The Developer's Guide

By default, the scripting language is assumed to be Java. However, you can select different language by specifying the language attribute as follows. The language attribute is case insensitive.

<zscript language="javascript">
    alert('Say Hi in JavaScript');    
    new Label("Hi, JavaScript!").setParent(win);    
</zscript>

To specify the scripting language for an event handler, you can prefix with, say, javascript: as follows. Notice: don't put whitespace before or after the language name.

<button onClick="javascript: do_something_in_js();"/>

You may have the script codes writing in different scripting languages in the same page.

To separate codes and views, developers could put the scripting codes in a separated file, say sayHello.zs, and then use the src attribute to reference it.

<window title="Hello" border="normal">
    <button label="Say Hello" onClick="sayHello()"/>    
    <zscript src="sayHello.zs"/>    
</window>

which assumes the content of sayHello.zs is as follows.

int count = 0;
void sayHello() { //declare a global function
    alert("Hello World! "+ ++count);    
}

If you prefer not to use any Java codes in the ZUML pages, you can extend the implementation of a component to handle the events as follows.

import org.zkoss.zul.Window;

public class MyWindow extends Window {
    public void onCreate() { //does initialization    
    }    
    public void onOK() { //save the result    
    }    
    public void onCancel() { //cancel any changes    
    }    
}

Then, specify the class with the use attribute as shown below.

<window use="MyWindow">
    ...    
</window>

If you prefer the MVC (Model-View-Controller) approach, i.e., you prefer not to embed the handling codes in the window (the view), you can implement a class to initialize the window. The class must implement the org.zkoss.zk.ui.util.Composer interface.

import org.zkoss.zk.ui.util.Composer;
import org.zkoss.zul.Window;
public class MyComposer implements Composer {
    public void doAfterCompose(Component comp) {    
        ((Window)comp).setTitle("My Title"); //do whatever initialization you want        
            //comp is Window since we will specify it to a window later            
    }    
}

where assumes you have three event listeners, MyCreate, MyOK, and MyCancel. Refer to the Event section below for the explanation of event listeners.

Then, specify the class with the apply attribute as shown below.

<window apply="MyComposer">
...
</window>

The window is still created as an instance of org.zkoss.zul.Window, and it will be passed to the doAfterCompose method as the comp argument. Then, you can do any initialization you want.

If you want to apply multiple composers, separate them with comma. In addition, you can use an EL expression to return the class, its name, an instance of Composer, or a collection of Composer instances.

<window apply="MyComposer, AnotherComposer">
    <textbox apply="${c:mycomposer()}"/>    
</window>

Thanks to the power of BeanShell^[14], the implementation of Java classes can be done in zscript as follows.

<zscript>
    public class MyWindow extends Window {    
    }    
</zscript>
<window use="MyWindow"/>

Tip: Many scripting languages, e.g., JRuby, also allow developers to define classes that are accessible by JVM. Please consult the corresponding manuals for details.

To separate codes from the view, you can put all zscript codes in a separated file, say mywnd.zs, and then,

<zscript src="/zs/mywnd.zs"/>
<window use="MyWindow"/>

Tip: You can use the init directive to specify a zscript file, too. The difference is the init directive is evaluated before any component is created (in the Page Initial phase). For more information, refer to the init Directive section in the ZK User Interface Markup Language chapter.

For developers who preferred not to use ZUML at all, they can use the so-called richlet to create all components manually.

import org.zkoss.zul.*;
public class TestRichlet extends org.zkoss.zk.ui.GenericRichlet {
    public void service(Page page) {    
        page.setTitle("Richlet Test");        

        final Window w = new Window("Richlet Test", "normal", false);        
        new Label("Hello World!").setParent(w);        
        final Label l = new Label();        
        l.setParent(w);        
        //...        
        w.setPage(page);        
    }    
}

Refer to the Richlets section in the Advanced Features chapter.

A component is an UI object, such as a label, a button and a tree. It defines the visual presentation and behaviors of a particular user interface. By manipulating them, developers control how to represent an application visually in the client.

A component must implement the org.zkoss.zk.ui.Component interface.

A page (org.zkoss.zk.ui.Page) is a collection of components. A page confines components belonging to it, such that they will be displayed in a certain portion of the browser. A page is automatically created when ZK loader interprets a ZUML page.

<?page title="My Page Title"?>

A ZUML page might include another ZUML pages directly or indirectly. Since these pages are created for serving the same URL request, they are collectively called a desktop (org.zkoss.zk.ui.Desktop). In other word, a desktop is a collection of pages for serving the same URL request.

As a ZK application interacts with user, more pages might be added to a desktop and some might be removed from a desktop. Similarly, a component might be added to or removed from a page.

A component has at most one parent. A component might have multiple children. Some components accept only certain types of components as children. Some must be a child of certain type of components. Some don't allow any child at all. For example, Listbox in XUL accepts Listcols and Listitem only. Refer to Javadoc or XUL tutorials for details.

A component without any parent is called a root component. A page might have multiple root components, which could be retrieved by the getRoots method.

Besides being a Java object in the server, a component has a visual part^[22] in the browser, if and only if it belongs to a page. When a component is attached to a page, its visual part is created^[23]. When a component is detached from a page, its visual part is removed.

There are two ways to attach a component into a page. First, you could call the setPage method to make a component to become a root component of the specified page. Second, you could call the setParent, insertBefore or appendChild method to make it to become a child of another component. Then, the child component belongs to the same page as to which the parent belongs.

Similarly, you could detach a root component from a page by calling setPage with null. A child is detached if it is detached from a parent or its parent is detached from a page.

Each component has an identifier (the getId method). It is created automatically when a component is created. Developers could change it anytime. There is no limitation about how an identifier shall be named. However, if an alphabetical identifier is assigned, developers could access it directly in Java codes and EL expression embedded in the ZUML page.

<window title="Vote" border="normal">
    Do you like ZK? <label id="label"/>    
    <separator/>    
    <button label="Yes" onClick="label.value = self.label"/>    
    <button label="No" onClick="label.value = self.label"/>    
</window>

A component has another identifier called UUID (Universal Unique ID), which application developers rarely need.

UUID is used by components and Client Engine to manipulate DOM at the browser and to communicate with the server. More precisely, the id attribute of a DOM element at the client is UUID.

UUID is generated automatically when a component is created. It is immutable, except the identifiers of components for representing HTML tags.

HTML relevant components handle UUID different from other set of components: UUID is the same as ID. If you change ID of a HTML relevant component, UUID will be changed accordingly. Therefore, old JavaScript codes and servlets will remain to work without any modification.

To let the interpreter able to access the components directly, the namespace concept (org.zkoss.scripting.Namespace) is introduced. First, each ID space has exactly one namespace. Second, variables defined in a namespace are visible to the scripting codes and EL expressions that belong to the same namespace.

<window border="normal">
    <label id="l" value="hi"/>    
    <zscript>    
        l.value = "Hi, namespace";        
    </zscript>    
    ${l.value}    
</window>

In the following example, there are two namspaces. One belongs to window w1 and the other to window w2^[24]. Thus, the b1 button's onClick script refers to the label defined in window w1, while the b2 button's onClick script refers to the checkbox defined in window w2.

<window id="w1">
    <window id="w2">    
        <label id="c"/>        
        <button id="b1" onClick="c.value = &quot;OK&quot;"/>        
    </window>    
    <checkbox id="c"/>    
    <button id="b2" onClick="c.label = &quot;OK&quot;"/>    
</window>

Notice the namespace is hierarchical. In other words, zscript in window w2 can see components in window w1, unless it is overridden in window w2. Thus, clicking button b1 will change label c in the following example.

<window id="w1">
    <window id="w2">    
        <button id="b1" onClick="c.value = &quot;OK&quot;"/>        
    </window>    
    <label id="c"/>    
</window>

In addition to ZK's assigning components to the namespace, you can assign your variables to them by use of the setVariable method, such that zscript can reference them directly.

In addition to executing codes, you could define variables and functions in the zscript element directly as depicted below.

<window id="A>
    <zscript>    
        Object myvar = new LinkedList();        
        void myfunc() {        
            ...            
        }        
    </zscript>    
    ...    
    <button label="add" onClick="myvar.add(some)"/>    
    <button label="some" onClick="myfunc()"/>    
</window>

The variables and methods defined in zscript are stored in the interpreter of the corresponding scripting language.

<window>
    <zscript>    
    String var = "abc";    
    self.setVariable("var2", "xyz", true);    
    </zscript>    
    ${var} ${var2}    
</window>

<window>
abc xyz
</window>

<window>
    <zscript>    
    String var = "abc";    
    self.setVariable("var", "xyz", true);    
    </zscript>    
    ${var}    
</window>

<window>
abc
</window>

<window>
    <zscript>    
    String var = "abc";    
    </zscript>    
    <label id="var" value="A label"/>    
    ${var.value} <!-- Wrong! var is "abc", not the label -->    
</window>

<zscript>
Date now = new Date();
</zscript>

<zscript>
{ //create a new logic scope
    String var = "abc"; //visible only inside of the enclosing curly brace    
}
</zscript>

<window id="A">
    <zscript>var1 = "abc";</zscript>    
    <window id="B">    
        <zscript>var2 = "def";</zscript>        
    </window>    
</window>

<window id="A">
    <window id="B">    
        <zscript>        
    String b = "local to window B";    
        </zscript>        
    </window>    
</window>

<window id="A">
    <zscript>    
    var1 = var2 = "abc";    
    </zscript>    
    <window id="B">    
        <zscript>        
    Object var1 = "123";    
    var2 = "def";    
    var3 = "xyz";    
        </zscript>        
    </window>    
    ${var1} ${var2} ${var3}    
</window>

<zscript language="Java">
    var1 = 123;    
</zscript>
<zscript language="JavaScript">
    var2 = 234;    
</zscript>

<zscript>
    var1 = 123; //var1 belongs to the interpreter, not any namespace    
    page.getVariable("var1"); //returns null    
</zscript>

page.getInterpreter("JavaScript").getVariable("some"); //interpreter for JavaScript
page.getInterpreter(null).getVariable("some"); //interpreter for default language

When a component is created in an event listener, it is assigned automatically to the associated desktop of the event being processed. This assignment happens even if the component is not attached to a page. It means that any component you created in an event listener can be used in the same desktop that the listener is handling.

When a component is created in a thread other than any event listener, it doesn't belong to any desktop. In this case, you could attach to any desktop you want as long as the attachment occurs in a proper event listener. Of course, once the component is attached to a desktop, it belongs to the desktop forever.

For most applications, it is rarely necessary to create components in a thread other than event listeners. However, if you have a long operation, you might want to execute it in a background thread. Then, you could prepare the component tree at the background and then add it to a desktop when a proper event is received. Refer to the Long Operations section in the Event Listening and Processing chapter.

In this phase, ZK processes the processing instructions, called init. If none of such processing instructions are defined, this phase is skipped.

For each init processing instruction with the class attribute, an instance of the specified class is constructed, and then its doInit method is called. What the class will do, of course, depends on your application requirements.

<?init class="MyInit"?>

Another form of the init processing instruction is to specify a file containing the scripting codes with the zscript attribute, as follows. Then, the file will be interpreted at the Page Initial phase.

<?init zscript="/my/init.zs"?>

Notice that the page is not yet attached to the desktop when the Page Initial phase executes.

In this phase, ZK loader interprets an ZUML page. It creates and initializes components accordingly. It takes several steps as follows.

Note: an developer can perform some application-specific initialization by listening to the onCreate event or implementing AfterCompose. AfterCompose is called in the Component Creation Phase, while the onCreate event is handled by an event listener.

An event listener is free to suspend and resume the execution (such as creating modal dialogs), while AfterCompose is a bit faster since no need to fork another thread.

In this phase, ZK invokes each listener for each event queued for this desktop one-by-one.

An independent thread is started to invoke each listener, so it could be suspended without affecting the processing of other events.

During the processing, an event listener might fire other events. Refer to the Event Listening and Processing chapter for details.

After all events are processed, ZK renders these components into a regular HTML page and sends this page to the browser.

To render a component, the redraw method is called. The implementation of a component shall not alter any content of the component in this method.

Depending on the request, ZK AU Engine might update the content of affected components such that their content are the same as what are shown at the client.

Then, it posts corresponding events to the queue.

This phase is the same as the Event Processing Phase in the Component Creation Phase. It processes events one-by-one in an independent thread.

After all events are processed, ZK renders affected components, generates corresponding ZK responses, and sends these responses back to the client. Then, Client Engine updates the DOM tree at the browser based on the responses.

Whether to redraw the whole visual presentation of a component or to update an attribute at the browser all depend on the implementation of components. It is the job of component developers to balance between interactivity and simplicity.

When overriding a component by use of your own class, you could declare a member function to be an event listener as follows.

In a ZUML page, you declare the use attribute to specify what class you want to use instead of the default one. As illustrated below, it asks ZK to use the MyWindow class instead of org.zkoss.zul.Window^[31].

<window use="MyWindow">
...
</window>

Then, you implement MyWindow.java by extending from the default class as follows.

public class MyWindow extends org.zkoss.zul.Window {
    public void onOK() { //add an event listener    
        ...//handles the onOK event (sent when ENTER is pressed)        
    }    
}

If you want to retrieve more information about the event, you could declare as follows.

public void onOK(org.zkoss.zk.ui.event.KeyEvent event) {...}

or

public void onOK(org.zkoss.zk.ui.event.Event event) {...}

Different events might be associated with different event objects. Refer to Append C for more details.

Developers could use the addEventListener and removeEventListener methods of the org.zkoss.zk.ui.Component interface to dynamically add or remove an event listener. As illustrated below, the event listener to be added dynamically must implement the org.zkoss.zk.ui.event.EventListener interface.

void init(Component comp) {
    ...    
    comp.addEventListener("onClick", new MyListener());    
    ...    
}
class MyListener implements org.zkoss.zk.ui.event.EventListener {
    public void onEvent(Event event) throws UiException {    
        ...//processing the event        
    }    
}

By default, events are sent the server when it is fired at the client. However, many event listeners are just used to maintain the status at the server, rather than providing visual response to the user. In other words, the events for these listeners have no need to be sent immediately. Rather, they shall be sent at once to minimize the traffic between the client and the server, and then to improve the server's performance. For the sake of the description convenience, we call them the deferrable event listeners.

To make an event listener deferrable, you have to implement the org.zkoss.zk.ui.event.Deferrable interface (with EventListener) and return true for the isDeferrable method as follows.

public class DeferrableListener implements EventListener, Deferrable {
    private boolean _modified;    
    public void onEvent(Event event) {    
        _modified = true;        
    }    
    public boolean isDeferrable() {    
        return true;        
    }    
}

When an event is fired at the client (e.g., the user selects a list item), ZK won't send the event if no event listener is registered for it or only deferrable listeners are registered. instead, the event is queued at the client.

On the hand, if at least one non-deferrable listener is registered, the event are sent immediately with all queued events to the server at once. No event is lost and the arriving order is preserved.

Tip: Use the deferrable listeners for maintaining the server status, while the non-deferrable listeners for providing the visual responses for the user.

Developers could add event listeners to a page (org.zkoss.zk.ui.Page) dynamically. Once added, all events of the specified name the are sent to any components of the specified page will be sent to the listener.

All page-level event listeners are non-ASAP. In other words, the isArap method is ignored.

A typical example is to use a page-level event listener to maintain the modification flag as follows.

public class ModificationListener implements EventListener, Deferrable {
    private final Window _owner;    
    private final Page _page;    
    private boolean _modified;    

    public ModificationListener(Window owner) {    
        //Note: we have to remember the page because unregister might        
        //be called after the owner is detached        
        _owner = owner;        
        _page = owner.getPage();        
        _page.addEventListener("onChange", this);        
        _page.addEventListener("onSelect", this);        
        _page.addEventListener("onCheck", this);        
    }    
    /** Called to unregister the event listener.    
     */    
    public void unregister() {    
        _page.removeEventListener("onChange", this);        
        _page.removeEventListener("onSelect", this);        
        _page.removeEventListener("onCheck", this);        
    }    
    /** Returns whether the modified flag is set.    
     */    
    public boolean isModified() {    
        return _modified;        
    }    
    //-- EventListener --//    
    public void onEvent(Event event) throws UiException {    
        _modified = true;        
    }    
    //-- Deferrable --//    
    public boolean isDeferrable() {    
        return true;        
    }    
}

Note: Whether to implement the Deferrable interface is optional in this example, because the page's event listeners are always assumed to be deferrable, no matter Deferrable is implemented or not.

The sequence of invoking event listeners is as follows. Let us assume the onClick event is received.

