ZK^TM Small Talks

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.

Version

Applicable to ZK 2.1 and later.

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>
  </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 © 2005-2006 Potix Corporation. All rights reserved.