This page contains outdated information

Purpose

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

Prerequisites

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.

tl;dr

https://www.youtube.com/watch?v=DHD6bQFxCMs

The workflow

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

Next >

Execution environment: JavaSE-1.7 (or whatever)
Host Plug-in: browse to org.adempiere.ui.zk

Finish >

New theme

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):

Jetty-WarFragmentFolderPath: /

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:

-DZK_THEME=newtheme

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.

Developing Plug-Ins - WebUI Themes