Customizing Look and Feel, Part I - CSS
Tom M. Yeh, Potix Corporation
March 3, 2006
Applicable to ZK 2.1 and later.
The Purpose
This is the first article in a series of small talks to illustrate how to customize the look and feel of ZK components. In this article, we talk about how to customize components by use of CSS styles and classes.
The Basics
Each component has three attributes to control the look and feel: style, sclass and mold. The style attribute could be any valid CSS style, while the sclass could be any valid CSS class name. The mold attribute is a bit sophisticated, which will be discussed in the next article.
- CSS Styles
For example, we could add border and background to a label as follows.
<label value="Hello, World!"
style="border: 1px outset;background-color:yellow;padding:5px"/>
- CSS Classes
Similarly, we could specify the name of a CSS class to the sclass attribute.
<button label="OK" sclass="blue"/>
Then, we have to provide a definition of the class called blue.
- Embedded CSS into ZUML Pages
- To embed CSS styles, you can use the style component as follows.
<window title="CSS Class">
<style>
.blue {
color: white; background-color: blue;
}
</style>
<button label="OK" sclass="blue"/>
</window>
- Link an External CSS file
- Sometimes it is better to store all CSS definitions in an independent file, say my.css. Then, we could reference it by use of the style component as follows.
<style src="/my.css"/>
Customize Components for the Whole Page
Since 1.2 RC2, developers could override the definitions of components used in the whole page, such that you don't need to specify them one by one.
<?component name="button" extends="button" sclass="blue"?>
<button label="OK">
where
- The component directive (<?component?>) defines a component. The extends attributes works the same as Java's extends. If specified, the new component is derived from the specified one.
- The component directive affects the whole page, such that the sclass property, in this example, will be initialized with "blue" for any buttons in this page. Of course, you can change it later.
Customize Components for the Whole ZK Application
Sometime we want the same kind of components to have the same appearance in the whole application. It can be done by specify the sclass attribute for each of them when it appears. Fortunately, ZK has a better way to do it.
First, you have to prepare a XML file, called language addon. A language addon is used to add additional components, or to extend the definitions of existent component.
We illustrated how to add a new component by a language addon in anther small talks: Integrating FCKeditor. Here we will learn how to extend an existent definition.
<language-addon>
<addon-name>my-theme</addon-name>
<language-name>xul/html</language-name>
<component>
<extends>button</extends>
<component-name>button</component-name>
<property>
<property-name>sclass</property-name>
<property-value>blue</property-value>
</property>
</component>
</language-addon>
<addon-name>
The name of this language addon.
<language-name>
Specifies the language to which the components shall be added.
- A language is defined by a file called lang.xml. Its format is similar but it assumes the specified language doesn't exist yet.
<component>
Defines a new component. If the child element called extends works the same as Java's extends. In this case, we have to specify extends, because we want to change one of its property: sclass.
- Add the Language Addon to ZK
After preparing lang-addon.xml, we have to tell ZK to load the file when booting up.
In Integrating FCKeditor, we illustrated how to specify lang-addon.xml in a Jar file. Here we illustrated an alternative: specify it in WEB-INF/zk.xml as follows.
<zk>
<language-config>
<addon-uri>/WEB-INF/lang-addon.xml</addon-uri>
</language-config>
</zk>
where
- WEB/zk.xml is optional and used to configure ZK if specified.
- You could specify any number of language adds by adding more <addon-uri> elements.
Specifying the language addon in WEB-INF/zk.xml is better for Web developers because all files and configuration are under the same WAR file. On the other hand, specifying the addon in a JAR file is better for component developers, because it is easier to distribute and install.
Customize Not Just Look and Feel
If you look into lang.xml in the source codes of zul.jar, you'll find there are a lot of stuffs you can do. For example, you could replace all Java class of the window component, or adding a special window.
<component><-- Override Java class for all window components -->
<extends>window</extends>
<component-name>window</component-name>
<component-class>MyWindow</component-class>
</component>
<component><-- Override Java class and give it a new name -->
<extends>window</extends>
<component-name>mywindow</component-name>
<component-class>MyWindow</component-class>
</component>
<component><-- Adds a brand-new component -->
<component-name>overlap</component-name>
<component-class>MyOverlappedWindow</component-class>
<mold>
<mold-name>default</mold-name>
<mold-uri>/my/beatifulwindow.dsp</mold-uri>
</mold>
</component>
Summary
1. Use the style and sclass attribute to customize the look and feel of particular components.
2. Use a language addon to change the look and feel of all instances of a particular type of components.
3. Use a language addon to change the behaviors of all instances of a particular type of components.
Update History
1. July 20, 2006: Upgrade to ZK 2.1 by use of the style component.
2. June 13, 2006: Upgrade to ZK 2.0 by use of extends.
3. April 3, 2006: Use WEB/zk.xml to specify language addons (to be compatible with 1.2.0 RC).
4. April 15, 2006: Use extend instead of override (to be compatible with 1.2.0).
5. April 18, 2006: Use the component directive (new feature introduced since 1.2.0 RC2).
| Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License. |