Difference between revisions of "Theme Management"

From ADempiere
Jump to: navigation, search
This Wiki is read-only for reference purposes to avoid broken links.
m (Intermediate save)
m (Removed theme development info to another page.)
 
Line 4: Line 4:
 
[[Category:Table of Contents]]
 
[[Category:Table of Contents]]
 
{{Note|This applies to the ZK 7 upgrade to 380RC1.}}
 
{{Note|This applies to the ZK 7 upgrade to 380RC1.}}
−
ADempiere has two user interfaces, a client GUI based on the java Swing system and a web based application which uses ZK.  The look and feel of both interfaces could be modified to apply custom skins.  This document describes how the ZK themes are managed following the upgrade to ZK7.
+
ADempiere has two user interfaces, a client GUI based on the java Swing system and a web based application which uses ZK.  The look and feel of both interfaces could be modified to apply custom skins.  This document describes how the ZK themes are managed following the upgrade to ZK7.  
 +
 
 +
For information on developing themes in ADempiere, see [[ZK Theme Development]].
  
 
== Overview ==
 
== Overview ==
Line 64: Line 66:
 
  ZK_LOGO_SMALL_IMAGE = "~./images/logo-small.png";
 
  ZK_LOGO_SMALL_IMAGE = "~./images/logo-small.png";
 
  ZK_BROWSER_ICON_IMAGE = "~./images/icon.png";
 
  ZK_BROWSER_ICON_IMAGE = "~./images/icon.png";
−
 
−
== Developing Themes ==
 
−
=== ZK Configuration ===
 
−
The following changes have been made to the ZK files to enable custom themes:
 
−
* In zkwebui/WEB-INF/zk.xml, a custom theme provider is defined and a number of development settings added.  In production environments, these need to be tailored appropriately.
 
−
 
−
<desktop-config>
 
−
    <theme-provider-class>org.adempiere.webui.theme.AdempiereThemeProvider</theme-provider-class>
 
−
</desktop-config>
 
−
 
−
<!-- turn off the floating scroll bar - behaviour is inconsistent. This can be removed after 7.02-->
 
−
<library-property>
 
−
                <name>org.zkoss.zul.nativebar</name>
 
−
                <value>true</value>
 
−
</library-property>
 
−
 
−
<!-- The name of the folder where the themes are stored under the root. "theme" is the default -->
 
−
<library-property>
 
−
                <name>org.zkoss.theme.folder.root</name>
 
−
                <value>theme</value>
 
−
</library-property>
 
−
 
−
<!-- Ensure that the basic default theme is selected.  This is a fall-back if the cookie method hasn't been used. -->
 
−
<library-property>
 
−
                <name>org.zkoss.theme.preferred</name>
 
−
                <value>adempiere_default</value>
 
−
</library-property>
 
−
 
−
<!-- Set to true in production environments -->
 
−
<library-property>
 
−
                <name>org.zkoss.web.classWebResource.cache</name>
 
−
                <value>false</value>
 
−
</library-property>
 
−
 
−
<!-- Set to true in production environments -->
 
−
<library-property>
 
−
<name>org.zkoss.zk.WCS.cache</name>
 
−
<value>false</value>
 
−
</library-property>
 
−
 
−
        <!-- set to a positive number or comment out in production environments.  Set to -1 in development. -->
 
−
<library-property>
 
−
                <name>org.zkoss.web.classWebResource.cache.CSS.hours</name>
 
−
                <value>-1</value>
 
−
</library-property>
 
−
 
−
=== The Theme Folder Structure ===
 
−
Themes can be added to the application as folders or jar files.  Theme Jar files can be saved in a number of locations but the zkwebui/WEB-INF/lib/theme folder is a good choice.
 
−
The folder structure is more powerful and allows for greater flexibility in managing the theme.  By the library property set in zk.xml, the theme folder is zkwebui/theme. (This is the zk default name so the entry in the zk.xml file is not really needed but is there in case of changes.) Under that folder are theme specific folders which follow a standard structure.
 
−
 
−
-zkwebui
 
−
    |-theme
 
−
        |-<theme name>
 
−
            |-images
 
−
            |-js
 
−
            |-zkex
 
−
            |-zkmax
 
−
            |-zul
 
−
                |-css
 
−
                    ext.css.dsp
 
−
                    norm.css.dsp
 
−
                    zk.wcs
 
−
                |-html
 