The org.zkoss.zk.ui.event.Express interface is a decorative interface used to alter the invocation priority of an event listener. Notice that it is meaningless if the event listener is added to pages, instead of components.

You could abort the calling sequence by calling the stopPropagation method in the org.zkoss.zk.ui.event.Event class. Once one of the event listeners invokes this method, all following event listeners are ignored.

By use of the postEvent method in the org.zkoss.zk.ui.event.Events class, the application could post an event to the end of the event queue. This method returns immediately after placing the event into the queue. The event will be processed later after all events preceding it have been processed.

By use of the sendEvent method in the org.zkoss.zk.ui.event.Events class, the application could ask ZK to process the specified event immediately. This method won't return until all event listeners of the specified event has been processed. The event is processed at the same thread.

By use of the echoEvent method in the org.zkoss.zk.ui.event.Events class, the application could ask the client to echo back the event for processing later. This method returned immediately after queuing the response asking the client to echo back the event.

Notice that, unlike sendEvent and postEvent, the event won't be processed in the current execution. Rather, it is processed later after the client echoes back the event. In other words, the event is processed later after the client has updated its user interfaces. Thus, it is useful to prompt the user before starting a long operation.

For example, you can open a highlighted window and then invoke echoEvent to do the long operation after the client shows the window (and echoes back the event).

For example, we can use the org.zkoss.zk.ui.util.Clients.showBusy method to show the busy message such that the user knows the system is busy. So, the end user will see "Execute..." first and then, after two seconds, "Done." in the following example. If you use postEvent, the end user will see "Execute..." and "Done" at the same time after two seconds.

<window id="w" title="Test echoEvent">
    <attribute name="onLater">    
    Thread.sleep(2000);    
    Clients.showBusy(null, false);    
    new Label("Done.").setParent(w);    
    </attribute>    

    <button label="echo">    
    <attribute name="onClick">    
    Clients.showBusy("Execute...", true);    
    Events.echoEvent("onLater", w, null);    
    </attribute>    
    </button>    
</window>

For advanced applications, you might have to suspend an execution until some condition is satisfied. The wait, notify and notifyAll methods of the org.zkoss.zk.ui.Executions class are designed for such purpose.

When an event listener want to suspend itself, it could invoke wait. Another thread could then wake it up by use of notify or notifyAll, if the application-specific condition is satisfied. The modal dialog is an typical example of using this mechanism.

