Developing Plug-Ins - WebUI Themes
Customize the web user interface using an OSGi Fragment-Project by replacing the original images with your own images or changing the CSS.
This tutorial is brought to you by Jan Thielemann from evenos GmbH (www.evenos-consulting.de). If you have questions, criticism or improvement suggestions, feel free to visit me (Jan.thielemann) or write me an email
Before you start developing plug-ins, you should take a look at Developing Plug-Ins without affecting trunk, Get your Plug-In started and Developing Plug-Ins - Export Plug-Ins and Fragments to get a good starting point.
Create a fragment
New Fragment project
File > New > Other > Plug-in Development > Fragment Project >
Name: org.evenos.newtheme Location: don't use default location, keep plug-ins in a separate directory Target Platform: OSGi Equinox
Execution environment: JavaSE-1.7 (or whatever) Host Plug-in: browse to org.adempiere.ui.zk
Create the new theme based on the iDempiere default theme:
- create a new folder under the project called theme. In this folder, create sub-folder with a name of your choice, e.g. newtheme, which will be the name of the theme
- copy all the resources from org.adempiere.ui.zk/theme/default and paste them into the folder of your personal theme in your fragment, namely org.evenos.webui/theme/newtheme
- replace the images in "theme/newtheme/images" or amend CSS files
Note: Some of the .zul files in /theme/newtheme/zul have hard coded paths to their resources so you may have to change the file paths there if necessary.
Configure the manifest
The next step is to configure the manifest to add the theme to the classpath, so open your MANIFEST.MF and:
- in the Overview tab, select "This fragment is a singleton"
- switch to the Runtime tab, scroll down to the Classpath section, click on the Add button and select the theme folder from the list to add it to the classpath
- in the Build tab, make sure the theme is checked under Binary Build
- in the MANIFEST.MF tab, add this line to the headers, and press Enter (the manifest must end with a newline):
Save the manifest.
Local testing in Eclipse
To test the theme fragment in Eclipse:
- open Run Configurations
- select the server.product, switch to the Plug-ins tab and check your theme fragment to activate it
- switch to the Arguments tab and add this to the VM arguments list:
Now you can run the server.
You must update the System Configurator with the details of the new theme, so log into the webui as SuperUser and System role, open up the System Configurator window and search for "ZK_THEME". Change the Configured Value from "default" to "newtheme" and save.
Note that you can also change the browser title here by adding a new keyword ZK_BROWSER_TITLE and entering the new title in the Configured Value.
To use the new theme, just click on Change Role and select the same role to prompt iDempiere to use the new settings and images.
Install on the server
Once you are done, you can export your theme fragment by creating a new feature project, or by using an existing one, or by right-clicking the fragment and exporting it as "Deployable plug-ins and fragments" under "Plug-in Development".
Follow the tutorial about getting your plug-ins running to install the fragment on the server.
Once you are done, you have to do some additional steps:
- make sure that your fragment was installed and resolved in the Apache Felix Web Console by checking that the state is Fragment (refresh the package if not)
- refresh the bundle org.adempiere.ui.zk to apply the changes
- log into the webui as SuperUser with the System role, open up the System Configurator window and search for "ZK_THEME". Change the Configured Value from "default" to "newtheme" and save
- select 'Change Role' to load the new theme.
If the new theme and/or images do not change, flush your browser cache to get rid of cached images. Recycle the whole application if necessary.