−
                |-img
 
−
                |-less
 
−
                    |-font
 
−
                    _header.less
 
−
                    _reset.less
 
−
                    _zkmixins.less
 
−
                    _zkvariables.less
 
−
                    norm.less
 
−
                login-info.zul
 
−
                ...
 
−
{{Note|"zkex" and "zkmax" folders relate to theme elements that are only available with the ZK Premium and Enterprise Edition. They are included in case of upgrades.)
 
−
The images and *.zul files in the zul directory have been added and are theme specific.  The rest of the structure is defined by zk and is part of the language definition "xul/html". This language defines all the component styles that need to be included in a Widget CSS descriptor (WCS) file - zk.wcs.  Edits to the .less files, once compiled to .css.dsp, will be picked up and included in the zk.wcs file. 
 
−
{{Note|Adding new components to this structure requires a modification of the language definition. See the ZK documentation for more info.}}
 
−
The most important file in this structure is _zkvariables.less.  This file contains theme specific variables such as colors and sizes that enable the full power of the less css preprocessor.  For example, the two themes adempiere_default and green_thumb differ only in the settings of this file.
 
−
 
−
=== Creating A New Theme ===
 
−
To create a new theme:
 
−
* Copy the adempiere_default folder under the theme directory and rename it to a suitable name. Alternatively, generate the folder structure from zk sources directly, such as a maven project, git or extract a jar.  You can also use a jar file if you don't intend to modify the components.
 
−
* Log in to ADempiere as the System Administrator and create a new theme in the {{MenuRef|Application Dictionary|Theme Management}} window.  Set the fields accordingly.
 
−
* Copy/create any external .less files and modify them as required.  These should be stored in the zkwebui/less folder.
 
−
* Edit the build-lesscss.xml file to add a target for your new theme.
 
−
* Build the ADempiere application and launch the server.  The new theme should be available as a user preference or as the system default depending on how the Theme Management fields were set.
 
−
 
−
=== Adding External less/css Files ===
 
−
Additional css files can be added to the theme by including them as resources in the Theme Resources tab of the {{MenuRef|Application Dictionary|Theme Management}} window.
 
−
 
−
Styles in these files can override the styles in the theme-specific zk.wcs file.  Changes to these files will be posted to the server once saved and the changes will be visible when the browser is refreshed.  It is strongly suggested that .less files be used to generate the css files as it is much easier to maintain .less files.  Less files can be stored in the zkwebui/less folder and the output css.dsp files will be saved in the css folder using the same file name.
 
−
 
−
=== Compiling less to css.dsp ===
 
−
To aid in compiling less files to css.dsp files, a ANT build file has been added to the zkwebui folder - build-lesscss.xml.  This file includes targets to compile the external css and/or the individual theme folders.  Developers will find it helpful to create External Tool Configurations for these targets.
 
−
 
−
Changes to the external .less files can be compiled and are published on the fly so the update is available by refreshing the browser.  Changes to the .less files in the theme folders require the server to be republished.  (If someone could figure out how to do this on the fly, it would be helpful.)
 
−
 
−
=== Using less To Override A zk Style or Create a New Component ===
 
−
lesscss is a powerful tool.  To learn more about its capabilities, visit the [http://lesscss.org lesscss.org] website or search for the numerous articles on its features on the web.
 
−
 
−
As an example of what it can do, here is the less code that is used to style the ADempiere Search Editor:
 
−
 
−
<pre>
 
−
.ad-search-editor,
 
−
.ad-number-editor,
 
−
.ad-pattribute-editor {
 
−
 
−
// Search box
 
−
border: none;
 
−
padding: 0px;
 
−
margin: 0px;
 
−
background-color: transparent;
 
−
 
−
// String style = AEnv.isFirefox2() ? "display: inline"
 
−
// : "display: inline-block";
 
−
// style = style
 
−
// + ";border: none; padding: 0px; margin: 0px; background-color: transparent;";
 
−
 
−
table {
 
−
border: none;
 
−
padding: 0px;
 
−
margin: 0px;
 
−
width: 100%;
 
−
cellpadding: 0;
 
−
cellspacing: 0;
 
−
}
 
−
 
−
tr {
 
−
width: 100%;
 
−
border: none;
 
−
padding: 0px;
 
−
margin: 0px;
 
−
white-space:nowrap;
 
−
}
 
−
 
−
.z-textbox {
 
−
.leftBorderRadius(@borderRadiusSmall);
 
−
    display: inline;
 
−
    width: 100%;
 
−
}
 
−
 
−
.editor-button {
 
−
.iconFontStyle(@baseFontSize, @iconColor);
 
−
width: @baseButtonWidth;
 
−
<c:if test="${ zk.ie == 8 }">
 
−
width: @baseButtonWidth - 10;
 
−
</c:if>
 
−
height: @baseButtonHeight;
 
−
.rightBorderRadius(@borderRadiusSmall);
 
−
padding: 0px;
 
−
line-height: @baseLineHeight;
 
−
background: @inputBackgroundColor;
 
−
text-align: center;
 
−
vertical-align: middle;
 
−
overflow: hidden;
 
−
cursor: pointer;
 
−
 
−
&:hover {
 
−
border-color: @hoverBorderColor;
 
−
<c:if test="${ zk.ie != 8 }">
 
−
.verGradient(@hoverGradientStart, @hoverGradientEnd);
 
−
</c:if>
 
−
}
 
−
&:active {
 
−
border-color: @activeBorderColor;
 
−
<c:if test="${ zk.ie != 8 }">
 
−
.verGradient(@activeGradientStart, @activeGradientEnd);
 
−
</c:if>
 
−
.boxShadow('inset 1px 1px 1px #91AAB7');
 
−
}
 
−
input[disabled] + & {
 
−
&:hover,
 
−
&:active {
 
−
border-color: @inputBorderColor;
 
−
.resetGradient();
 
−
.boxShadow('none');
 
−
}
 
−
}
 
−
 
−
img {
 
−
vertical-align: middle;
 
−
text-align: center;
 
−
}
 
−
}
 
−
}
 
−
</pre>
 
−
 
−
* Adding class styles in code
 
−
* DefautlTheme
 
−
* ThemeUtils
 
−
* MTheme
 

Latest revision as of 07:08, 23 June 2014

⇐ Table of Contents{{#if: | | [[{{{2}}}]] }}{{#if: | | [[{{{3}}}]] }}{{#if: | | [[{{{4}}}]] }}{{#if: | | [[{{{5}}}]] }} | Theme Management{{#if: | | [[{{{next}}}]] }} ⇒

Note.gif Note:

This applies to the ZK 7 upgrade to 380RC1.

ADempiere has two user interfaces, a client GUI based on the java Swing system and a web based application which uses ZK. The look and feel of both interfaces could be modified to apply custom skins. This document describes how the ZK themes are managed following the upgrade to ZK7.

For information on developing themes in ADempiere, see ZK Theme Development.

Overview

The theme system is a major enhancement in ZK7 and allows developers to easily create and apply themes to the application through customized Cascading Style Sheet (CSS) files. In ZK7, the processes of creating the CSS files and managing the collection of files has been improved by the adoption of a CSS preprocessor known as "less". Less allows the developer to use variables and functions to simplify the creation of the css files. Please refer to the ZK documentation ([www.zk.org www.zk.org]) and the less documentation ([lesscss.org lesscss.org]) for more about their capabilities.

Note.gif Note:

Adempiere has been integrated with the Community Edition (CE) of ZK7 which provides access to the ZK source. The Enterprise Edition (EE) includes responsive design elements for tablets. Developers can integrate this additional functionality for a fee.

In ADempiere, the ZK theme systems and less have been incorporated to allow developers to create new themes, define system defaults and also to provide users with a means of selecting a theme or preference. Themes are stored in jar files or as folder structures in the zkwebui/theme directory. If no theme folder is provided, the internal Breeze theme will be used. To customize the look and feel, add new styles and override the ZK styles, additional css files can be applied in addition to the main theme. These additional files are injected or added to the page when it is rendered.

Theme Management

There is one default theme "adempiere_default" which is very similar to the Breeze theme in look and feel. The application will fall back to this theme if no other system defaults are defined. With the Application Dictionary{{#if: Theme Management | →Theme Management }}{{#if: | → }}{{#if: | → }} window, additional themes can be defined and made available to the system. The process is as follows:

  • Copy one of the existing themes to a new folder under the zkwebui/theme directory. The folder name will be the new theme name. The path prefix "~./" is used to indicate the current theme so files within this new folder can be found.
  • Modify the less files within this folder structure as required to customize the theme. Most of the customization can be done within the ~./zul/less/_zkvariables.less file. This file contains the colors, sizes and that will be used by the rest of the theme system.
  • Create additional less files to override and add new styles as required. These can be saved in the zkwebui/less directory. When compiled, these files will create css.dsp files in the zkwebui/css directory.
Note.gif Note:

Developing a theme by customizing the CSS files within the theme folder is not very friendly. It is easier to develop the required styles outside the folder as these can be compiled by less and applied by refreshing the browser. Alternatively, the developer can explore integrating less in the browser. Neither route is ideal for production so the customizations should be moved into the folder structure where applicable. On page load, all the css.dsp files that are part of the language definition are loaded into a single zk.wcs file which can be cached at the browser to improve performance.

  • In ADempiere, log in as System and access the Application Dictionary{{#if: Theme Management | →Theme Management }}{{#if: | → }}{{#if: | → }} window. Here you can define the key elements of the theme:
    • Theme Name - same as the folder name (adempiere_default)
    • Display Name - the string to use to identify the theme (Adempiere Default)
    • The origin of the theme - Folder or Jar
    • The priority for the theme - used if to select the theme from all those registered if there is no default defined or multiple defaults defined.
    • If the theme is a default theme - used by the logon window and as a user default.
    • Whether the theme should be cached or not. Deselect this during development and select it in production.
    • The cache hours - the length of time the browser is allowed to keep the cached theme files.
    • Locations for some of the key resources such as the favicon and logo image files.
  • In the Theme Resource tab, add the path(s) to any additional CSS files or resources required by the theme. These will be added to the page header.

ThemeManagement.png

The Theme Resource tab defines additional URIs that can be added to the page header when the theme is being used. These will typically be the .css.dsp files that override the zk styles or add additional functionality. The URIs are injected into the page header by the theme provider (org.adempiere.webui.theme.AdempiereThemeProvider.java).

ThemeResources.png

Changing Themes

Themes can be changed in a number of ways:

  • Users can select a theme based on the user preferences. The theme will switch from the system default to the user theme during the login process.
  • Use the Theme Management window to define a default theme which will be the system default and the default for all users who have not selected a preference. The system default theme will be used during the login process. This provides a way to private-label the application or make an implementation client specific.
  • Remove all records in the Theme Management window or uncheck the default. The system will fall back to constants defaults in the System Configurator.
  • If there are no values saved in the System Configurator, the application will use the definition in DefaultTheme.java which is the default ADempiere theme.

User Preferences

Users can select themes using the Preferences button/link at the top right once they are logged in. Saving the preference will load the theme and refresh the current page to use the selected theme.

Changing Theme.jpg

System Configurator Settings

ADempiere System Configurations can be used to define a default theme. These values will be used if there are no default themes defined in the Theme Management window. The text following the configurator name is the system default that will be used if the configurator is not defined. See DefaultTheme.java form more comments. 

ZK_DEFAULT_THEME_NAME 		= "adempiere_default";	// Should match the folder name
ZK_DEFAULT_THEME_DISPLAY 	= "Adempiere";		// Used as a title in about windows.
ZK_DEFAULT_THEME_ORIGIN 	= "FOLDER";	// FOLDER or JAR. See http://www.zkoss.org/javadoc/7.0.1/zk/org/zkoss/web/theme/StandardTheme.ThemeOrigin.html
ZK_DEFAULT_THEME_PRIORITY 	= 1000;	// Integer priority
ZK_DEFAULT_THEME_URI		= "/css/adempiere_default.css.dsp"; // A single resource only. For multiple resources, use the Theme Management window.
ZK_BROWSER_TITLE		= "ADempiere";  // Will appear in the Browser tab
ZK_LOGIN_TOP_PANEL_ZUL 		= "~./zul/login-top.zul";
ZK_LOGIN_BOTTOM_PANEL_ZUL 	= "~./zul/login-bottom.zul";
ZK_LOGIN_LEFT_PANEL_ZUL 	= "~./zul/login-left.zul";
ZK_LOGIN_RIGHT_PANEL_ZUL 	= "~./zul/login-right.zul";
ZK_LOGO_LARGE_IMAGE 		= "~./images/logo-large.png";
ZK_LOGO_SMALL_IMAGE 		= "~./images/logo-small.png";
ZK_BROWSER_ICON_IMAGE		= "~./images/icon.png";
Retrieved from "http://www.adempiere.com/index.php5?title=Theme_Management&oldid=29191"