public void doModal() throws InterruptedException {
    ...Executions.wait(_mutex); //suspend this thread, an event processing thread}    
public void endModal() {
...
    Executions.notify(_mutex); //resume the suspended event processing thread    
}

Their use is similar to the wait, notify and notifyAll methods of the java.lang.Object class. However, you cannot use the methods of java.lang.Object for suspending and resuming event listeners. Otherwise, all event processing will be stalled for the associated desktop.

Notice that, unlike Java Object's wait and notify, whether to use the synchronized block to enclose Executions' wait and notify is optional. In the above case, we don't have to, because no racing condition is possible. However, if there is an racing condition, you can use the synchronized block as what you do with Java Object's wait and notify.

//Thread 1
public void request() {
    ...    
    synchronized (mutex) {    
        ...//start another thread        
        Executions.wait(mutex); //wait for its completion        
    }    
}

//Thread 2
public void process() {
    ... //process it asynchronously    
    synchronized (mutex) {    
        Executions.notify(mutex);        
    }    
}

Events for the same desktop are processed sequentially. In other words, an event handler will block any following handlers. Worse of all, the user, due to the limitation of HTTP, got no hint but the small processing dialog shown at the left-top corner on the browser.

With the echo event and the showBusy method as described in the Echo Events section above, you can provide a more descriptive message and prevent the user from, say, clicking other buttons to slow down the performance further for long operations.

However, blocking users from access might not be acceptable for your applications. To prevent the blocking, you have to, like desktop applications, process the long operation in another working thread. Then, report the processing status back the client continuously.

With ZK, you have four options: server push, suspend and resume, timer, and piggyback.

<window title="Demo of Server Push">
<zscript>
    import test.WorkingThread;    
    WorkingThread thread;    
    void startServerpush(){    
        //enable server push        
        desktop.enableServerPush(true);        
            //invoke working thread and passing required component as parameter            
            thread= new WorkingThread(info);            
        thread.start();        
    }    
    void stopServerpush(){    
        //stop the thread        
        thread.setDone();        
        //disable server push        
        desktop.enableServerPush(false);        
    }    
</zscript>
    <vbox>    
        <button label="Start Server Push" onClick="startServerpush()"/>        
        <button label="Stop Server Push" onClick="stopServerpush()"/>        
    <label id="info"/>    
    </vbox>    
</window>

    packagetest;    

        publicclassWorkingThread extends Thread{        
    private final Desktop _desktop;    
    private final Label _info;    
    private int _cnt;    
    private boolean _ceased;    
        publicWorkingThread(Label info){        
        _desktop = info.getDesktop();        
            _info= info;            
                            }publicvoidrun(){try{                            
                while(!_ceased){                
                Threads.sleep(2000); //Update each two seconds                
                Executions.activate(_desktop); //get full control of desktop                
                    try{                    
                    _info.setValue(Integer.toString(++_cnt));                    
                                            }catch(RuntimeException ex){throw ex;                                            
                    }catch(Error ex){                    
                    throw ex;                    
                }finally{                
                    Executions.deactivate(_desktop);                    
                        //release full control of desktop                        
                }                
            }            
            }catch(InterruptedException ex){            
            }            
                }publicvoidsetDone(){                
        _ceased = true;        
    }}    

//WorkingThread
package test;
public class WorkingThread extends Thread {
    private static int _cnt;    
    private Desktop _desktop;    
    private Label _label;    
    private final Object _mutex = new Integer(0);    
    /** Called by thread.zul to create a label asynchronously.    
    *To create a label, it start a thread, and wait for its completion.    
    */    
    public static final Label asyncCreate(Desktop desktop)    
        throws InterruptedException {        
                final WorkingThread worker = new WorkingThread(desktop);synchronized (worker._mutex) { //to avoid racing                
            worker.start();            
            Executions.wait(worker._mutex);            
            return worker._label;            
        }        
    }    
    public WorkingThread(Desktop desktop) {    
        _desktop = desktop;        
        }public void run() {        
            _label = new Label("Execute "+ ++_cnt);            
            synchronized (_mutex) { //to avoid racing            
            Executions.notify(_desktop, _mutex);            
        }        
    }    
}

<window id="main" title="Working Thread">
    <button label="Start Working Thread">    
        <attribute name="onClick">        
        timer.start();        
        Label label = test.WorkingThread.asyncCreate(desktop);        
        main.appendChild(label);        
        timer.stop()        
        </attribute>        
    </button>    
    <timer id="timer" running="false" delay="1000" repeats="true"/>    
</window>

//WorkingThread2
package test;
public class WorkingThread2 extends Thread {
    private static int _cnt;    
    private final Desktop _desktop;    
    private final List _result;    
        
    public WorkingThread2(Desktop desktop, List result) {    
        _desktop = desktop;        
        _result = result;        
    }    
    public void run() {    
        _result.add(new Label("Execute "+ ++_cnt));        
    }    
}

<window id="main" title="Working Thread2">
    <zscript>    
        int numPending = 0;        
        List result = Collections.synchronizedList(new LinkedList());        
    </zscript>    
    <button label="Start Working Thread">    
        <attribute name="onClick">        
            ++numPending;            
            timer.start();            
            new test.WorkingThread2(desktop, result).start();            
        </attribute>        
    </button>    
    <timer id="timer" running="false" delay="1000" repeats="true">    
        <attribute name="onTimer">        
            while (!result.isEmpty()) {            
            main.appendChild(result.remove(0));            
            --numPending;            
            }            
            if (numPending == 0) timer.stop();            
        </attribute>        
    </timer>    
</window>

<window id="main" title="Working Thread3" onPiggyback="checkResult()">
    <zscript>    
    List result = Collections.synchronizedList(new LinkedList());    

    void checkResult() {    
        while (!result.isEmpty())        
            main.appendChild(result.remove(0));            
    }    
    </zscript>    
    <button label="Start Working Thread">    
        <attribute name="onClick">        
    timer.start();    
    new test.WorkingThread2(desktop, result).start();    
        </attribute>        
    </button>    
</window>

An event listener is executed in an event processing thread. Sometimes, you have to initialize the thread before processing any event.

A typical example is to initialize the thread for the authentication. Some J2EE or Web containers store authentication information in the thread local storage, such that they could re-authenticate automatically when needed.

To initialize the event processing threads, you have to register a class, that implements the org.zkoss.zk.ui.event.EventThreadInit interface, to the listener element in the WEB-INF/zk.xml file^[32].

Once registered, an instance of the specified class is constructed in the main thread (aka., the servlet thread), before starting an event processing thread. Then, the init method of the instance is called at the context of the event processing thread before doing anything else.

Notice that the constructor and the init method are invoked at different thread such that developers could retrieve thread-dependent data from one thread and pass to anther.

Here is an example for the authentication mechanism of JBoss^[33]. In this example, we retrieve the information stored in the servlet thread in the constructor. Then, we initialize the event processing thread when the init method is called.

import java.security.Principal;
import org.jboss.security.SecurityAssociation;
import org.zkoss.zk.ui.Component;
import org.zkoss.zk.ui.event.Event;
import org.zkoss.zk.ui.event.EventThreadInit;

public class JBossEventThreadInit implements EventThreadInit {
    private final Principal _principal;    
    private final Object _credential;    
    /** Retrieve info at the constructor, which runs at the servlet thread. */    
    public JBossEventThreadInit() {    
        _principal = SecurityAssociation.getPrincipal();        
        _credential = SecurityAssociation.getCredential();        
    }    
    //-- EventThreadInit --//    
    /** Initial the event processing thread at this method. */    
    public void init(Component comp, Event evt) {    
        SecurityAssociation.setPrincipal(_principal);        
        SecurityAssociation.setCredential(_credential);        
    }    
}

Then, in WEB-INF/zk.xml, you have to specify as follows.

<zk>
    <listener>    
        <listener-class>JBossEventThreadInit</listener-class>        
    </listener>    
</zk>

Similarly, you might have to clean up an event processing thread after it has processed an event.

A typical example is to close the transaction, if it is not closed properly.

To cleanup the event processing threads, you have to register a listener class, that implements the org.zkoss.zk.ui.event.EventThreadCleanup interface, to the listener element in the WEB-INF/zk.xml file.

<zk>
    <listener>    
        <listener-class>my.MyEventThreadCleanup</listener-class>        
    <listener>    
</zk>

First, each element must be closed. They are two ways to close an element as depicted below. They are equivalent.

<window></window>

<window/>

Second, elements must be properly nested.

<window> <groupbox> Hello World! </groupbox></window>

<window> <groupbox> Hello World! </window></groupbox>

XML use <element-name> to denote an element, so you have to replace special characters. For example, you have to use &lt; to represent the < character.

Alternatively, you could ask XML parser not to interpret a piece of text by use of CDATA as follows.

<zscript>
<![CDATA[
void myfunc(int a, int b) {
    if (a < 0 && b > 0) {    
        //do something        
    }    
]]>
</zscript>

It is interesting to notice that backslash (\) is not a special character, so you don't need to escape it at all.

A comment is used to leave a note or to temporarily edit out a portion of XML code. To add a comment to XML, use <!-- and --> to escape them.

<window>
<!-- this is a comment and ignored by ZK -->
</window>

It is, though optional, a good idea to specify the encoding in your XML such that the XML parser can interprets it correctly. Note: it must be the first line of the file.

<?xml version="1.0" encoding="UTF-8"?>

In addition to specify the correct encoding, you have to make sure your XML editor supports it as well.

Namespaces are a simple and straightforward way to distinguish names used in XML documents. ZK uses XML namespaces to distinguish the component name, such that it is OK to have two components with the same name as long as they are in different namespace. In other words, ZK uses a XML namespace to represent a component set, such that developers could mix two or more component sets in the same page, as depicted below.

<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:x="http://www.zkoss.org/2005/zul"
xmlns:zk="http://www.zkoss.org/2005/zk">
<head>
    <title>ZHTML Demo</title>    
</head>
<body>
    <h1>ZHTML Demo</h1>    
    <table>    
    <tr>    
        <td><x:textbox/></td>        
        <td><x:button label="Now" zk:onClick="addItem()"/></td>        
    </tr>    
    </table>    
    <zk:zscript>    
        void addItem() {        
    }    
    </zk:zscript>    
</body>
</html>

where

<window xmlns="http://www.zkoss.org/2005/zul"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.zkoss.org/2005/zul http://www.zkoss.org/2005/zul/zul.xsd">

The evaluation of an element could be conditional. By specifying the if or unless attribute or both, developers could control whether to evaluate the associated element.

In the following example, the window component is created only if a is 1 and b is not 2. If an element is ignored, all of its child elements are ignored, too.

<window if="${a==1}" unless="${b==2}">
    ...    
</window>

The following example controls when to interpret a piece of Java codes.

<textbox id="contributor"/>
<zscript if="${param.contributor}">
    contributor.label = Executions.getCurrent().getParameter("contributor");    
</zscript>

With the switch and case attributes of the zk element, you can evaluate a portion of a ZK page only if a variable matches a certain value.

<zk switch="${fruit}">
    <zk case="apple">    
    Evaluated only if ${fruit} is apple    

</zk>

<zk case="${special}">

Evaluated only if ${fruit} equals ${special}

</zk>

<zk>

Evaluated only if none of the above cases matches.

</zk>

</zk>

ZK Loader will evaluate from the first case to the last case, until it matches the switch condition, which is the value specified in the switch attribute. The evaluation is mutually exclusive conditional. Only the first matched case is evaluated.

The zk element without any case, is the default – i.e., it always matches and is evaluated if all cases above it failed to match.

<zk switch="${fruit}">
    <zk case="apple, ${special}">    
    Evaluated if ${fruit} is either apple or ${special}    

<zk switch="${fruit}">

<zk case="${each}" forEach="apple, orange">

The choose and when attributes provide an alternative way for mutually exclusive conditional evaluation.

<zk choose="">
    <zk when="${fruit == 'apple'}">    

Evaluated if the when condition is true.

</zk>

<zk>

Evaluated if none of above cases matches.

</zk>

</zk>

You don't have to assign any value to the choose attribute, which is used only to identify the range of the mutually exclusive condition evaluation.

During the evaluation, a variable called each is created and assigned with the item from the specified collection. In the above example, each is assigned with "Best" in the first iteration, then "Better" and finally "Good".

Notice that the each variable is accessible both in EL expression and in zscript. ZK will preserve the value of the each variable if it is defined before, and restore it after the evaluation of the associated element.

The forEachStatus variable is an instance of org.zkoss.ui.util.ForEachStatus. It holds the information about the current iteration. It is mainly used to get the item of the enclosing element that is also assigned with the forEach attribute.

In the following example, we use nested iterative elements to generate two listboxes.

<hbox>
<zscript>
classes = new String[] {"College", "Graduate"};
grades = new Object[] {
new String[] {"Best", "Better"}, new String[] {"A++", "A+", "A"}
};
</zscript>
<listbox width="200px" forEach="${classes}">
<listhead>
<listheader label="${each}"/>
</listhead>
<listitem label="${forEachStatus.previous.each}: ${each}"
forEach="${grades[forEachStatus.previous.index]}"/>
</listbox>
</hbox>

Notice that the forEachStatus variable is accessible both in EL expression and in zscript.

It is a bit tricky to use the forEach and forEachStatus variables in event listeners, because they are available only in the Component Creation Phase^[35]. Thus, the following sample is incorrect: when the onClick listener is called, the each variable is no longer available.

<window title="Countries" border="normal" width="100%">
    <zscript><![CDATA[    
    String[] countries = {    
        "China", "France", "Germany", "United Kindom", "United States"};        
    ]]></zscript>    

    <hbox>    
        <button label="${each}" forEach="${countries}"        
            onClick="alert(each)"/> <!-- incorrect!! -->            
    </hbox>    
</window>

Notice that the button's label is assigned correctly because it is done at the same phase – the Component Creation Phase.

Also notice that you cannot use EL expressions in the event listener. For example, the following codes fail to execute because the onClick listener is not a legal Java codes (i.e., EL expressions are ignored in zscript).

<button label="${each}" forEach="${countries}"
        onClick="alert(${each})"/> <!-- incorrect!! -->        

<window title="Countries" border="normal" width="100%">
    <zscript><![CDATA[    
    String[] countries = {    
        "China", "France", "Germany", "United Kindom", "United States"};        
    ]]></zscript>    

    <hbox>    
        <button label="${each}" forEach="${countries}"        
        onClick="alert(self.getAttribute(&quot;country&quot;))">        
            <custom-attributes country="${each}"/>            
        </button>        
    </hbox>    
</window>

The simplest way to defer the creation of the child components is to use the fulfill attribute. For example, the comboitem component in the following code snippet will not be created, until the combobox component receives the onOpen event, indicating comboitem is becoming visible.

<combobox fulfill="onOpen">
    <comboitem label="First Option"/>    
</combobox>

In other words, if a ZUML element is specified with the fulfill attribute, its child elements won't be processed until the event specified as the value of the fulfill attribute is received.

If the event to trigger the creation of children is targeted to another component, you can specify the target component's identifier after colon as depicted below.

<button id="btn" label="show" onClick="content.visible = true"/>
<div id="content" fulfill="btn.onClick">
    Any content created automaticall when btn is clicked    
</div>

If the components belong to different ID space, you can specify a path after the event name as follows.

<button id="btn" label="show" onClick="content.visible = true"/>
<window id="content" fulfill="../btn.onClick">
    Any content created automaticall when btn is clicked    
</window>

If you prefer to create the children manually or you need to alter them dynamically, you can listen to the event indicating the children are becoming visible, and then manipulate them in the listener. For example,

<combobox id="combo" onOpen="prepare()"/>
<zscript><![CDATA[
    void prepare() {    
        if (event.isOpen() && combo.getItemCount() == 0) {        
            combo.appendItem("First Option");            
        }        
    }    
]]></zscript>

The org.zkoss.zk.ui.Execution interface provides information about the current execution, such as the request parameters. To get the current execution, you could do one of follows.

<?page [id="..."] [title="..."] [style="..."] [language="xul/html"] [zscriptLanguage="Java"]?>

It describes attributes of a page.

Note: You can place the page directive in any location of a XML document, but the language attribute is meaningful only if the directive is located at the topmost level, i.e., at the the same level as the root element.

For more available options and descriptions, refer to the Developer's Reference.

<?component name="myName" macroURI="/mypath/my.zul" [apply="composer"] [prop1="value1"] [prop2="value2"]...?>

<?component name="myName" [class="myPackage.myClass"] [extends="existentName"] [moldName="myMoldName"] [moldURI="/myMoldURI"] [apply="composer"] [prop1="value1"] [prop2="value2"]...?>

Defines a new component for a particular page. Components defined in this directive is visible only to the page with this directive. To define components that can be used in any page, use the language addon, which is a XML file defining components for all pages in a Web application^[36].

There are two formats: by-macro and by-class.

<?component name="mywindow" extends="window" class="MyWindow"?>
...
<mywindow>
...
</mywindow>

<window use="MyWindow">
...
</window>

<?component name="okbutton" extends="button" label="OK"
style="border:1px solid blue"?>

<?button name="button" extends="button" style="border:1px solid blue"?>
<button/> <!-- with blue border -->

<?init class="..." [arg0="..."] [arg1="..."] [arg2="..."] [arg3="..."]?>

<?init zscript="..."?>

There are two formats. The first format is to specify a class that is used to do the application-specific initialization. The second format is to specify a zscript file to do the application-specific initialization.

Since 3.6.2, you can use any (readable) name instead of arg0 and so on. For example,

<?init class="org.zkoss.zkplus.databind.AnnotateDataBinderInit" root="./abc"?>

The initialization takes place before the page is evaluated and attached to a desktop. Thus, the getDesktop, getId and getTitle method will return null, when initializing. To retrieve the current desktop, you could use the org.zkoss.zk.ui.Execution interface.

You could specify any number of the init directive. If you choose the first format, the specified class must implement the org.zkoss.zk.ui.util.Initator interface. Once specified, an instance of the class is constructed and its doInit method is called, before the page is evaluated.

In addition, the doFinally method is called, after the page has been evaluated. The doCatch method is called if an exception occurs. Thus, this directive is not limited to initialization. You could use it for cleanup and error handling.

If you choose the second format, the zscript file is evaluated.

For more information, refer to the Developer's Reference.

<?variable-resolver class="..."?>

Specifies the variable resolver that will be used by the zscript interpreter to resolve unknown variables. The specified class must implement the org.zkoss.xel.VariableResolver interface.

You can specify multiple variable resolvers with multiple variable-resolver directives. The later declared one has higher priority.

The following is an example when using ZK with the Spring framework. It resolves Java Beans declared in the Spring framework, such that you access them directly.

<?variable-resolver class="org.zkoss.zkplus.spring.DelegatingVariableResolver"?>

Refer to Small Talk: ZK with Spring DAO and JDBC, Part II for more details.

For more information about the attributes, refer to the Developer's Reference.

<?import uri="..."?><?import uri="..." directives="..."?>

It imports the directives, such as component definitions (<?component?>) and initiators (<?init?>), defined in another ZUML page.

If the directives attribute is omitted, only the component and init directives are imported. If you want to import particular directives, you can specify a list of the names of the directives separated by comma. For example,

<?import uri="/template/taglibs.zul" directives="taglib, xel-method"?>

The directives that can be imported include component, init, meta, taglib, variable-resolver, and xel-method. If you want to import them all, specify * to the directives attribute. Notice that meta implies both the meta and link directives.

A typical use is that you put a set of component definitions in one ZUML page, and then import it in other ZUML pages, such that they share the same set of component definitions, additional to the system default.

<!-- special.zul: Common Definitions -->
<?init zscript="/WEB-INF/macros/special.zs"?>
<?component name="special" macroURI="/macros/special.zuml" class="Special"?>
<?component name="another" macroURI="/WEB-INF/macros/another.zuml"?>

where the Special class is assumed to be defined in /WEB-INF/macros/special.zs.

Then, other ZUML pages can share the same set of component definitions as follows.

<?import uri="special.zul"?>
...
<special/><!-- you can use the component defined in special.zul -->

Unlike other directives, the import directives must be at the topmost level, i.e., at the the same level as the root element.

For more information, refer to the Developer's Reference.

<?link [href="uri"] [name0="value0"] [name1="value1"] [name2="value2"]?><?meta [name0="value0"] [name1="value1"] [name2="value2"]?><?script type="text/javascript" [src="uri"] [charset="encoding"] [content="javascript"]?>

These are so-called header elements in HTML. They are generated inside the HEAD element. The meta tags are generated before ZK default JavaScript and CSS files, while the other tags are generated after ZK default JavaScript and CSS files. Currently only HTML-based clients (so-called browsers) support them.

Developers can specify whatever attributes with these header directives. ZK only encodes the URI of the href and src attribute (by use of the encodeURL method of the Executions class). ZK generates all other attributes directly to the client.

Notice that these header directives are effective only for the main ZUL page. In other words, they are ignored if a page is included by another pages or Servlets. Also, they are ignored if the page is a zhtml file.

<?link rel="alternate" type="application/rss+xml" title="RSS feed"
href="/rssfeed.php"?><?link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"?>
<?link rel="stylesheet" type="text/css" href="~./zul/css/ext.css.dsp"?>
<?script type="text/javascript" src="/js/foo.js"?>
<?script type="text/javascript" content="var foo = true;

if (zk.ie) foo = false;"?>

<window title="My App">
    My content    
</window>

apply="a-class-name"apply="class1, class2,..."apply="${EL_returns_a_class_or_a_collection_of_classes}"apply="${EL_returns_an_instance_or_a_collection_of_Composer_instances}"

It specifies a class, a collection of classes that are used to initialize the component. The class must implement the org.zkoss.zk.util.Composer interface. And then, you can do the initialization in the doAfterCompose method, since it is called after the component and all its children are instantiated.

<window apply="MyComposer"/>

In addition, you specify a Composer instance, or a collection of Composer instances by use of EL expressions.

Note: the EL expressions are, if specified, evaluated before the component is instantiated. So you cannot reference to the component. Moreover, the self variable references to the parent component, if any, or the current page, if no parent component, in the EL expressions specified in this attribute.

If you want more control such as handling the exception, you can also implement the org.zkoss.zk.util.ComposerExt interface.

use="a-class-name"use="${EL_returns_a_class_or_a_class_name_or_a_component}"

It specifies a class to create a component instead of the default one. In the following example, MyWindow is used instead of the default class, org.zkoss.zul.Window.

<window use="MyWindow"/>

Notice that, if the expression returns a component, the component shall not belong to any page.

if="${an-EL-expr}"

It specified the condition to evaluate the associated element. In other words, the associated element and all its child elements are ignored, if the condition is evaluated to false.

unless="${an-EL-expr}"

It specified the condition not to evaluate the associated element. In other words, the associated element and all its child elements are ignored, if the condition is evaluated to true.

forEach="${an-EL-expr}"forEach="${an-EL-expr},a-value"

There are two formats. First, you specify a value without comma. The value is usually a collection of objects, such that the associated element will be evaluated repeatedly against each object in the collection. If not specified or empty, this attribute is ignored. If non-collection object is specified, it is evaluated only once as if a single-element collection is specified.

Second, you can specify a list of values by separating them with comma. Then, the associated element will be evaluated repeatedly against each value in the list.

forEachBegin="an-interger"forEachBegin="${an-EL-expr}"

It is used with the forEach attribute to specify the index (starting from 0) that the iteration shall begin at. If not specified, the iteration begins at the first element, i.e., 0 is assumed.

If forEachBegin is greater than or equals to the number of elements, no iteration is performed.

Note: forEachStatus.index is absolute with respect to the underlying collection, array or other type. For example, if forEachBegin is 5, then the first value of forEachStatus.index with be 5.

forEachEnd="an-interger"forEachEnd="${an-EL-expr}"

It is used with the forEach attribute to specify the index (starting from 0) the iteration shall ends at (inclusive). If not specified, the iterations ends at the last element.

If forEachEnd is greater than or equals to the number of elements, the iteration ends at the last element.

fulfill="event-expr"fulfill="event-expr1, event-expr2, event-expr3"fulfill="event-expr=uri-expr"fulfill="event-expr1, event-expr2=uri-expr2"fulfill="=uri_expr"

where event-expr, event-expr1 and others are called event expressions. An event expression is used to identify an event that is targeting a particular component. It can be one of the following formats:

event-nametarget-id.event-nameid1/id2/id3.event-name${el-expr}.event-name

and uri-expr is an URI or an EL expression returning URI. For example,

/my/super.zul${my_super_zul}

It is used to specify when to create the child components. By default (i.e., fulfill is not specified), the child components are created right after its parent component, when the ZUML page is loaded.

If you want to defer the creation of the child components, you can specify the condition with the fulfill attribute. The condition consists of the event name and, optionally, the target component's identifier or path. It means that the child elements won't be processed, until the event is received by, if specified, the target component. If the identifier is omitted, the same component is assumed.

If an EL expression is specified, it must return a component, an identifier or a path.

Refer to the Load on Demand section for more details.

<button id="b" label="open"/>
<div id="d" fulfill="b.onClick=/my/super.zul">
</div>

<div fulfill="=/my/super.zul">
    <combobox/>    
</div>

<div fulfill="b1.onClick, b2.onOpen"
onFulfill="Components.wireVariables(self, controller)">

forward="target_event_expr"forward="oringal_event=target_event_expr"

where target_event_expr is an event expressions. An event expression is used to identify an event that is targeting a particular component. It can be one of the following formats:

event-nametarget-id.event-nameid1/id2/id3.event-name${el-expr}.event-name

It is used to forward an event, that is targeting a particular component, to another component and to another event name. It is called the forward condition.

For example, you can forward the onClick event targeting a button to the window as follows:

<window id="w" use="MyWindow">
    ...    
    <button lable="Submit" forward="onClick=w.onOK"/>    
</window>

Then, you can handle the submission in the MyWindow class as follows:

public class MyWindow extends Window {
    public void onOK() {    
        //handle the submission        
    }    
}

The original event is optional. If it is omitted, onClick is assumed. Similarly, the target ID is also optional. If omitted, the space owner is assumed. Thus, the above codes can be simplified to the following:

<window id="w" use="MyWindow">
    ...    
    <button lable="Submit" forward="onOK"/>    
</window>

If you want to forward several events, you can specify these conditions in the forward attribute by separating them with the comma (,):

<textbox forward="onChanging=onUpdating, onChange=some.onUpdate"/>

<button forward="onCancel(abort)"/>

<button forward='${mainWnd}.onOK(${c:getProperty("status")})'/>

<zk>...</zk>

It is a special element used to aggregate other components. Unlike a real component (say, hbox or div), it is not part of the component tree being created. In other words, it doesn't represent any component. For example,

<window>
    <zk>    
        <textbox/>        
        <textbox/>        
    </zk>    
</window>

is equivalent to

<window>
    <textbox/>    
    <textbox/>    
</window>

Then, what is it used for?

<?page title="Multiple Root"?>
<zk>
    <window title="First">    
    ...    
    </window>    
    <window title="Second" if="${param.secondRequired}">    
    ...    
    </window>    
</zk>

<window>
    <zk forEach="${mycols}">    
        <textbox if="${each.useText}"/>        
        <datebox if="${each.useDate}"/>        
        <combobox if="${each.useCombo}"/>        
    </zk>    
</window>

<zscript [language="Java"]>Scripting codes</zscript><zscript src="uri" [language="Java"]/>

It defines a piece of the scripting codes, say the Java codes, that will be interpreted when the page is evaluated. The language of the scripting codes is, by default, Java (see below). You can select a different language by use the language attribute.

The zscript element has two formats as shown above. The first format is used to embed the scripting codes directly in the page. The second format is used to reference an external file that contains the scripting codes.

<button onClick="alert(&quot;Hi&quot;)"/>

<window>
    <zscript>    
    void add() {    
    }    
    </zscript>    
    <button onClick="add()"/>    
</window>

<window>
    <zscript deferred="true">    
    void add() {    
    }    
    </zscript>    
    <button onClick="add()"/>    
</window>

<button onClick="javascript:do_something_in_js()"/>
<zscript language="groovy">
do_something_in_Groovy();
</zscript>

<?page zscriptLanguage="Groovy"?>

<zscript>
def name = "Hello World!";
</zscript>

<zscript-config>
        <language-name>SuperJava</language-name><!-- case insensitive -->        

</zscript-config>

It defines a XML attribute of the enclosing element. The content of the element is the attribute value, while the name attribute specifies the attribute name. It is useful if the value of an attribute is sophisticated, or the attribute is conditional.

<window>
    <attribute name="title" if="${new}">Untitled</attribute>    
    <attribute name="title" unless="${new}">${title}</attribute>    
</window>

In addition, you can specify a XML fragment as the value of the attribute. The XML fragment is so-called the native content.

<html>
    <attribute name="content">    
        <ol>        
            <li forEach="${values}">${each}</li>            

</ol>

</attribute>

</html>

where ol and li are part of the native content. They are not ZK components. They will be eventually converted to a String instance and assigned to the specified attribute. If values has three elements, the above example is equivalent to the following:

<html>
    <attribute name="content"><![CDATA[    
        <ol>        
            <li>${values[0]}</li>            
            <li>${values[1]}</li>            
            <li>${values[2]}</li>            
        </ol>        
    ]]></attribute>    
</html>

It defines a set of variables. It is equivalent to the setVariable method of Component, if it has a parent component, and Page, if it is declared at the page level.

As depicted below, variables is convenient to assign variables without programming.

<window>
    <variables rich="simple" simple="intuitive"/>    
</window>

It is equivalent to

<window>
    <zscript>    
        self.setVariable("rich", "simple", false);        
        self.setVariable("simple", "intuitive", false);        
    </zscript>    
</window>

Of course, you can specify EL expressions for the values.

<window>
    <window id="w" title="Test">    
        <variables title="${w.title}"/>        
        1: ${title}        
    </window>    
    2: ${title}    
</window>

Like Component's setVariable, you can control whether to declare variables local to the current ID space as follows. If not specified, local="false" is assumed.

<variables simple="rich" local="true"/>

<variables simple="apple, ${more}" composite="list"/>

<variables simple="juice=apple, flavor=${more}" composite="map"/>

<variables var=""/>

<variables var="${null}"/>

<variables m:forEach="a value" xmlns:m="http://whatever.com"/>

It defines a set of custom attributes. Custom attributes are objects associated with a particular scope. Acceptable scopes include component, space, page, desktop, session and application.

As depicted below, custom-attributes is convenient to assign custom attributes without programming.

<window>
    <custom-attributes main.rich="simple" very-simple="intuitive"/>    
</window>

It is equivalent to

<window>
    <zscript>    
        self.setAttribute("main.rich", "simple");        
        self.setAttribute("very-simple", "intuitive");        
    </zscript>    
</window>

Moreover, you could specify what scope to assign the custom attributes to.

<window id="main" title="Welcome">
    <custom-attributes scope="desktop" shared="${main.title}"/>    
</window>

It is equivalent to

<window id="main">
    <zscript>    
        desktop.setAttribute("shared", main.title);        
    </zscript>    
</window>

Notice that EL expression is evaluated against the component being created. Sometime it is subtle to notice. For example, ${componentScope.simple} is evaluated to null, in the following codes. Why? It is a shortcut of <label value="${componentScope.simple}"/>. In other words, the component, self, is the label rather than the window, when the EL is evaluated.

<window>
    <custom-attributes simple="intuitive"/>    
    ${componentScope.simple}    
</window>

is equivalent to

<window>
    <custom-attributes simple="intuitive"/>    
    <label value="${componentScope.simple}"/><!-- self is label not window -->    
</window>

Tip: Don't confuse <attribute> with <custom-attributes>. They are irrelevant. The attribute element is a way to define a XML attribute of the enclosing element, while the custom-attributes element is used to assign custom attributes to particular scopes.

As stated before, each set of components is associated with an unique namespace. However, developers might develop or use additional components from 3rd party, so here we list only the namespaces that are shipped with the ZK distribution.

It is optional to specify namespaces in ZUML pages, until there are conflicts. ZK determined which namespace to use by examining the extension of a ZUML page. For the .zul and .xul extensions, the namespace of XUL is assumed. For html, xhtml and zhtml, the namespace of XHTML is assumed.

To mix with another markup language, you have to use xmlns to specify the correct namespace.

<window xmlns:h="http://www.w3.org/1999/xhtml">
    <h:div>    
        <button/>        
    </h:div>    
</window>

For the XHTML components, the onClick and onChange attributes are conflicts with ZK's attributes. To resolve, you have to use the reserved namespace, http://www.zkoss.org/2005/zk, as follows.

<html xmlns:x="http://www.zkoss.org/2005/zul" xmlns:zk="http://www.zkoss.org/2005/zk">
<head>
<title>ZHTML Demo</title>
</head>
<body>
    <script type="text/javascript">    
    function woo() { //running at the browser    
    }    
    </script>    
    <zk:zscript>    
    void addItem() { //running at the server    
    }    
    </zk:zscript>    
<x:window title="HTML App">
     <input type="button" value="Add Item"    
     onClick="woo()" zk:onClick="addItem()"/>    
</x:window>
</body>

In this example, the onClick attribute is a ZHTML's attribute to specify JavaScript codes to run at the browser. On the other hand, the zk:onClick is a reserved attribute for specify a ZK event handler.

Notice that the namespace prefix, zk, is optional for the zscript element, because ZHTML has no such element and ZK has enough information to determine it.

Also notice that you have to specify the XML namespace for the window component, because it is from a different component set.

A label component represents a piece of text.

<window border="normal">
    Hello World    
</window>

If you want to specify attribute to a label, you have to specify <label> explicitly as follows.

<window border="normal">
    <label style="color: red" value="Hello World"/>    
</window>

Tip: ZUML is XML, not HTML, so it doesn't accept &nbsp;. However, you can use &#160; instead.

<window border="normal" width="100px">
<vbox id="result">
</vbox>
    <zscript><![CDATA[    
    String[] s = {"this is 9", "this is ten more to show",    
    "this framework", "performance is everything"};    
    for (int j = 0; j < s.length; ++j) {    
        Label l = new Label(s[j]);        
        l.maxlength = 9;        
        l.hyphen = true;        
        l.parent = result;        
    }    
    ]]></zscript>    
</window>

There are two types of buttons: button and toolbarbutton. They behave similar except the appearance is different. The button component uses HTML BUTTON tag, while the toolbarbutton component uses HTML A tag.

You could assign a label and an image to a button by the label and image properties. If both are specified, the dir property control which is displayed up front, and the orient property controls whether the layout is horizontal or vertical.

<button label="Left" image="/img/folder.gif" width="125px"/>
<button label="Right" image="/img/folder.gif" dir="reverse" width="125px"/>
<button label="Above" image="/img/folder.gif" orient="vertical" width="125px"/>
<button label="Below" image="/img/folder.gif" orient="vertical" dir="reverse" width="125px"/>

In addition to identifying images by URL, you could assign a dynamically generated image to a button by use of the setImageContent method. Refer to the following section for details.

Tip: The setImageContent method is supplied by all components that has the image property. Simplicity put, setImageContent is used for dynamically generated images, while image is used for images identifiable by URL.

<button onClick="do_something_in_Java()"/>
<button href="/another_page.zul"/>

<button onClick="Executions.sendRedirect(&quot;another.zul&quot;)"/>
<button href="another.zul"/>

A radio button is a component that can be turned on and off. Radio buttons are grouped together in a group, called radiogroup. Only one radio button with the same group may be selected at a time.

<radiogroup onCheck="alert(self.selectedItem.label)">
    <radio label="Apple"/>    
    <radio label="Orange"/>    
    <radio label="Banana"/>    
</radiogroup>

<radiogroup>
    <grid>    
    <rows>    
        <row><radio label="Apple" selected="true"/> Fruit, music or computer</row>        
        <row><radio label="Orange"/><textbox/></row>        
        <row><radio label="Banana"/><datebox/></row>        
    </rows>    
    </grid>    
</radiogroup>

<radiogroup>
    <grid>    
    <rows>    
        <row><radio label="Apple" selected="true"/> Fruit, music or computer</row>        
        <row><radio label="Orange"/>        
            <radiogroup>            
            <radio label="Small"/>            
            <radio label="Large" selected="true"/>            
            </radiogroup>            
        </row>        
        <row><radio label="Banana"/><datebox/></row>        
    </rows>    
    </grid>    
</radiogroup>

An image component is used to display an image at the browser. There are two ways to assign an image to an image component. First, you could use the src property to specify a URI where the image is located. This approach is similar to what HTML supports. It is useful if you want to display a static image, or any image that can be identified by URL.

<image src="/some/my.jpg"/>

<image src="/my*.png"

Location: <textbox onChange="updateMap(self.value)"/>
Map: <image id="image"/>
<zscript>
    void updateMap(String location) {    
        if (location.length() > 0)        
            image.setContent(new MapImage(location));            
    }    
</zscript>

A imagemap component is a special image. It accepts whatever properties an image component accepts. However, unlike image, if a user clicks on the image, an onClick event is sent back to the server with the coordinates of the mouse position. In contrast, the onClick event sent by image doesn't contain the coordinates.

The coordinates of the mouse position are screen pixels counted from the upper-left corner of the image beginning with (0, 0). It is stored as instance of org.zkoss.zk.ui.event.MouseEvent. Once the application receives the onClick event, it could examine the coordinates of the mouse position from the getX and getY methods.

For example, if a user clicks 208 pixels over and 205 pixels down from the upper-left corner of the image displayed from the following statement.

<imagemap src="/img/sun.jpg" onClick="alert(event.x + &quot;, &quot; +event.y)"/>

Then, the user gets the result as depicted below.

The application usually uses the coordinates to determine where a user has clicked, and then response accordingly.

Area

Instead of processing the coordinates by the application itself, developers could add the area components as the children of a imagemap component.

<imagemap src="/img/sun.jpg" onClick="alert(event.area)">
<area id="First" coords="0, 0, 100, 100"/>
<area id="Second" shape="circle" coords="200, 200, 100"/>
</imagemap>

Then, the imagemap component will translate the coordinates of the mouse position to a logical name: the identifier of the area that users has clicked.

For example, if users clicks at (150, 150), then the user gets the result as depicted blow.

An audio component is used to play the audio at the browser. Like image, you could use the src property to specify an URL of an audio resource, or the setContent method to specify a dynamically generated audio.

Depending on the browser and the audio plugin, developers might be able to control the play of an audio by the play, stop and pause methods. Currently, Internet Explorer with Media Player is capable of such controls.

A set of input controls are supported in the XUL component set: textbox, intbox, decimalbox, doublebox, datebox, combobox, and bandbox. They are used to let users input different types of data.

<zk>
    <textbox/>    
    <datebox/>    
</zk>

Tip: combobox and bandbox are special input boxes. They shares the common properties described here. Their unique features will be discussed later in the Comboboxes and Bandboxes section.

Username: <textbox/>
Password: <textbox type="password"/>

<datebox format="MM/dd/yyyy"/>
<decimalbox format="#,##0.##"/>

<datebox id="db"/><button label="set MM-dd-yyyy" onClick="db.setFormat(&quot;MM-dd-yyyy&quot;)"/>

<intbox constraint="no negative,no zero"/>

<textbox constraint="/.+@.+\.[a-z]+/"/>

new Textbox().setContraint("/.+@.+\\.[a-z]+/");

<textbox constraint="/.+@.+\.[a-z]+/: e-mail address only"/>

<textbox constraint="/.+@.+\.[a-z]+/: ${c:l('err.email.required')}"/>

<datebox constraint="between 20071225 and 20071203"/>
<datebox constraint="before 20071225"/>
<datebox constraint="after 20071225"/>

<window title="Custom Constraint">
    <zscript><![CDATA[    
Constraint ctt = new Constraint() {
    public void validate(Component comp, Object value) throws WrongValueException {    
        if (value =e= null || ((Integer)value).intValue() < 100)        
            throw new WrongValueException(comp, "At least 100 must be specified");            
    }    
}
    ]]></zscript>    
    <intbox constraint="${ctt}"/>    
</window>

<?taglib uri="http://www.zkoss.org/dsp/web/core" prefix="c"?>
<textbox constraint="${c:new('my.EmailValidator')}"/>

<textbox>
    <attribute name="onChange">    
        if (!self.value.equals("good")) {        
            self.value = "try again";            
            throw new WrongValueException(self, "Not a good answer!");            
        }        
    </attribute>    
</textbox>

<window title="Custom Constraint" border="normal">
    <zscript><![CDATA[    
class MyConst implements Constraint, CustomConstraint {
    //Constraint//    
    public void validate(Component comp, Object value) {    
        if (value == null || ((Integer)value).intValue() < 100)        
            throw new WrongValueException(comp, "At least 100 must be specified");            
    }    
    //CustomConstraint//    
    public void showCustomError(Component comp, WrongValueException ex) {    
        errmsg.setValue(ex != null ? ex.getMessage(): "");        
    }    
}
Constraint ctt = new MyConst();
    ]]></zscript>    
    <hbox>    
        Enter a number at least 100:        
        <intbox constraint="${ctt}"/>        
        <label id="errmsg"/>        
    </hbox>    
</window>

<script type="text/javascript"><![CDATA[
    //Running at the browser    
    window.Validate_errorbox = function (id, boxid, msg) {    
        var html = '<div style="display:none;position:absolute" id="'        

            document.body.insertAdjacentHTML("afterbegin", html);return $e(boxid);}            
]]></script>

<grid>
    <rows>    
        <row>The onChanging textbox:         
            <textbox onChanging="copy.value = event.value"/></row>            
        <row>Instant copy:        
            <textbox id="copy" readonly="true"/></row>            
    </rows>    
</grid>

A calendar displays a 'flat' calendar and allows user to select a day from it.

<hbox>
    <calendar id="cal" onChange="in.value = cal.value"/>    
    <datebox id="in" onChange="cal.value = in.value"/>    
</hbox>

The compact Property

A calendar supports two different layouts and you can control it by use of the compact property.

<calendar compact="true"/>

The default value depends on the current Locale.

A progress meter is a bar that indicates how much of a task has been completed. The value property must be in the range between 0 and 100.

<progressmeter value="10"/>    

A slider is used to let user specifying a value by scrolling.

<slider id="slider" onScroll="Audio.setVolume(slider.curpos)"/>

A slider accepts a range of value starting from 0 to 100. You could change the maximal allowed value by the maxpos property.

A timer is an invisible component used to send the onTimer event to the server at the specified time or period. You could control a timer by the start and stop methods.

<window title="Timer demo" border="normal">
    <label id="now"/>    
    <timer id="timer" delay="1000" repeats="true"    
        onTimer="now.setValue(new Date().toString())"/>        
    <separator bar="true"/>    
    <button label="Stops timer" onClick="timer.stop()"/>    
    <button label="Starts timer" onClick="timer.start()"/>    
</window>

A paging component is used to separate long content into multiple pages. For example, assume that you have 100 items and prefer to show 20 items at a time, then you can use the paging components as follows.

<paging totalSize="100" pageSize="20"/>

Then, when a user clicks on the hyperlinks, the onPaging event is sent with an instance of org.zkoss.zul.event.PagingEvent to the paging component. To decide which portion of your 100 items are visible, you shall add a listener to the paging component.

<paging id="paging"/><zscript>List result = new SearchEngine().find("ZK");//assume SearchEngine.find() will return a list of items.paging.setTotalSize(result.size());paging.addEventListener("onPaging", new EventListener() {public void onEvent(Event event) {int pgno = event.getPaginal().getActivePage();int ofs = pgno * event.getPaginal().getPageSize();new Viewer().redraw(result, ofs, ofs + event.getPaginal().getPageSize() - 1);//assume redraw(List result, int b, int e) will display//from the b-th item to the e-th item}});</zscript>                                                                                                    

A window might have a title, a caption and a border. The title is specified by the title property. The caption is specified by declaring a child component called caption. All children of the caption component will appear to the right side of the title.

<window title="Demo" border="normal" width="350px">
    <caption>    
        <toolbarbutton label="More"/>        
        <toolbarbutton label="Help"/>        
    </caption>    
    <toolbar>    
        <toolbarbutton label="Save"/>        
        <toolbarbutton label="Cancel"/>        
    </toolbar>    
    What is your favorite framework?    
    <radiogroup>    
        <radio label="ZK"/>        
        <radio label="JSF"/>        
    </radiogroup>    
    </window>    

You could also specify a label and an image to a caption, and then the appearance is as follows.

<window id="win" title="Main" border="normal" width="200px">
    <caption image="/img/coffee.gif" label="Hi there!"/>    
    <checkbox label="Hello, World!"/>    
</window>

By setting the closable property to true, a close button is shown for the window, such that user could close the window by clicking the button. Once user clicks on the close button, an onClose event is sent to the window. It is processed by the onClose method of Window. Then, onClose, by default, detaches the window itself.

You can override it to do whatever you want. Or, you registered a listener to change the default behavior. For example, you might choose to hide rather than close.

<window closable="true" title="Detach on Close" border="normal" width="200px"
onClose="self.visible = false; event.stopPropagation();">
    In this example, this window hides itself when the close button is clicked.    
</window>

Notice that event.stopPropagation() must be called to prevent Window.onClose() being called.

Tip: If the window is a popup, the onOpen event will be sent to the window with open=false, when the popup is closed due to user's clicking outside of the window, or pressing ESC.

It is a bit confusing but onClose is sent to ask the server to detach or to hide the window. By default, the window is detached. Of course, the application can override it and do whatever it wants as described above.

On the other hand, onOpen is a notification. It is sent to notify the application that the client has hidden the window. The application cannot prevent it from be hidden, or change the behavior to be detached.

If you allow users to resize the window, you can specify true to the sizable property as follows. Once allowed, users can resize the window by dragging the borders.

<window id="win" title="Sizable Window" border="normal" width="200px" sizable="true">
    This is a sizable window.    
    <button label="Change Sizable" onClick="win.sizable = !win.sizable"/>    
</window>

ZK supports four different style classes for window: embedded, overlapped, popup and wndcyan. Of course, you can add more if you want.

By default, the sclass property is the same as the window mode, so windows in different modes appear differently. To change the appearance, simply assign a value to the sclass property as illustrated in the following example.

<hbox>
    <window title="Embedded Style" border="normal" width="200px">    
        Hello, Embedded!        
    </window>    
    <window title="Cyan Style" sclass="wndcyan" border="normal" width="200px">    
        Hello, Cyan!        
    </window>    
    <window title="Popup Style" sclass="popup" border="normal" width="200px">    
        Hello, Popup!        
    </window>    
    <window title="Modal Style" sclass="modal" border="normal" width="200px">    
        Hello, Modal!        
    </window>    
</hbox>

You can customize the look and feel of the content block of the window by specifying the contentStyle property.

<window title="My Window" border="normal" width="200px" contentStyle="background:yellow">
    Hello, World!    
</window>

<window id="win" title="Hi" width="150px" height="100px" contentStyle="overflow:auto" border="normal">
This is a long line to spead over several lines, and more content to display.
Finally, the scrollbar becomes visible.
This is another line.
</window>

The border property specifies whether to display a border for window. The default style sheets support only normal and none. The default value is none.

Of course, you can provide additional style class. For example,

<zk>
    <style>    
    div.wc-embedded-dash {    
    padding: 2px; border: 3px dashed #aab;    
    }    
    </style>    
    <window title="My Window" border="dash" width="200px">    
    Hello, World!    
    </window>    
</zk>

where wc-embedded-dash defines the style of the inner box of the window. The style class is named by concatenating wc^[37], the sclass property and the border property together and separating them with dash (-). In this example, sclass is embedded since it is an embedded window and no explicit sclass is assigned (so the default sclass is used).

A window could be in one of four different modes: overlapped, popup, modal, highlighted and embedded. By default, it is in the embedded mode. You could change the mode by use of the doOverlapped, doPopup, doModal, doHighlighted, and doEmbedded methods, depicted as follows.

<zk>
    <window id="win" title="Hi!" border="normal" width="200px">    
        <caption>        
            <toolbarbutton label="Close" onClick="win.setVisible(false)"/>            
        </caption>        
        <checkbox label="Hello, Wolrd!"/>        
    </window>    
        
    <button label="Overlap" onClick="win.doOverlapped();"/>    
    <button label="Popup" onClick="win.doPopup();"/>    
    <button label="Modal" onClick="win.doModal();"/>    
    <button label="Embed" onClick="win.doEmbedded();"/>    
    <button label="Highlighted" onClick="win.doHighlighted();"/>    
</zk>

<window title="My Overlapped" width="300px" mode="overlapped">
</window>

win1.doModal(); //the execution is suspended until win1 is closed

win2.doHighlighted(); //the execution won't be suspended
g1()

Modal Windows and Event Listeners

Unlike other modes, you can only put a window into the modal mode in an event listener. In other words, you can invoke doModal() or setMode("modal") in an event listener.

<zk>
    <window id="wnd" title="My Modal" visible="false" width="300px">    
        <button label="close" onClick="wnd.visible = false"/>        
    </window>    
    <button label="do it" onClick="wnd.doModal()"/>    
</zk>

On the other hand, the following is wrong if it executes in the Component Creation Phase^[38].

//t1.zul
<window title="My Modal" width="300px" closable="true" mode="modal">
</window>

It will cause the following result^[39] if you browse it directly.

The following codes will cause the same result.

//t2.zul
<window title="My Modal" width="300px" closable="true">
    <zscript>    
        self.doModal();        
    </zscript>    
</window>

If you need to create a modal window in page loading, you can post the onModal event as follows.

//t3.zul
<window title="My Modal" width="300px" closable="true">
    <zscript>    
    Events.postEvent("onModal", self, null);    
    </zscript>    
</window>

Note: the following codes execute correctly even if t1.zul sets the window's mode to modal directly (as shown above). Why? It executes in an event listener (for onClick).

<button label="do it">
    <attribute name="onClick">    
    Executions.createComponents("t1.zul", null, null);    
        //it loads t1.zul in this event listener for onClick        
    </attribute>    
</button>

In addition to the left and top properties, you can control the position of an overlapped/popup/modal window by use of the position property. For example, the following code snippet positions the window to the right-bottom corner.

<window width="300px" mode="overlapped" position="right,bottom">
...

The value of the position property can be a combination of the following constants by separating them with comma (,).

By default, its value is null. That is, the overlapped and popup window is positioned by the left and top properties, while the modal window is positioned at the center.

The XUL component set supports the following common dialogs to simplify some common tasks.

if (Messagebox.show("Remove this file?", "Remove?", Messagebox.YES | Messagebox.NO, Messagebox.QUESTION) == Messagebox.YES) {
    ...//remove the file    

alert("Wrong");
Messagebox.show("Wrong");

<window title="Messagebox not allowed in paging loading">
    <zscript>    
    //failed since show cannot be called in paging loading    
    if (Messagebox.show("Redirect?", "Redirect?",    
    Messagebox.YES | Messagebox.NO, Messagebox.QUESTION) == Messagebox.YES)    
        Executions.sendRedirect("another.zul");        
    </zscript>    
</window>

<window title="Fileupload Demo" border="normal">
    <image id="image"/>    
    <button label="Upload">    
        <attribute name="onClick">{        
            Object media = Fileupload.get();            
            if (media instanceof org.zkoss.image.Image)            
                image.setContent(media);                
            else if (media != null)            
                Messagebox.show("Not an image: "+media, "Error",                
                    Messagebox.OK, Messagebox.ERROR);                    
        }</attribute>        
    </button>    
</window>

<window title="fileupload demo" border="normal">
    <button label="Upload">    
        <attribute name="onClick"><![CDATA[{        
    Object media = Fileupload.get(5);    
    if (media != null)    
        for (int j = 0; j < media.length; ++j) {        
            if (media[j] instanceof org.zkoss.image.Image) {            
                Image image = new Image();                
                image.setContent(media[j]);                
                image.setParent(pics);                
            } else if (media[j] != null) {            
                Messagebox.show("Not an image: "+media[j], "Error",                
                    Messagebox.OK, Messagebox.ERROR);                    
            }            
        }        
        }]]></attribute>        
    </button>    
    <vbox id="pics"/>    
</window>

The fileupload Component

The fileupload component is not a modal dialog. Rather, it is a component, so it is placed inline with other components.

Note: In addition to providing the static get methods for opening the file upload dialogs, org.zkoss.zul.Fileupload itself is a component. It is the so-called fileuplod component.

For example,

<image id="img"/>
Upload your hot shot:
<fileupload onUpload="img.setContent(event.media)"/>

The onUpload Event

When the Upload button is pressed, the onUpload event is sent with an instance of the org.zkoss.zk.ui.event.UploadEvent event. You can then retreive the content of the upload files by use of the getMedia or getMedias methods.

Notice that getMedia and getMedias return null to indicate that no file is specified but the Upload button is pressed.

The onClose Event

In addition to onUpload, the onClose event is sent to notify that either the Upload button or the Cancel button is pressed. By default, it simply invalidates the fileupload component, i.e., all fields are cleaned up and redrawn. If you listen to this event to have the custom behavior.

<button label="Download download.html">
    <attribute name="onClick">{    
                java.io.InputStream is = desktop.getWebApp().getResourceAsStream("/test/download.html");                
    if (is != null)    
Filedownload.save(is, "text/html", "download.html");
    else    
        alert("/test/download.html not found");        
    }</attribute>    
</button>

Moreover, you could embed one layout component into another to divide the area into more regions as follows,

<borderlayout height="500px">
    <north size="30%">    
        <borderlayout height="250px">        
            <west border="normal">            

                Inner West                
            </west>            
            <center>            
                Inner Center                
            </center>            
            <east size="50%" border="normal">            
                Inner East                
            </east>            
        </borderlayout>        
    </north>    
    <center border="normal">    
        <borderlayout>        
            <west border="normal">            
                Inner West                
            </west>            
            <center border="normal">            
                Inner Center                
            </center>            
            <east size="30%" border="normal">            
            </east>            
        </borderlayout>        
    </center>    
</borderlayout>

You could specify the size property of the following children components (north,south,east,west) to determine their sizes. However, the function of size property depends on the type of children components (vertically or horizontally). For horizontal components (north, and south), the size property determines their height. As for vertically components (east, and west), the size property determines their width.

The border property determines whether there exists border for these layout components, including all children components of borderlayout. The following table specifies values of border property.

Here is an example.

<borderlayout height="500px">
    <north size="30%" border="normal">    
        The North        
    </north>    
    <east size="30%" border="normal">    
         The East        
    </east>    

    <center border="normal">    
        The Center        
    </center>    
    <west border="normal">    
        The West        
    </west>    
    <south border="normal">    
        The South        
    </south>    
</borderlayout>

If you would like to make your layout components splittable, you could assign the splittable property to be true.

In addition, you could make a layout component collapsible by specifying the collapsible property to be true.

<borderlayout height="500px">
    <north size="20%" splittable="true" collapsible="true"/>    
<east size="20%" splittable="true" collapsible="true"/>
    <center border="normal"/>    
<west size="20%" splittable="true" collapsible="true"/>
<south size="30%" border="normal" splittable="true" collapsible="true"/>
</borderlayout>

<north splittable="true" maxsize="500" minisize="200"/>

If the size of browser has been changed, the layout components will re-size themselves automatically to fit the size of the browser. If you would like those ZK components embedded within these layout components to be auto-resized also, you could specify the flex property of the layout component to be true.

To know whether a layout is collapsed, you can check the value of the open property (i.e., the isOpen method). To open or collapse programmingly, you can set the value of the open property (i.e., the setOpen method).

When a layout is collapsed or opened by a user, the onOpen event is sent to the application.

You could control the spacing among children of the box control. For example, the following example puts 5em at both the upper margin and the lower margin. Notice: the total space between two input fields is 10em.

<vbox spacing="5em">
    <textbox/>    
    <datebox/>    
</vbox>

Another example illustrated an interesting layout by use of zero spacing.

<window title="Box Layout Demo" border="normal">
    <hbox spacing="0">    
        <window border="normal">0</window>        
        <vbox spacing="0">        
            <hbox spacing="0">            
                <window border="normal">1</window>                
                <window border="normal">2</window>                
                <vbox spacing="0">                
                    <window border="normal">3</window>                    
                    <window border="normal">4</window>                    
                </vbox>                
            </hbox>            
            <hbox spacing="0">            
                <vbox spacing="0">                
                    <window border="normal">5</window>                     
                    <window border="normal">6</window>                    
                </vbox>                
                <window border="normal">7</window>                
                <window border="normal">8</window>                
                <window border="normal">9</window>                
            </hbox>            
        </vbox>        
    </hbox>    
</window>

You can specify the width for each cell of hbox with the widths property as follows.

<hbox width="100%" widths="10%,20%,30%,40%"><label value="10%"/><label value="20%"/><label value="30%"/><label value="40%"/></hbox>                

The value is a list of widths separated by comma. If any value is missed, no width is generated for the corresponding cell and the real width is up to the browser.

Similarly, you can specify the heights for each cell of vbox with the heights property. Actually, these two properties are the same since the orientation of a box can be horizontal or vertical depending on the orient property.

Components: splitter.

There may be times when you want to have two sections of a window where the user can resize the sections. This feature is accomplished by using a component called a splitter. It creates a skinny bar between two sections which allows either side to be resized.

A splitter must be put inside a box. When a splitter is placed inside a horizontal box (hbox), it will allow resizing horizontally. When a splitter is placed inside a vertical box (vbox), it will allow resizing vertically. For example,

Note: If you would like to use the original “os” CSS, you could specify the class name of

splitter with “splitter-os”.

And, the codes are as follows.

<hbox spacing="0" style="border: 1px solid grey" width="100%">
    <vbox height="200px">    
        Column 1-1: The left-top box. To know whether a splitter        
        is collapsed, you can listen to the onOpen event.        
        <splitter collapse="after"/>        
        Column 1-2: You can enforce to open or collapse programming        
        by calling setOpen method.        
    </vbox>    
    <splitter collapse="before"/>    
    Column 2: Whether a splitter allows users to open or collapse    
    depending on the collapse attribue.    
</hbox>

A tab panel could contain anything including another tab boxes.

<tabbox>
    <tabs>    
        <tab label="First"/>        
        <tab label="Second"/>        
    </tabs>    
    <tabpanels>    
        <tabpanel>        
        The first panel.        
        <tabbox>        
            <tabs>            
                <tab label="Nested 1"/>                
                <tab label="Nested 2"/>                
                <tab label="Nested 3"/>                
            </tabs>            
            <tabpanels>            
                <tabpanel>The first nested panel</tabpanel>                
                <tabpanel>The second nested panel</tabpanel>                
                <tabpanel>The third nested panel</tabpanel>                
            </tabpanels>            
        </tabbox>        
        </tabpanel>        
        <tabpanel>The second panel</tabpanel>        
    </tabpanels>    
</tabbox>

Tab boxes supports two molds: default and accordion. The effect of the accordion mold is as follows.

<tabbox mold="accordion">
    <tabs>    
        <tab label="First"/>        
        <tab label="Second"/>        
    </tabs>    
    <tabpanels>    
        <tabpanel>The first panel.</tabpanel>        
        <tabpanel>The second panel</tabpanel>        
    </tabpanels>    
</tabbox>

Developers can control whether the tabs are located by use of the orient property. By default, it is horizontal. You can change it to vertical, and the effect is as follows.

<tabbox width="400px" orient="vertical">
    <tabs>    
        <tab label="A"/>        
        <tab label="B"/>        
        <tab label="C"/>        
        <tab label="D"/>        
        <tab label="E"/>        
    </tabs>    
    <tabpanels>    
        <tabpanel>This is panel A</tabpanel>        
        <tabpanel>This is panel B</tabpanel>        
        <tabpanel>This is panel C</tabpanel>        
        <tabpanel>This is panel D</tabpanel>        
        <tabpanel>This is panel E</tabpanel>        
    </tabpanels>    
</tabbox>

Developers can control the alignment of tab by use the align property of tabs. By default, it is start (leftmost or uppermost). You can change it to center or end (rightmost or bottommost), and the effect is as follows.

<tabbox width="250px">
    <tabs align="end">    
        <tab label="Tab 1"/>        
        <tab label="Tab 2"/>        
    </tabs>    
    <tabpanels>    
        <tabpanel>This is panel 1</tabpanel>        
        <tabpanel>This is panel 2</tabpanel>        
    </tabpanels>    
</tabbox>

By setting the closable property to true, a close button is shown for the tab, such that user could close the tab and the corresponding tab panel by clicking the button. Once user clicks on the close button, an onClose event is sent to the tab. It is processed by the onClose method of Tab. Then, onClose, by default, detaches the tab itself and the corresponding tab panel.

See also window's closable property.

By setting the disabled property of tab to be true, the user could not select or close the corresponding tab by clicking the tab or close button. But, Developers can still control the selection or close of tab by program.

<tabbox width="300px" id="tbx">
    <tabs>    
        <tab label="Step 1" id="tb1" disabled="true"/>        
        <tab label="Step 2" id="tb2" disabled="true"/>        
        <tab label="Step 3" id="tb3" disabled="true"/>        
    </tabs>    
    <tabpanels>    
        <tabpanel><button label="to Step2" onClick="tbx.selectedTab=tb2"/></tabpanel>        
        <tabpanel><button label="to Step3" onClick="tbx.selectedTab=tb3"/></tabpanel>        
        <tabpanel>This is panel 3</tabpanel>        
    </tabpanels>    
</tabbox>

Like many other components, you can load the content of the tab panel only when it becomes visible. The simplest way is to use the fulfill attribute to defer the creation of the children of a tab panel.

<tabbox>
    <tabs>    
        <tab label="Preload" selected="true"/>        
        <tab id="tab2" label="OnDemand"/>        
    </tabs>    
    <tabpanels>    
        <tabpanel>        
    This panel is pre-loaded since no fulfill specified    
        </tabpanel>        
        <tabpanel fulfill="tab2.onSelect">        
    This panel is loaded only tab2 receives the onSelect event    
        </tabpanel>        
    </tabpanels>    
</tabbox>

If you prefer to create the children manually or manipulate the panel dynamically, you could listen to the onSelect event, and then fulfill the content of the panel when it is selected, as depicted below.

<tabbox id="tabbox" width="400" mold="accordion">
    <tabs>    
        <tab label="Preload"/>        
        <tab label="OnDemand" onSelect="load(self.linkedPanel)"/>        
    </tabs>    
    <tabpanels>    
        <tabpanel>        
    This panel is pre-loaded.    
        </tabpanel>        
        <tabpanel>        
        </tabpanel>        
    </tabpanels>    
    <zscript><![CDATA[    
    void load(Tabpanel panel) {    
        if (panel != null && panel.getChildren().isEmpty())        
            new Label("Second panel is loaded").setParent(panel);            
    }    
    ]]></zscript>    
</tabbox>

A grid could be scrollable if you specify the height property and there is not enough space to show all data.

<grid width="500px" height="130px">
    <columns>    
        <column label="Head 1"/>        
        <column label="Head 2" align="center"/>        
        <column label="Head 3" align="right"/>        
    </columns>    
    <rows>    
        <row>        
            <listbox mold="select">            
                <listitem label="Faster"/>                
                <listitem label="Fast"/>                
                <listitem label="Average"/>                
            </listbox>            
            <datebox/>            
            <textbox rows="2"/>            
        </row>        
        <row>        
            <checkbox checked="true" label="Option 1"/>            
            <checkbox label="Option 2"/>            
            <radiogroup>            
                <radio label="Apple"/>                
                <radio label="Orange" checked="true"/>                
                <radio label="Lemon"/>                
            </radiogroup>            
        </row>        
        <row>        
            <checkbox checked="true" label="Option 1"/>            
            <checkbox label="Option 2"/>            
            <radiogroup orient="vertical">            
                <radio label="Apple"/>                
                <radio label="Orange" checked="true"/>                
                <radio label="Lemon"/>                
            </radiogroup>            
        </row>        
    </rows>    
</grid>

If you allow users to resize the widths of columns, you can specify true to the sizable property of columns as follows. Once allowed, users can resize the widths of columns by dragging the border between adjacent column components.

<window>
    <grid>    
        <columns id="cs" sizable="true">        
            <column label="AA"/>            
            <column label="BB"/>            
            <column label="CC"/>            
        </columns>        
        <rows>        
            <row>            
                <label value="AA01"/>                
                <label value="BB01"/>                
                <label value="CC01"/>                
            </row>            
            <row>            
                <label value="AA01"/>                
                <label value="BB01"/>                
                <label value="CC01"/>                
            </row>            
            <row>            
                <label value="AA01"/>                
                <label value="BB01"/>                
                <label value="CC01"/>                
            </row>            
        </rows>        
    </grid>    
    <checkbox label="sizeable" checked="true" onCheck="cs.sizeable = self.checked"/>    
</window>

There are two ways to handle long content in a grid: scrolling and paging. The scrolling is enabled by specifying the height property as discussed in the previous section. The paging is enabled by specifying paging to the mold property. Once paging is enable, the grid separates the content into several pages and displays one page at a time as depicted below.

<grid width="300px" mold="paging" pageSize="4">
    <columns>    
        <column label="Left"/>        
        <column label="Right"/>        
    </columns>    
    <rows>    
        <row>        
            <label value="Item 1.1"/><label value="Item 1.2"/>            
        </row>        
        <row>        
            <label value="Item 2.1"/><label value="Item 2.2"/>            
        </row>        
        <row>        
            <label value="Item 3.1"/><label value="Item 3.2"/>            
        </row>        
        <row>        
            <label value="Item 4.1"/><label value="Item 4.2"/>            
        </row>        
        <row>        
            <label value="Item 5.1"/><label value="Item 5.2"/>            
        </row>        
        <row>        
            <label value="Item 6.1"/><label value="Item 6.2"/>            
        </row>        
        <row>        
            <label value="Item 7.1"/><label value="Item 7.2"/>            
        </row>        
    </rows>    
</grid>

Once the paging mold is set, the grid creates an instance of the paging component as the child of the grid. It then takes care of paging for the grid it belongs to.

<vbox>
<paging id="pg" pageSize="4"/>
<hbox>
    <grid width="300px" mold="paging" paginal="${pg}">    
        <columns>        
            <column label="Left"/><column label="Right"/>            
        </columns>        
        <rows>        
            <row>            
                <label value="Item 1.1"/><label value="Item 1.2"/>                
            </row>            
            <row>            
                <label value="Item 2.1"/><label value="Item 2.2"/>                
            </row>            
            <row>            
                <label value="Item 3.1"/><label value="Item 3.2"/>                
            </row>            
            <row>            
                <label value="Item 4.1"/><label value="Item 4.2"/>                
            </row>            
            <row>            
                <label value="Item 5.1"/><label value="Item 5.2"/>                
            </row>            
            <row>            
                <label value="Item 6.1"/><label value="Item 6.2"/>                
            </row>            
            <row>            
                <label value="Item 7.1"/><label value="Item 7.2"/>                
            </row>            
        </rows>        
    </grid>    
    <grid width="300px" mold="paging" paginal="${pg}">    
        <columns>        
            <column label="Left"/><column label="Right"/>            
        </columns>        
        <rows>        
            <row>            
                <label value="Item A.1"/><label value="Item A.2"/>                
            </row>            
            <row>            
                <label value="Item B.1"/><label value="Item B.2"/>                
            </row>            
            <row>            
                <label value="Item C.1"/><label value="Item C.2"/>                
            </row>            
            <row>            
                <label value="Item D.1"/><label value="Item D.2"/>                
            </row>            
            <row>            
                <label value="Item E.1"/><label value="Item E.2"/>                
            </row>            
            <row>            
                <label value="Item F.1"/><label value="Item F.2"/>                
            </row>            
        </rows>        
    </grid>    
</hbox>
</vbox>

grid.addEventListener(org.zkoss.zul.event.ZulEvents.ON_PAGING, new MyListener());

Grids support the sorting of rows directly. To enable the ascending order for a particular column, you assign a java.util.Comparator instance to the sortAscending property of the column. Similarly, you assign a comparator to the sortDescending property to enable the descending order.

As illustrated below, you first implement a comparator that compares any two rows of the grid, and then assign its instances to the sortAscending and sortDescending properties. Notice: the compare method is called with two org.zkoss.zul.Row instance.

<zk>
    <zscript>    
        class MyRowComparator implements Comparator {        
            public MyRowComparator(boolean ascending) {            
            ...            
            }            
            public int compare(Object o1, Object o2) {            
                Row r1 = (Row)o1, r2 = (Row)o2;                
                ....                
            }            
        }        
        Comparator asc = new MyRowComparator(true);        
        Comparator dsc = new MyRowComparator(false);        
    </zscript>    
    <grid>    
        <columns>        
            <column sortAscending="${asc}" sortDescending="${dsc}"/>            
...

<column sortDirection="ascending"/>

Row row = new Row();
row.setParent(rows);
row.appendChild(...);
...
if (!"natural".column.getSortDirection())
    column.sort("ascending".equals(column.getSortDirection()));    

column.setSortDirection("natural");
sort(myorder);

sort(myorder, true);

Like list boxes, grids support the live data. With live data, developers could separate the data from the view. In other words, developers needs only to provide the data by implementing the org.zkoss.zul.ListModel interface. Rather than manipulating the grid directly. The benefits are two folds.

There are three steps to use the live data.

In the following example, we prepared a list model called strset, assigned it to a grid through the model property. Then, the grid will do the rest.

<window title="Live Grid" border="normal">
    <zscript>    
        String[] data = new String[30];        
        for(int j=0; j &lt; data.length; ++j) {        
            data[j] = "option "+j;            
        }        
        ListModel strset = new SimpleListModel(data);        
    </zscript>    
    <grid width="100px" height="100px" model="${strset}">    
        <columns>        
            <column label="options"/>            
        </columns>        
    </grid>    
</window>

class MyListModel implements ListModel, ListModelExt {
    public void sort(Comparator cmpr, boolean ascending) {    
        //do the real sorting        
        //notify the grid (or listbox) that data is changed by use of ListDataEvent        
    }    
}

new ListDataEvent(this, ListDataEvent.CONTENTS_CHANGED, -1, -1) 

In addition to columns, you can specify auxiliary headers with the auxhead and auxheader components as follows.

<grid>
    <auxhead>    
        <auxheader label="H1'07" colspan="6"/>        
        <auxheader label="H2'07" colspan="6"/>        
    </auxhead>    
    <auxhead>    
        <auxheader label="Q1" colspan="3"/>        
        <auxheader label="Q2" colspan="3"/>        
        <auxheader label="Q3" colspan="3"/>        
        <auxheader label="Q4" colspan="3"/>        
    </auxhead>    
    <columns>    
        <column label="Jan"/><column label="Feb"/><column label="Mar"/>        
        <column label="Apr"/><column label="May"/><column label="Jun"/>        
        <column label="Jul"/><column label="Aug"/><column label="Sep"/>        
        <column label="Oct"/><column label="Nov"/><column label="Dec"/>        
    </columns>    
    <rows>    
        <row>        
        <label value="1,000"/><label value="1,100"/><label value="1,200"/>        
        <label value="1,300"/><label value="1,400"/><label value="1,500"/>        
        <label value="1,600"/><label value="1,700"/><label value="1,800"/>        
        <label value="1,900"/><label value="2,000"/><label value="2,100"/>        
        </row>        
    </rows>    
</grid>

The auxiliary headers support the colspan and rowsspan properties that the column header don't. However, as its name suggested, the auxiliary headers must be used with column.

Unlike column/columns, which can used only with grid, auhead/auxheader can be used with grid, listbox and tree.

Components: separator and space.

A separator is used to insert a space between two components. There are several ways to customize the separator.

<window>
    line 1 by separator    
    <separator/>    
    line 2 by separator    
    <separator/>    
    line 3 by separator<space bar="true"/>another piece    
    <separator spacing="20px"/>    
    line 4 by separator<space bar="true" spacing="20px"/>another piece    
</window>

Components: groupbox.

A group box is used to group components together. A border is typically drawn around the components to show that they are related.

The label across the top of the group box can be created by using the caption component. It works much like the HTML legend element.

Unlike windows, a group box is not an owner of the ID space. It cannot be overlapped or popup.

<groupbox width="250px">
    <caption label="Fruits"/>    
    <radiogroup>    
        <radio label="Apple"/>        
        <radio label="Orange"/>        
        <radio label="Banana"/>        
    </radiogroup>    
</groupbox>

In addition to the default mold, the group box also supports the 3d mold. If the 3d mold is used, it works similar to a simple-tab tab box. First, you could control whether its content is visible by the open property. Similarly, you could create the content of a group box when the onOpen event is received.

<groupbox mold="3d" open="true" width="250px">
    <caption label="fruits"/>    
    <radiogroup>    
        <radio label="Apple"/>        
        <radio label="Orange"/>        
        <radio label="Banana"/>        
    </radiogroup>    
</groupbox>

<groupbox mold="3d" width="150px" contentStyle="height:50px;overflow:auto">
    <caption label="fruits"/>    
    <radiogroup onCheck="fruit.value = self.selectedItem.label" orient="vertical">    
        <radio label="Apple"/>        
        <radio label="Orange"/>        
        <radio label="Banana"/>        
    </radiogroup>    
</groupbox>

Components: toolbar and toolbarbutton.

A toolbar is used to place a series of buttons, such as toolbar buttons. The toolbar buttons could be used without toolbars, so a toolbar could be used without tool buttons. However, tool buttons change their appearance if they are placed inside a toolbar.

The toolbar has two orientation: horizontal and vertical. It controls how the buttons are placed.

<toolbar>
    <toolbarbutton label="button1"/>    
    <toolbarbutton label="button2"/>    
</toolbar>

A menu command is associated with a menu item. There are two ways to associate a command to it: the onClick event and the href property. If a event listener is added for a menu item for the onClick event, the listener is invoked when the item is clicked.

<menuitem onClick="draft.save()"/>

On the other hand, you could specify the href property to hyperlink to the specified URL when a menu item is clicked.

<menuitem href="/edit"/>
<menuitem href="http://zk1.sourceforge.net"/>

If both of the event listener and href are specified, they will be executed. However, when the event listener get executed in the server, the browser might already change the current URL to the specified one. Thus, all responses generated by the event listener will be ignored.

A menu item could be used as a check box. The checked property denotes whether this menu item is checked. If checked, a check icon is appeared in front of the menu item.

In addition to programming the checked property, you could specify the autocheck property to be true, such that the checked property is toggled automatically when user clicks the menu item.

<menuitem label="" autocheck="true"/>

By default, the popup menu is opened when user clicks on it. You might change this to automatically popup menu when the mouse moves over it. This is done by setting the autodrop property to true.

<menubar autodrop="true">
    ...    
</menubar>

When a menupopup is going to appear (or hide), an onOpen event is sent to the menupopup for notification. For sophisticated applications, you can defer the creation of the content of the menupopup or manipulate the content dynamically, until the onOpen event is received. Refer to the Load on Demand section in th ZK User Interface Markup Language chapter for details.

Like box, you could control the orientation of a menu by use of the orient property. By default, the orientation is horizontal.

Like other components, you could change the menu dynamically, including properties and creating sub menus. Refer to menu.zul under the test directory in zkdemo.

In addition to open a popup when user right-clicks a component, ZK can open a popup under other circumstances.

For example,

<window title="Context Menu and Right Click" border="normal" width="360px">
    <label value="Move Mouse Over Me!" tooltip="editPopup"/>    
    <separator bar="true"/>    
    <label value="Tooptip for Another Popup" tooltip="any"/>    
    <separator bar="true"/>    
    <label value="Click Me!" popup="editPopup"/>    

    <menupopup id="editPopup">    
            <menuitem label="Undo"/>            
            <menuitem label="Redo"/>            
            <menu label="Sort">            
        <menupopup>        
            <menuitem label="Sort by Name" autocheck="true"/>            
            <menuitem label="Sort by Date" autocheck="true"/>            
        </menupopup>        
            </menu>            
    </menupopup>    
    <popup id="any" width="300px">    
        <vbox>        
            ZK simply rich.            
                                    <toolbarbutton label="ZK your killer Web application now!"href="http://zk1.sourceforge.net"/>                                    
        </vbox>        
</popup>
</window>

Notice that you can specify any identifier in the popup, tooltip and context properties, as long as they are in the same page. In other words, it is not confined by the ID space.

When a context menu, a tooltip or a popup is going to appear (or hide), an onOpen event is sent to the context, tooltip or poup menu for notification. The event is an instance of the org.zkoss.zk.ui.event.OpenEvent class, and you can retrieve the component that causes the context menu, tooltip or popup to appear by calling the getReference method.

To improve the performance, you defer the creation of the content until it becomes visible – i.e., until the onOpen event is received.

The simplest way to defer the creation of the content is to use the fulfill attribute as shown below.

<popup id="any" width="300px" fulfill="onOpen">
<button label="Hi"/><!-- whatever content -->
</popup>

Then, the content (the Hi button) won't be created when the page is loaded. Rather, the content is created when the onOpen event is received at the first time.

If you prefer to dynamically manipulate the content in Java, you can listen to the onOpen event as depicted below.

<popup id="any" width="300px">
    <attribute name="onOpen">    
    if (event.isOpen()) {    
        if (self.getChildren().isEmpty()) {        
            new Button("Hi").seParent(self);            
            ...            
        }        
        if (event.getReference() instanceof Textbox) {        
            //you can do component-dependent manipulation here            
            ...            
        }        
    }    
    </attribute></popup>    

The list box also supports multiple columns. When user selects an item, the entire row is selected.

To specify a multi-column list, you need to specify the listcell components as collumns of each listitem (as a row).

<listbox width="200px">
    <listitem>    
        <listcell label="George"/>        
        <listcell label="House Painter"/>        
    </listitem>    
    <listitem>    
        <listcell label="Mary Ellen"/>        
        <listcell label="Candle Maker"/>        
    </listitem>    
    <listitem>    
        <listcell label="Roger"/>        
        <listcell label="Swashbuckler"/>        
    </listitem>    
</listbox>

You could specify the column headers by use of listhead and listheader as follows^[40]. In addition to label, you could specify an image as the header by use of the image property.

<listbox width="200px">
    <listhead>    
        <listheader label="Name"/>        
        <listheader label="Occupation"/>        
    </listhead>    
...
</listbox>

You could specify the column footers by use of listfoot and listfooter as follows. Notice that the order of listhead and listfoot doesn't matter. Each time a listhead instance is added to a list box, it must be the first child, and a listfoot instance the last child.

<listbox width="200px">
    <listhead>    
        <listheader label="Population"/>        
        <listheader align="right" label="%"/>        
    </listhead>    
    <listitem id="a" value="A">    
        <listcell label="A. Graduate"/>        
        <listcell label="20%"/>        
    </listitem>    
    <listitem id="b" value="B">    
        <listcell label="B. College"/>        
        <listcell label="23%"/>        
    </listitem>    
    <listitem id="c" value="C">    
        <listcell label="C. High School"/>        
        <listcell label="40%"/>        
    </listitem>    
    <listitem id="d" value="D">    
        <listcell label="D. Others"/>        
        <listcell label="17%"/>        
    </listitem>    
    <listfoot>    
        <listfooter label="More or less"/>        
        <listfooter label="100%"/>        
    </listfoot>    
</listbox>

You could create a drop-down list by specifying the select mold and single row. Notice you cannot use multi-column for the drop-down list.

<listbox mold="select" rows="1">
    <listitem label="Car"/>    
    <listitem label="Taxi"/>    
    <listitem label="Bus" selected="true"/>    
    <listitem label="Train"/>    
</listbox>

When user clicks on a list item, the whole item is selected and the onSelect event is sent back to the server to notify the application. You could control whether a list box allows multiple selections by setting the multiple property to true. The default value is false.

A list box is scrollable if you specify the rows property or the height property, and there is no enough to show all list items.

<listbox width="250px" rows="4">
    <listhead>    
        <listheader label="Name" sort="auto"/>        
        <listheader label="Gender" sort="auto"/>        
    </listhead>    
    <listitem>    
        <listcell label="Mary"/>        
        <listcell label="FEMALE"/>        
    </listitem>    
    <listitem>    
        <listcell label="John"/>        
        <listcell label="MALE"/>        
    </listitem>    
    <listitem>    
        <listcell label="Jane"/>        
        <listcell label="FEMALE"/>        
    </listitem>    
    <listitem>    
        <listcell label="Henry"/>        
        <listcell label="MALE"/>        
    </listitem>    
    <listitem>    
        <listcell label="Michelle"/>        
        <listcell label="FEMALE"/>        
    </listitem>    
</listbox>

Like columns, you can set the sizable property of listhead to true to allow users to resize the width of list headers. Similarly, the onColSize event is sent when a user resized the widths.

Like grids, you can use multiple pages to represent long content for list boxes by specifying the paging mold. Similarly, you can control how many items for each page to display, whether to use an external paging component and whether to customize the behavior when a page is selected. Refer to the Grids section for more details.

List boxes support sorting of list items directly. There are a few ways to enable the sorting of a particular column. The simplest way is to set the sort property of the list header to auto as follows. Then, the column that the list header is associated with is sortable based on the label of each list cell of the specified column.

<zk>
    <listbox width="200px">    
        <listhead>        
            <listheader label="name" sort="auto"/>            
            <listheader label="gender" sort="auto"/>            
        </listhead>        
        <listitem>        
            <listcell label="Mary"/>            
            <listcell label="FEMALE"/>            
        </listitem>        
        <listitem>        
            <listcell label="John"/>            
            <listcell label="MALE"/>            
        </listitem>        
        <listitem>        
            <listcell label="Jane"/>            
            <listcell label="FEMALE"/>            
        </listitem>        
        <listitem>        
            <listcell label="Henry"/>            
            <listcell label="MALE"/>            
        </listitem>        
            </listbox>            
</zk>

<zscript>
    Comparator asc = new ListitemComarator(-1, true, true);    
    Comparator dsc = new ListitemComarator(-1, false, true);    
</zscript>
<listbox>
    <listhead>    
        <listheader sortAscending="${asc}" sortDescending="${dsc}"/>        
...

<listheader sortDirection="ascending"/>

new Listem("New Stuff").setParent(listbox);
if (!"natural".header.getSortDirection())
    header.sort("ascending".equals(header.getSortDirection()));    

Like grids^[41], list boxes support the live data. With live data, developers could separate the data from the view. In other words, developers needs only to provide the data by implementing the org.zkoss.zul.ListModel interface. Rather than manipulating the list box directly. The benefits are two folds.

There are three steps to use the live data.

In the following example, we prepared a list model called strset, assigned it to a list box through the model property. Then, the list box will do the rest.

<window title="Livedata Demo" border="normal"><zscript>String[] data = new String[30];for(int j=0; j &lt; data.length; ++j) {data[j] = "option "+j;}ListModel strset = new SimpleListModel(data);</zscript><listbox width="200px" rows="10" model="${strset}"><listhead><listheader label="Load on demend"/></listhead></listbox></window>                                                                                        

class MyListModel implements ListModel, ListModelExt {
    public void sort(Comparator cmpr, boolean ascending) {    
        //do the real sorting        
        //notify the listbox (or grid) that data is changed by use of ListDataEvent        
    }    
}

new ListDataEvent(this, ListDataEvent.CONTENTS_CHANGED, -1, -1)

In theory, a list cell could contain any other components, as depicted below.

<listbox width="250px">
    <listhead>    
        <listheader label="Population"/>        
        <listheader label="Percentage"/>        
    </listhead>    
    <listitem value="A">    
        <listcell><textbox value="A. Graduate"/></listcell>        
        <listcell label="20%"/>        
    </listitem>    
    <listitem value="B">    
        <listcell><checkbox label="B. College"/></listcell>        
        <listcell><button label="23%"/></listcell>        
    </listitem>    
    <listitem value="C">    
        <listcell label="C. High School"/>        
        <listcell><textbox cols="8" value="40%"/></listcell>        
    </listitem>    
</listbox>

Notes:

Each tree item has the open property used to control whether to display its child items. The default value is true. By setting this property to false, you could control what part of the tree is invisible.

<treeitem open="false">

When a user clicks on the +/- button, he opens the tree item and makes its children visible. The onOpen event is then sent to the server to notify the application.

For sophisticated applications, you can defer the creation of the content of the tree item or manipulate its content dynamically, until the onOpen event is received. Refer to the Load on Demand section in th ZK User Interface Markup Language chapter for details.

When user clicks on a tree item, the whole item is selected and the onSelect event is sent back to the server to notify the application. You could control whether a tree control allows multiple selections by setting the multiple property to true. The default value is false.

The pageSize property controls the number of tree items to display at once. By default, it is 10. That is, at most 10 tree items are displayed at the client for each level as depicted in the right figure.

A user can click to see more tree items (i.e., enlarge pageSize), or click or to scroll up and down.

If you want to display all tree items, simply set pageSize to -1. However, it is not recommended if the tree control is huge, since the browser is too slow to handle a tree with huge number of items.

In addition to the pageSize property of a tree control, you can change the page size of each treechildren instance by modifying the pageSize property of the corresponding treechildren instance.

As illustrated below, you could listen to the onOpen event, and then load the children of an tree item. Similarly, you could do create-on-open for group boxes.

<tree width="200px">
    <treecols>    
        <treecol label="Subject"/>        
        <treecol label="From"/>        
    </treecols>    
    <treechildren>    
        <treeitem open="false" onOpen="load()">        
            <treerow>            
                <treecell label="Intel Snares XML"/>                
                <treecell label="David Needle"/>                
            </treerow>            
            <treechildren/>            
        </treeitem>        
    </treechildren>    
    <zscript>    
    void load() {    
        Treechildren tc = self.getTreechildren();        
        if (tc.getChildren().isEmpty()) {        
            Treeitem ti = new Treeitem();            
            ti.setLabel("New added");            
            ti.setParent(tc);            
        }        
    }    
    </zscript>    
</tree>

By default, the drop-down list won't be opened until user clicks the

button, or press Alt+DOWN. However, you could set the autodrop property to true, such that the drop-down list is opened as soon as user types any character. This is helpful for novice users, but it might be annoying for experienced users.

<combobox autodrop="true"/>

You could add a description to each combo item to make it more descriptive. In addition, you could assign an image to each combo item.

<combobox>
    <comboitem label="Simple and Rich" image="/img/coffee.gif"    
    description="The simplest way to make Web applications rich"/>    
    <comboitem label="Cool!" image="/img/corner.gif"    
    description="The coolest technology"/>    
    <comboitem label="Ajax and RIA" image="/img/cubfirs.gif"    
    description="Rich Internet Application by Ajax"/>    
</combobox>

Like other components that support images, you could use the setImageContent method to assign the content of a dynamically generated image to the comboitem component. Refer to the Image section for details.

The onOpen event is sent to the application, when user opens the drop-down list. To defer the creation of combo items, you can use the fulfill attribute as shown below.

<combobox fulfill="onOpen">
    <comboitem label="Simple and Rich"/>    
    <comboitem label="Cool!"/>    
    <comboitem label="Ajax and RIA"/>    
</combobox>

Alternatively, you can listen to the onOpen event, and then prepare the drop-down list or change it dynamically in the listener as shown below.

<combobox id="combo" onOpen="prepare()"/>
<zscript>
    void prepare() {    
        if (event.isOpen() &amp;&amp; combo.getItemCount() == 0) {        
            combo.appendItem("Simple and Rich");            
            combo.appendItem("Cool!");            
            combo.appendItem("Ajax and RIA");            
        }        
    }    
</zscript>

The appendItem method is equivalent to create a combo item and then assign its parent to the comobox.

Since a combobox is also a text box, the onChanging event will be sent if you add a listener for it. By listening to this event, you could manipulate the drop-down list as the Google Suggests^[42] does. This feature is sometimes called autocomplete.

As illustrated below, you could fill the drop-down list based on what user is entering.

<combobox id="combo" autodrop="true" onChanging="suggest()"/>
<zscript>
    void suggest() {    
        combo.getItems().clear();        
        if (event.value.startsWith("A")) {        
            combo.appendItem("Ace");            
            combo.appendItem("Ajax");            
            combo.appendItem("Apple");            
        } else if (event.value.startsWith("B")) {        
            combo.appendItem("Best");            
            combo.appendItem("Blog");            
        }        
    }    
</zscript>

Notice that, when the onChanging event is received, the content of the combobox is not changed yet. Thus, you cannot use the value property of the combobox. Rather, you shall use the value property of the event (org.zkoss.zk.ui.event.InputEvent).

A popup window could contain any kind of components, so it is developer's job to copy the value from and close the popup if one of item is selected.

In the above example, we copy the selected item's label to the bandbox, and then close the popup by the following statement.

<listbox width="200px" onSelect="bd.value=self.selectedItem.label; bd.closeDropdown();">

By default, the popup window won't be opened until user clicks the

button, or press Alt+DOWN. However, you could set the autodrop property to true, such that the popup is opened as soon as user types any character. This is helpful for novice users, but it might be annoying for experienced users.

<bandbox autodrop="true"/>

The onOpen event is sent to the application if the user opens the popup window. By use of the fulfill attribute with the onOpen value as shown below, you can defer the creation of the popup window.

<bandbox fulfill="onOpen">
    <bandpopup>    
    ...    
    </bandpopup>    
</bandbox>

Alternatively, you could prepare the popup window in Java by listening to the onOpen event, as depicted below.

<bandbox id="band" onOpen="prepare()"/>
<zscript>
    void prepare() {    
        if (event.isOpen() &amp;&amp; band.getPopup() == null) {        
            ...//create child elements            
        }        
    }    
</zscript>

Since a bandbox is also a text box, the onChanging event will be sent if you add a listener for it. By listening to this event, you could manipulate the popup window any way you like.

As illustrated below, you could fill the drop-down list based on what user is entering.

<bandbox id="band" autodrop="true" onChanging="suggest()"/>
<zscript>
    void suggest() {    
        if (event.value.startsWith("A")) {        
            ...//do something            
        } else if (event.value.startsWith("B")) {        
            ...//do another            
        }        
    }    
</zscript>

Notice that, when the onChanging event is received, the content of the bandbox is not changed yet. Thus, you cannot use the value property of the bandbox. Rather, you shall use the value property of the event (org.zkoss.zk.ui.event.InputEvent).

The above example is somehow a little bit misleading. In fact, developers don't have to prepare the real data before feed it into a chart because chart components support live data mechanism. With live data, developers could separate the data from the view. In other words, developer can add, change, and remove data from the data model and the chart would be redrawn accordingly. For some advanced implementation, developers can even provide their own chart model by implementing the org.zkoss.zul.ChartModel interface.

When a user views a chart and finds something interesting, it is natural that the user would like to see the detail information regarding that interesting point. It is usually a pie in a pie chart, a bar in a bar chart or a point in a line chart. Chart components support such drill down facility by automatically cutting a chart into area components and users can then click on the chart to fire an onClick MouseEvent. Developers then locate the area component and do whatever appropriate drill down.

In the area component's componentScope there are some useful information that developers can use them.

In the following example, we provide an onClick event listener on the chart. It locates the associated area component and show the category of that area (i.e. the pie).

<chart id="mychart" type="pie" width="400" height="250">
<attribute name="onClick">
alert(self.getFellow(event.getArea()).getAttribute("category"));
</attribute>
<zscript><![CDATA[
PieModel model = new PieModel();
model.setValue("C/C++", new Double(17.5));
model.setValue("PHP", new Double(32.5));
model.setValue("Java", new Double(43.2));
model.setValue("VB", new Double(10.0));
mychart.setModel(model);
]]></zscript>
</chart>

Chart components also provide a area renderer mechanism that developers can manipulate the cutting area components of the chart.

Only two steps needed to use the area renderer.

So developers get a chance to change the area component's properties or insert more information into the area component's componentScope property and thus be passed through to the onClick event listener.

With ZK, you could make a component draggable by assigning any value, other than "false", to the draggable property. To disable it, assign it with "false".

<image draggable="true"/>

Similarly, you could make a component droppable by assigning "true" to the droppable property.

<hbox droppable="true"/>

Then, user could drag a draggable component, and then drop it to a droppable component.

Once user has dragged a component and dropped it to another component, the component that the user dropped the component to will be notified by the onDrop event. The onDrop event is an instance of org.zkoss.ui.event.DropEvent. By calling the getDragged method, you could retrieve what has been dragged (and dropped).

Notice that the target of the onDrop event is the droppable component, not the component being dragged.

The following is a simple example that allows users to reorder list items by drag-and-drop.

<window title="Reorder by Drag-and-Drop" border="normal">
    Unique Visitors of ZK:    
    <listbox id="src" multiple="true" width="300px">    
        <listhead>        
            <listheader label="Country/Area"/>            
            <listheader align="right" label="Visits"/>            
            <listheader align="right" label="%"/>            
        </listhead>        
        <listitem draggable="true" droppable="true" onDrop="move(event.dragged)">        
            <listcell label="United States"/>            
            <listcell label="5,093"/>            
            <listcell label="19.39%"/>            
        </listitem>        
        <listitem draggable="true" droppable="true" onDrop="move(event.dragged)">        
            <listcell label="China"/>            
            <listcell label="4,274"/>            
            <listcell label="16.27%"/>            
        </listitem>        
        <listitem draggable="true" droppable="true" onDrop="move(event.dragged)">        
            <listcell label="France"/>            
            <listcell label="1,892"/>            
            <listcell label="7.20%"/>            
        </listitem>        
        <listitem draggable="true" droppable="true" onDrop="move(event.dragged)">        
            <listcell label="Germany"/>            
            <listcell label="1,846"/>            
            <listcell label="7.03%"/>            
        </listitem>        
        <listitem draggable="true" droppable="true" onDrop="move(event.dragged)">        
            <listcell label="(other)"/>            
            <listcell label="13,162"/>            
            <listcell label="50.01%"/>            
        </listitem>        
        <listfoot>        
            <listfooter label="Total 132"/>            
            <listfooter label="26,267"/>            
            <listfooter label="100.00%"/>            
        </listfoot>        
    </listbox>    
    <zscript>    
    void move(Component dragged) {    
        self.parent.insertBefore(dragged, self);        
    }    
    </zscript>    
</window>

When a user drag-and-drops a list item or a tree item, the selection status of these items won't be changed. Visually only the dragged item is moved, but you can handle all selected items at once by looking up the set of all selected items as depicted below.

public void onDrop(DropEvent evt) {
    Set selected = ((Listitem)evt.getDragged()).getListbox().getSelectedItems();    
    //then, you can handle the whole set at once    
}

Notice that the dragged item may not be selected. Thus, you may prefer to change the selection to the dragged item for this case, as shown below.

Listitem li = (Listitem)evt.getDragged();
if (li.isSelected()) {
    Set selected = ((Listitem)evt.getDragged()).getListbox().getSelectedItems();    
    //then, you can handle the whole set at once    
} else {
    li.setSelected(true);    
    //handle li only    
}

It is common that a droppable component doesn't accept all draggable components. For example, an e-mail folder accepts only e-mails and it rejects contacts or others. You could silently ignore non-acceptable components or alert an message, when onDrop is invoked.

To have better visual effect, you could identify each type of draggable components with an identifier, and then assign the identifier to the draggable property.

<listitem draggable="email"/>
...
<listitem draggable="contact"/>

Then, you could specify a list of identifiers to the droppable property to limit what can be dropped. For example, the following image accepts only email and contact.

<image src="/img/send.png" droppable="email, contact" onDrop="send(event.dragged)"/>

To accept any kind of draggable components, you could specify "true" to the droppable property. For example, the following image accepts any kind of draggable components.

<image src="/img/trash.png" droppable="true" onDrop="remove(event.dragged)"/>

On the other hand, if the draggable property is "true", it means the component belongs to anonymous type. Furthermore, only components with the droppable property assigned to "true" could accept it.

The simplest way is to use a XUL component called html^[43] to embed whatever HTML tags you want to send directly to the browser. To avoid ZK from interpreting the HTML tags, you usually enclose them with <![CDATA[ and ]]>. In other words, they are not the child component. Rather, they are stored in the content property^[44]. Notice you can use EL expressions in it.

<window title="Html Demo">
    <html><![CDATA[    
        <h4>Hi, ${parent.title}</h4>        
        <p>It is the content of the html component.</p>        
    ]]></html>    
</window>

where <h4>...</p> will become the content of the html element (see also the getContent method of the org.zkoss.zul.Html class).

Tip: You can use the attribute element to specify the XHTML fragment instead of CDATA as follows.

<html> <attribute name="content"> <h4>Hi, ${parent.title}</h4> <p>It is the content of the html component.</p>

</attribute></html>

Refer to the attribute Element section in the ZK User Interface Markup Language chpater..

The html component generates the HTML SPAN tag to enclose the content. In other words, it generates the following HTML tags when rendered to the browser.

<span id="z_4a_3">
    <h4>Hi, Html Demo</h4>    
    <p>It is the content of the html component.</p>    
</span>

The html component is no different to other XUL components. For example, you specify the CSS style and change its content dynamically.

<html id="h" style="border: 1px solid blue;background: yellow"><![CDATA[
    <ul>    
        <li>Native browser content</li>        
    </ul>    
]]></html>
<button label="change" onClick="l.setContent(&quot;Hi, Update&quot;)"/>

Notice that, since SPAN is used to enclose the embedded HTML tags, the following code snippet is incorrect.

<html><![CDATA[
    <ul>    
        <li> <!-- incorrect since <ul><li> is inside <span> -->        
]]></html>

<textbox/>

<html><![CDATA[
        </li>        
    </ul>    
]]</html>

If you need to generate the embedded HTML tags directly without the enclosing SPAN tag, you can use the Native namespace as described in the following section.

With the Native namespace, a XML element in a ZUML page denotes that it shall be sent to the browser directly rather than becoming a ZK component. For example,

<n:ul xmlns:n="http://www.zkoss.org/2005/zk/native">
    <n:li>    
    <textbox/>    
    </n:li>    
    <n:li>    
    <textbox/>    
    </n:li>    
</n:ul>

will generate the following HTML tags to the browser:

<ul>
    <li>    
    <input id="z_a3_2"/>    
    </li>    
    <li>    
    <input id="z_a3_5"/>    
    </li>    
</ul

where <input> is the HTML tag(s) generated by the textbox component. Unlike textbox in the example above, ZK Loader doesn't really create a component for each of ul and li.^[45] Rather, they are sent to the client directly. Of course, they must be recognizable by the client. For HTML browsers, they must be the valid HTML tags.

Since the elements associated with the Native namespace are sent directly to the client, they are not ZK components, and they don't have the counterpart at the client. The advantage is the better performance in term of both memory and processing time. On the other hand, the disadvantage is you cannot access or change them dynamically. For example, the following code snippet is incorrect, since there is no component called x.

<n:ul id="x" xmlns:n="http://www.zkoss.org/2005/zk/native"/>
<button label="add" onClick="new Li().setParent(x)"/>

If you want to change them dynamically, you can specify the XHTML namespace as described in the following section.

native:URI-of-another-namespace

<window>
    <svg width="100%" height="100%" version="1.1"    
xmlns="native:http://www.w3.org/2000/svg">
        <ellipse cx="240" cy="100" rx="220" ry="30" style="fill:purple"/>        
    </svg>    
</window>

<div id="z_lx_0c" z.type="zul.wnd.Wnd">46The real HTML output of window depends on its implementation. Here is only a simplified version.
    <svg width="100%" height="100%" version="1.1"    
xmlns="http://www.w3.org/2000/svg">
        <ellipse cx="240" cy="100" rx="220" ry="30" style="fill:purple"/>        
    </svg>    
</div>

The XHTML namespace represents the XHTML component set, just like the ZUL namespace (http://www.zkoss.org/2005/zul) represents the ZUL component set. Thus, a XML element specified with the XHTML namespace simply denotes a component that shall be created based on the component definition from the XHTML component set. For example, the statement blow specifies a component that shall be created as an instance of the component definition called ul, and ul belongs to the XHTML component set:

<h:ul xmlns:h="http://www.w3.org/1999/xhtml">

In other words, ZK loader will search the XHTML component set for the component definition called ul , and then create an instance based on it.

The following is another yet more complete example.

<window title="mix HTML demo" xmlns:h="http://www.w3.org/1999/xhtml">
    <h:table border="1">    
        <h:tr id="row1">        
            <h:td>column 1</h:td>            
            <h:td>            
                <listbox id="list" mold="select">                
                    <listitem label="AA"/>                    
                    <listitem label="BB"/>                    
                </listbox>                
            </h:td>            
        </h:tr>        
    </h:table>    
    <button label="add" onClick="new org.zkoss.zhtml.Td().append(row1)"/>    
</window>

Unlike the html components, where HTML tags are stored in the content property, ZK loader creates one component for each of them. The advantage is that you can manipulate each individual HTML tag dynamically, as depicted in the above example (the add button). The disadvantage is that they take longer to process and more space to maintain.

Tip: Unlike the XHTML namespace, the Native namespace doesn't represent another component set. It is a reserved namespace to tell ZK Loader to send them directly to the client for better performance.

The include component is used to include the output generated by another servlet. The servlet could be anything including JSF, JSP and even another ZUML page.

<window title="include demo" border="normal" width="300px">
    Hello, World!    
    <include src="/userguide/misc/includedHello.zul"/>    
    <include src="/html/frag.html"/>    
</window>

Like all other properties, you could dynamically change the src attribute to include the output from a different servlet at the run time.

If the included output is another ZUML, developers are allowed to access components in the included page as if they are part of the containing page.

<include src="mypage?some=something"/>

${param.some}

<include src="mypage" some="something" another="${expr}"/>

${requestScope.some}

<window onCreate="desktop.getPages()"> <!-- the included page not available -->
    <include src="/my.zul"/>    
    <zscript>    
        desktop.getPages(); //the included page not available yet        
    </zscript>    
    <button label="Hit" onClick="desktop.getPages()"/>    
        <!-- Yes, the included page is available when onClick is received -->        
</window>

The style component is used to specify CSS styles in a ZUML page. The simplest format is as follows.

<style>
.blue {
color: white; background-color: blue;
}
</style>
<button label="OK" sclass="blue"/>

Tip: To configure a style sheet for the whole application, specify theme-uri in zk.xml, refer to the Themes section in the Internationalization chpater, or Appendix B in the Developer's Reference for details. To configure a style sheet for a language, use the language addon, refer to the Component Development Guide.

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"/>

The above statement actually sends the following HTML tags^[47] to the browser, so the specified file must be accessible by the browser.

<link rel="stylesheet" href="/css/mystyles.css"/>

In other words, you cannot specify "/WEB-INF/xx" or "C:/xx/yy".

Like other URI, it accepts "*" for loading browser and Locale dependent style sheet. Refer to the Browser and Locale Dependent URI section in the Internationalization chapter for details.

The script component is used to specify the script codes running at the browser. Notice that, unlike zscript, the script codes are running at the browser. They are usually written in JavaScript which is supported by the most of browsers. The simplest format is as follows.

<script type="text/javascript">
function myfunc() {
    $e("${win.uuid}").style.backgroundColor = "blue";    
}
</script>

As shown above, you can use EL expressions (${win.uuid}) in script codes.

Of course, you can reference to an external JavaScript file with the src property as follows.

<script src="/js/super.js" type="text/javascript"/>

With ZK, developers rarely need to specify JavaScript codes to execute, since the ZK applications are running at the server (and execute in your favorite language). They are usually to customize the behavior of ZK Client Engine, or to run the legacy JavaScript libraries.

The iframe component uses the HTML IFRAME tag to delegate a portion of the display to another URL. Though the appearance looks similar to the include component. The concept and meaning of the iframe component is different.

The content included by the include component is a fragment of the whole HTML page. Because the content is part of the HTML page, the content is part of the desktop and you could access any components, if any, inside of the include component. The inclusion is done at the server, and the browser knows nothing about it. It means the URL specified by the src property could be any internal resource.

The content of the iframe component is loaded by the browser as a separate page. Because it is loaded as a separate page, the format of the content could be different from HTML. For example, you could embed an PDF file.

<iframe src="/my.pdf"/>
...other HTML content

Tip: By default, there is no border. To enable it, use the style attribute to specify it. For example,<iframe style="border:1px inset" src="http://www.zkoss.org"/>

The embedding is done by the browser, when it interprets the HTML page containing the IFRAME tag. It also implies that the URL must be a resource that you can access from the browser.

Like the image and audio components^[48], you could specify the dynamically generated content. A typical example is you could use JasperReport^[49] to generate a PDF report in a binary array or stream, and then pass the report to an iframe component by wrapping the result with the org.zkoss.util.media.AMedia class.

In the following example, we illustrate that you could embed any content by use of iframe, as long as the client supports its format.

<window title="iframe demo" border="normal">
    <iframe id="iframe" width="95%"/>    
    <separator bar="true"/>    
    <button label="Upload">    
        <attribute name="onClick">{        
            Object media = Fileupload.get();            
            if (media != null)            
                iframe.setContent(media);                
        }</attribute>        
    </button>    
</window>

This picture depicted the appearance after user uploaded an Microsoft PowerPoint file.

//Part of your, say, PHP page
<script type="text/script">
function onIframeChange(uuid, url) {
    do_whatever_you_need_in_the_technology_you_use(uuid, url);    
}
</script>

To work with legacy Web applications, you could specify the name property as you did for HTML pages. For example,

<window xmlns:h="http://www.w3.org/1999/xhtml">
<h:form method="post" action="/my-old-servlet">
<grid>
<rows>
<row>When <datebox name="when"/> Name <textbox name="name"/> Department
<combobox name="department">
<comboitem label="RD"/>
<comboitem label="Manufactory"/>
<comboitem label="Logistics"/>
</combobox>
</row>
<row>
<h:input type="submit" value="Submit"/>
</row>
</rows>
</grid>
</h:form>
</window>

Once users press the submit button, a request is posted to the my-old-servlet servlet with the query string as follows.

/my-old-servlet?when=2006%2F03%2F01&name=Bill+Gates&department=Manufactory

Thus, as long as you maintain the proper associations between name and value, your servlet could work as usual without any modification.

All input-types components support the name property, such as textbox, datebox, decimalbox, intbox, combobox, bandbox, slider and calendar.

In addition, list boxes and tree controls are also support the name property. If the multiple property is true and users select multiple items, then multiple name/value pairs are posted.

<listbox name="who" multiple="true" width="200px">
    <listhead>    
        <listheader label="name"/>        
        <listheader label="gender"/>        
    </listhead>    
    <listitem value="mary>    
        <listcell label="Mary"/>        
        <listcell label="FEMALE"/>        
    </listitem>    
    <listitem value="john">    
        <listcell label="John"/>        
        <listcell label="MALE"/>        
    </listitem>    
    <listitem value="jane">    
        <listcell label="Jane"/>        
        <listcell label="FEMALE"/>        
    </listitem>    
    <listitem value="henry">    
        <listcell label="Henry"/>        
        <listcell label="MALE"/>        
    </listitem>    
</listbox>

If both John and Henry are selected, then the query string will contain:

who=john&who=henry

Notice that, to use list boxes and tree controls with the name property, you have to specify the value property for listitem and treeitem, respectively. They are the values being posted to the servlets.

Because a form component could contain any kind of components, the rich user interfaces could be implemented independent of the existent servlets. For example, you could listen to the onOpen event and fulfill a tab panel as illustrated in the previous sections. Yet another example, you could dynamically add more rows to a grid control, where each row might control input boxes with the name property. Once user submits the form, the most updated content will be posted to the servlet.

In the JavaScript codes, you can reference to a component or other objects with the late-binding EL expression. The late-binding EL expression starts with #{ and ending with } as depicted below.

<button action="onmouseover: action.show(#{parent.tip})"/>

The late-binding EL expressions are evaluated as late as the Rendering Phase. On the other hand, if you assign an EL expression starting with ${, it will be evaluated at the Component Creation Phase, before assigning to the action property. For example,

<button action="onfocus: action.show(${tip}); onblur: action.hide(${tip})"/>
<div id="tip" visible="false">...</div>

will be evaluated to

<button action="onfocus: action.show(); onblur: action.hide()"/>
<div id="tip" visible="false">...</div>

since the tip component is not created when assigning the action property.

Even if the referenced component was created before action is assigned, it is still incorrect, since the ZUML loader has no knowledge of CSA, and it converts the component to a string by invoking the toString method.

Of course, it doesn't prevent you from using ${} in an action, as depicted below. Just remember it is evaluated before assigning the action property.

<variables myaction="onfocus: action.show(#{tip}); onblur: action.hide(#{tip});"
<button action="${myaction} onmouseover: action.show(#{parent.parent.tip})"/>

<grid>
    <columns>    
        <column/>        
        <column/>        
        <column/>        
    </columns>    
    <rows>    
        <row>        
<label value="text1: "/>
<textbox action="onfocus: action.show(#{help1}); onblur: action.hide(#{help1})"/>
<label id="help1" visible="false" value="This is help for text1."/>
        </row>        
        <row>        
<label value="text2: "/>
<textbox action="onfocus: action.show(#{help2}); onblur: action.hide(#{help2})"/>
<label id="help2" visible="false" value="This is help for text2."/>
        </row>        
    </rows>    
</grid>

The onshow and onhide actions are used to control the visual effect of displaying and hiding a component.

<zk>
    <button label="Show Overlapped" onClick="win.doOverlapped();"/>    
    <window id="win" border="normal" width="200px" mode="overlapped"    
action="onshow:anima.appear(#{self});onhide:anima.fade(#{self})" visible="false">
        <caption image="/img/inet.png" label="Hi there!"/>        
        <checkbox label="Hello, Effect!"/>        
    </window>    
</zk>

To simplify the CSA programming, ZK provides a few utilities objects that you can utilize.

<window title="Test of JavaScript Utilities">
    <html onClick='l.value = "onClick "+event.area'    
        onUser='l.value ="onUser " +org.zkoss.lang.Objects.toString(event.data)'><![CDATA[        
        <a href="javascript:;" onclick="comm.sendClick(this, 'Hi')">onClick with Hi</a>        
        <a href="javascript:;" onclick="comm.sendClick(this)">onClick with null</a>        
        <a href="javascript:;" onclick="comm.sendUser(this)">onUser with null</a>        
        <a href="javascript:;" onclick="comm.sendUser(this, 'One')">onUser with One</a>        
        <a href="javascript:;" onclick="comm.sendUser(this, 'One', 'Two')">onUser with [One, Two]</a>        
        <a href="javascript:;" onclick="comm.sendEvent(this, 'onUser', 'XYZ')">onUser with XYZ</a>        
    ]]></html>    
    <separator/>    
    <label id="l"/>    
</window>

<window>
    <div id="t" visible="false"    
    action="onshow: anima.slideDown(#{self}); onhide: anima.slideUp(#{self})">    
        <div><!-- the 2nd div is optional but sometimes it looks better with it -->        
            <groupbox>            
                <caption label="slide down"/>                
                Hi <textbox/>                
            </groupbox>            
            When? <datebox/>            
        </div>        
    </div>    
    <button label="toggle" onClick="t.visible = !t.visible"/>    
</window>

<window title="Animation Effects">
    <style>    
    .ctl{    
                border: 1pxoutset#777; background:#ddeecc;                
                        margin: 2px;margin-right:10px;padding-left: 2px; padding-right: 2px;                        
    }    
    </style>    

            <labelvalue="Slide" sclass="ctl" action="onmouseover:anima.slideDown(#{t});onmouseout:anima.slideUp(#{t})"/>            
                <labelvalue="Fade" sclass="ctl" action="onmouseover:anima.appear(#{t});onmouseout:anima.fade(#{t})"/>                
                <labelvalue="Puff" sclass="ctl" action="onmouseover:anima.appear(#{t});onmouseout:anima.puff(#{t})"/>                
                            <labelvalue="Drop Out"sclass="ctl" action="onmouseover:anima.appear(#{t});onmouseout:anima.dropOut(#{t})"/>                            

        <div id="t"visible="false">        
        <div>        
        <groupbox>        
                <captionlabel="Dynamic Content"/>                
            Content to show and hide dynamically.            
            <datebox/>            
        </groupbox>        
            Description<textbox/>            
        </div>        
    </div>    
</window>

The keystroke events are sent to the nearest window that has registered an event listener for the specified events. It is designed to implement the submit, cancel and shortcut functions.

As illustrated below, doA() is invoked if user pressed ENTER when T1 got the focus, and doB() is invoked if user pressed ENTER when T2 got the focus.

<window id="A" onOK="doA()">
    <window id="B" onOK="doB()">    
        <textbox id="T1"/>        
    </window>    
    <textbox id="T2"/>    
</window

Notice that a window doesn't receive the keystroke events that are sent for the inner window, unless you post them manually. In the above example, the event won't be sent to window A, if T1 got the focus, no matter whether the onOK handler is declared for window B or not.

<window ctrlKeys="@c^a#10^#3">
...