Create a Custom iDempiere UI Theme using OSGi Fragment
Create a Custom iDempiere UI Theme using OSGi Fragment
This Folder is copy from iceblue_c fragment project
Overview
This guide explains how to convert the iDempiere UI theme into an independent OSGi Fragment and customize it under your own module name. This approach isolates UI customization into a single plugin, making upgrades and maintenance easier.
Template Repository: https://github.com/tm731531/tw.idempiere.UI.customer.theme/tree/main
1. Clone the Base Template
Clone the project and rename the folder to your preferred theme name:
tw.idempiere.UI.<your_theme_name>.theme
2. Update Project Metadata
2.1 Update .project
Ensure the Eclipse project name matches the folder name:
<name>tw.idempiere.UI.<your_theme_name>.theme</name>
2.2 Update .iml file
Rename the file to match your folder:
tw.idempiere.UI.<your_theme_name>.theme.iml
Update the source folder path:
<sourceFolder url="file://$MODULE_DIR$/src/web/theme/<your_theme_name>" type="java-resource" relativeOutputPath="web/theme/<your_theme_name>"/>.theme
3. Update OSGi Metadata (MANIFEST.MF)
Modify the following fields under META-INF/MANIFEST.MF:
Bundle-Name: iDempiere <your theme> Theme Bundle-SymbolicName: tw.idempiere.UI.<your_theme_name>.theme;singleton:=true Bundle-Vendor: <your company name> Automatic-Module-Name: tw.idempiere.UI.<your_theme_name>.theme
4. Rename the Theme Folder
Rename:
src/web/theme/customer
to:
src/web/theme/<your_theme_name>
This folder contains:
CSS
ZUL fragments
Images
JS resources
5. Update preference.zul
Set your theme name:
var setZkTheme = "<your_theme_name>";
This value must match the folder name inside /theme/<your_theme_name>.
6. Update ZUL Macro Paths
Update the macroURI paths in the following files:
login.zul
login-info.zul
login-left.zul
login-links.zul
vendor-logo.zul
desktop.zul
Example:
<include src="~./theme/customer/zul/desktop/header.zul" id="northBody"/>
Change to:
<include src="~./theme/<your_theme_name>/zul/desktop/header.zul" id="northBody"/>
Replace every customer with your theme name.
7. Modify Css or ZUL
Modify UI or Css style or js
8. Build and Deploy the Fragment
Export the fragment as a deployable plugin
Open Felix Console → Bundles
Upload the JAR file
Confirm the status is Installed or Resolved
9. Enable the Theme in iDempiere
Navigate to:
System Configurator → ZK_THEME
Change value:
iceblue_c → <your_theme_name>
10. Refresh WebUI
Return to Felix console
Refresh the fragment (or restart host bundle)
Reload the WebUI
Your new theme should now be applied.
Notes
This fragment attaches to org.adempiere.ui.zk
No core modification required
Fully upgrade-safe
Only UI/CSS/ZUL customization should be inside this fragment
