The Developer's Reference

Version 3.6.3


Table of Contents

1. Introduction
2. The ZK User Interface Markup Language
Implicit Objects
applicationScope - java.util.Map
arg - java.util.Map
componentScope - java.util.Map
desktop - org.zkoss.zk.ui.Desktop
desktopScope - java.util.Map
each - java.lang.Object
event - org.zkoss.zk.ui.event.Event or derived
execution – org.zkoss.zk.ui.Execution
forEachStatus – org.zkoss.zk.ui.util.ForEachStatus
page - org.zkoss.zk.ui.Page
pageContext – org.zkoss.web.servlet.xel.PageContext
pageScope - java.util.Map
requestScope – java.util.Map
self - org.zkoss.zk.ui.Component
session - org.zkoss.zk.ui.Session
sessionScope - java.util.Map
spaceOwner - org.zkoss.zk.ui.IdSpace
spaceScope - java.util.Map
Processing Instructions
The component Directive
The evaluator Directive
The forward Directive
The function-mapper Directive
The import Directive
The init Directive
The link, meta and script Directives
The page Directive
The root-attributes Directive
The taglib Directive
The variable-resolver Directive
The xel-method Directive
ZK Elements
The XML Namespace
The attribute Element
The custom-attributes Element
The variables Element
The zk Element
The zscript Element
ZK Attributes
The apply Attribute
The forEach Attribute
The forEachBegin Attribute
The forEachEnd Attribute
The forward Attribute
The fulfill Attribute
The if Attribute
The unless Attribute
The use Attribute
3. EL Expressions
Overview
Using EL Expressions
Variables
Implicit Objects
Literals
Operators
Functions
Standard Implicit Objects that ZK supports
applicationScope - java.util.Map
cookie - java.util.Map
header - java.util.Map
headerValues - java.util.Map
pageScope - java.util.Map
param - java.util.Map
paramValues - java.util.Map
requestScope - java.util.Map
sessionScope - java.util.Map
ZK Implicit Objects
4. The XUL Components
Overview
AbstractComponent
FormatInputElement
HeaderElement
HeadersElement
HtmlBasedComponent
InputElement
LabelElement
LabelImageElement
LayoutRegion
NumberInputElement
XulElement
Components
Audio
Auxhead
Auxheader
Bandbox
Bandpopup
Calendar
Borderlayout
Box
Button
Captcha
Caption
Center
Chart
Checkbox
Column
Columnchildren
Columnlayout
Columns
Combobox
Comboitem
Datebox
Detail
Doublebox
Div
East
Fisheyebar
Fisheye
Flash
Footer
Foot
Grid
Group
Groupbox
Groupfoot
Hbox
Html
Iframe
Image
Imagemap
Include
Intbox
Label
Listbox
Listcell
Listfoot
Listfooter
Listgroup
Listgroupfoot
Listhead
Listheader
Listitem
Longbox
Menu
Menubar
Menuitem
Menupopup
Menuseparator
North
Paging
Panel
Panelchildren
Popup
Portallayout
Portalchildren
Progressmeter
Radio
Radiogroup
Row
Rows
Script
Slider
Space
Events
CheckEvent
ColSizeEvent
CreateEvent
DropEvent
ErrorEvent
Event
InputEvent
KeyEvent
MouseEvent
MoveEvent
OpenEvent
PageSizeEvent
PagingEvent
PortalMoveEvent
ScrollEvent
SelectEvent
SelectionEvent
SizeEvent
UploadEvent
ZIndexEvent
Supplemental Classes
AbstractListModel
Constraint
Constrained
Fileupload
ListitemRenderer
ListModel
Messagebox
RendererCtrl
SimpleConstraint
SimpleListModel
5. The XHTML Components
Overview
URL and encodeURL
AbstractTag
Raw
Components
A
Abbr
Acronym
Address
Area
B
Base
Big
Blockquote
Body
Br
Button
Caption
Cite
Code
Collection
Colgroup
Dd
Del
Dfn
Dir
Div
Dl
Dt
Em
Embed
Fieldset
Font
Form
H1
H2
H3
H4
Head
Hr
Html
I
Iframe
Img
Input
Ins
Isindex
Kbd
Label
Legend
Li
Link
Map
Menu
Meta
Nobr
Object
Ol
Optgroup
Option
P
Pre
Q
S
Sam
Script
Select
Small
Span
Strong
Style
Sub
Sup
Table
Tbody
Td
Text
Textarea
Tfoot
Th
Thead
Title
Tr
Tt
Ul
Var
Supplement Classes
Fileupload
Messagebox
Appendix A. WEB-INF/web.xml
ZK Loader
The Initial Parameters
ZK AU Engine
The Initial Parameters
ZK Session Cleaner
ZK Filter
The Initial Parameters
How to Specify in web.xml
DSP Loader
The Initial Parameters
How to Specify in web.xml
Sample of web.xml
Appendix B. WEB-INF/zk.xml
Overview
The richlet and richlet-mapping elements
The listener Element
The log Element
The client-config Element
The desktop-config Element
The xel-config Element
The language-config Element
The session-config Element
The system-config Element
The zscript-config Element
The device-config Element
The error-page Element
The preference Element
The library-property Element
The system-property Element

SIMPLY RICH

ZKTM

June 2009

Potix Corporation

Revision 113

Copyright © Potix Corporation. All rights reserved.

The material in this document is for information only and is subject to change without notice. While reasonable efforts have been made to assure its accuracy, Potix Corporation assumes no liability resulting from errors or omissions in this document, or from the use of the information contained herein.

Potix Corporation may have patents, patent applications, copyright or other intellectual property rights covering the subject matter of this document. The furnishing of this document does not give you any license to these patents, copyrights or other intellectual property.

Potix Corporation reserves the right to make changes in the product design without reservation and without notification to its users.

The Potix logo and ZK are trademarks of Potix Corporation.

All other product names are trademarks, registered trademarks, or trade names of their respective owners.

1. Introduction

Welcome to ZK, the simplest way to make Web applications rich.

The Developer's Reference fully describes properties and methods of components. For concepts, features, refer to the Developer's Guide. For installation, refer to the Quick Start Guide.

2. The ZK User Interface Markup Language

Implicit Objects

For scripts (aka., zsccript) and EL expressions embedded in a ZUML page, there are a set of implicit objects that enable developers to access components more efficiently.

applicationScope - java.util.Map

A map of custom attributes associated with the Web application. It is the same as the getAttributes method in the org.zkoss.zk.ui.WebApp interface.

A Web application is a WAR, and each Web application has an independent set of custom attributes. These attributes are used mainly to communicate among different desktops and sessions.

If the client is based on HTTP, such as a Web browser, this is the same map of attributes stored in javax.servlet.ServletContext. In other words, you could use it communicate with other servlets, such as JSF.

arg - java.util.Map

The arg argument passed to the createComponents method in the org.zkoss.zk.ui.Executions class. It might be null, depending on how createComponents is called.

It is the same as self.desktop.execution.arg.

params.put("name", "John");
Executions.createComponents("/my.zul", null, params);

Then, in my.zul,

<window title="${arg.name}">
...

Notice that arg is available only when creating the components for the included page, say my.zul. On the other hand, all events, including onCreate, are processed later. Thus, if you want to access arg in the onCreate's listener, use the getArg method of the org.zkoss.zk.ui.event.CreateEvent class.

componentScope - java.util.Map

A map of custom attributes associated with the component. It is the same as the getAttributes method in the org.zkoss.zk.ui.Component interface.

desktop - org.zkoss.zk.ui.Desktop

The current desktop. It is the same as self.desktop.

desktop.getPage("main");

desktopScope - java.util.Map

A map of custom attributes associated with the desktop. It is the same as the getAttributes method in the org.zkoss.zk.ui.Desktop interface.

It is mainly used to communicate among pages in the same desktop.

each - java.lang.Object

The current item of the collection being iterated, when ZK evaluates an iterative element. An iterative element is an element with the forEach attribute.

<listbox width="100px">
<listitem label="${each}" forEach="${contacts}"/>
</listbox>

event - org.zkoss.zk.ui.event.Event or derived

The current event. Available for the event listener only.

<textbox onChanging="react(event.value)"/>
<combobox onChanging="autoComplete()"/>
<zscript>
void react(String value) {
...
}
void autoComplete() {
String value = event.getValue();
...
}
</zscript>

execution – org.zkoss.zk.ui.Execution

The current execution.

forEachStatus – org.zkoss.zk.ui.util.ForEachStatus

The status of an iteration. ZK exposes the information relative to the iteration taking place when evaluating the iterative element.

<zk>
<zscript>
grades = new String[] {"Best", "Better", "Good"};
</zscript>
<listbox width="100px">
<listitem label="${forEachStatus.index}: ${each}" forEach="${grades}"/>
</listbox>
</zk>

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.

page - org.zkoss.zk.ui.Page

The current page. It is the same as self.page.

pageContext – org.zkoss.web.servlet.xel.PageContext

The current page context used to retrieve the request, response, variable resolver and so on.

pageScope - java.util.Map

A map of custom attributes associated with the current page. It is the same as the getAttributes method in the org.zkoss.zk.ui.Page interface.

requestScope – java.util.Map

A map of custom attributes associated with the current execution. It is the same as getAttributes method in the org.zkoss.zk.ui.Execution interface.

self - org.zkoss.zk.ui.Component

The component itself. In other words, it is the closest component, depicted as follows.

<listbox>
<zscript>self.getItems();</zscript><!-- self is listbox -->
<listitem value="ab" label="${self.value}"/><!-- self is listitem -->
<zscript>self.getSelectedIndex();</zscript><!-- self is listbox -->
</listbox>

session - org.zkoss.zk.ui.Session

The session. It is similar to javax.servlet.http.HttpSession[1].

sessionScope - java.util.Map

A map of custom attributes associated with the session. It is the same as the getAttributes method in the org.zkoss.zk.ui.Session interface.

If the client is based on HTTP, such as a Web browser, this is the same map of attributes stored in javax.servlet.http.HttpSession. In other words, you could use it communicate with other servlets, such as JSF.

spaceOwner - org.zkoss.zk.ui.IdSpace

The space owner of this component. It is the same as self.spaceOwner.

spaceScope - java.util.Map

A map of custom attributes associated with the ID space containing this component.

Processing Instructions

The XML processing instructions describe how to process the ZUML page. They will be processed first before processing XML elements.

The component Directive

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

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

Defines a new component. There are two formats: by-macro and by-class.

The by-macro Format

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

You could define a new component based on a ZUML page. It is also called the macro component. In other words, once an instance of the new component is created, it creates child components based on the specified ZUML page (the macroURI attribute).

In addition, you could specify the initial properties (such as prop1 in the above example), such that they are always passed to the macro component (thru the arg variable).

The inline attribute specifies whether it is an inline macro (inlinie="true") or a regular macro (default).

An inline macro behaves like inline-expansion. ZK doesn't create a macro component if an inline macro is encountered. Rather, it inline-expands the components defined in the macro URI. In other words, it works as if you type the content of the inline macro directly to the target page.

On the other hand, ZK will create a real component (called a macro component) to represent the regular macro. That is, the macro component is created as the parent of the components that are defined in the macro.

The by-class Format

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

In addition to defining a component by a ZUML page (aka., a macro component), You could define a new component by implementing a class that implements the org.zkoss.zk.ui.Component interface. Then, use the by-class format to declare such kind of components for a page.

To define a new component, you have to specify at least the class attribute, which is used by ZK to instantiate a new instance of the component.

In addition to defining a new component, you can override properties of existent components by specifying the extends element with the component's name to extend from (aka., extendee). In other words, if extends is specified, the definition of the extendee is loaded as the default value and then override only properties that are specified in this directive.

If the name of extendee and extender are the same, it means the extender will override the definition of extendee.

For example, assume you want to use MyWindow instead of the default window, org.zkoss.zul.html.Window, for all windows defined in this ZUML page. Then, you can declare it as follows.

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

It is equivalent to the following codes.

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

In addition, you could specify the properties to initialize. For example, you want to use the style class called blue for all buttons used in this page, then you could:

<?component name="button" extends="button" sclass="blue"?>

Similarly, you could use the following definition to use OK as the default label for all buttons specified in this page.

<?component name="button" extends="button" label="OK"?>

Notice that the properties won't be applied if a component is created manually (by zscript or by Java codes). If you still want them to be applied with the initialial properties, you could invoke the applyProperties method as follows.

<zscript>Button btn = new Button();btn.applyProperties(); //apply the initial properties</zscript>

apply

[Optional][since 3.6.0]

The apply condition, which is a list of composer's class names or EL expression.

Notice that the list of composers specified here is always applied even if the component has its own apply condition. For example, both BaseComposer and FooComposer are applied in the following example,

<?component name="window" extends="window" apply="BaseComposer"?>

<window apply="FooComposer">

</window>

class

[Optional]

Used to specify the class to instantiate an instance of such kind of components. Unlike other directives, the class can be defined with zscript.

extends

[Optional]

Specifies the component name to extend from. The existent definition of the specified name will be loaded to initialize the new component definition. In other words, it extends the existent definition instead of defining a brand-new one.

macroURI

[Required if the by-macro format is used][EL is not allowed]

Used with the by-macro format to specify the URI of the ZUML page, which is used as the template to create components.

moldName

[Optional][Default: default]

Used with the by-class format to specify the mold name. If moldName is specified, moldURI must be specified, too.

moldURI

[Optional][EL is allowed]

moldURI="~./zul/in-my-jar.dsp"moldURI="/WEB-INF/in-my-web.dsp"moldURI="/jsp-or-other-servlet"moldURI="class:com.mycompany.myrender"

Used with the by-class format to specify the mold URI. If moldURI is specified but moldName is not specified, the mold name is assumed as default.

In addition to DSP, JSP and any Servlet technologies, you can implement the org.zkoss.zk.util.ComponentRenderer interface, and then specify it in the moldURI attribute by starting with "class:". With this approach, the performance is the best.

name

[Required]

The component name. If an existent component is defined with the same name, the existent component is completely invisible in this page. If the by-class format is used, the attributes of the existent components are used to initialize the new components and then override with what are defined in this processing instruction.

The evaluator Directive

<?evaluator [name="..."] [class="..."] [import="..."]?>

It specifies how to evaluate XEL expressions.

name

[optional][Default: none][Case insensitive]

The name of the implementation used to evaluate the XEL expressions. There are two ways to specify the implementation. One is the name attribute. The other is the class attribute.

For example, if you want to use MVEL[2], you can specify the name as follows.

<?evaluator name="mvel"?>
<window id="w" title="MVEL Demo">
    ${new org.zkoss.zul.Textbox().setParent(w)}    
</window>

Here are a list of built-in implementations.

Name

Class / Description

default

org.zkoss.xel.el.ELFactory

The default implementation. It is based on ZK Commons EL (zcommons-el.jar), which is a performance enhancement version of Apache Commons EL.

mvel

org.zkoss.zkmax.xel.mvel.MVELFactory

The implementation based on MVEL, http://mvel.codehaus.org.

[available only if zkmax.jar is loaded]

ognl

org.zkoss.zkmax.xel.ognl.OGNLFactory

The implementation based on OGNL, http://www.ognl.org.

[available only if zkmax.jar is loaded]

commons-el

org.zkoss.zkmax.xel.el.ApacheELFactory

The implementation that is based on Apache Commons EL, org.apache.commons.el.ExpressionEvaluatorImpl.

[available only if zkmax.jar is loaded]

japser-el

org.zkoss.zkmax.xel.el21.ApacheELFactory

The implementation that is based on Apache JSP 2.1 EL, org.apache.el.ExpressionFactoryImpl.

[available only if zkmax.jar is loaded]

You can provide additional implementations by use of the class attribute, as described in the following section. The class must implement the org.zkoss.xel.ExpressionFactory interface. Or, you can specify the following content in metainfo/xel/config.xml.

<config>
    <xel-config>    
        <evaluator-name>Super</evaluator-name><!-- case insensitive -->        
        <evaluator-class>my.SuperEvaluator</evaluator-class>        
    </xel-config>    
</config>

class

[Optional][Default: dependind on how xel-config is specified]

The implementation used to evaluate the XEL expressions. In addition to the name attribute, you can specify the class directly. For example, you can use MVEL by specifying class as follows.

<?evaluator class="org.zkoss.zkmax.xel.mvel.MVELFactory"?>
<window id="w" title="MVEL Demo">
    ${new org.zkoss.zul.Textbox().setParent(w)}    
</window>

import

[Optiona][Default: what are defined in taglib]

Specifies a list of classes separated with comma to import for evaluating the expression in this page. For example, with MVEL:

<?evaluator class="org.zkoss.zkmax.xel.mvel.MVELFactory"
import="org.zkoss.zul.Datebox,org.zkoss.zul.Combobox"?>
<window id="w" title="MVEL Demo">
    ${new Datebox().setParent(w)}    

</window>

Notice that not all evaluators support the import of classes. For example, all EL-based the evaluators, including the system default one, don't support it. In other words, the import attribute is meaningless to them. Rather, you have to use the taglib directive to import functions.

The forward Directive

<?forward uri="..." [if="..."] [unless="..."]?>

It specifies the URI to forward the request to, and the condition to decide whether to forward. If the condition is satisfied or not specified, this page won't be rendered, and the request is, instead, forwarded to the URI specified in the uri attribute.

Notes

  • Even if the forward is effective (i.e., ZK forwards the request to the specified URI), the initiators specified in the init directives will be called.

  • The createComponents method of the Execution interface ignores the forward directives. In other words, the forward directives are evaluated only if the ZUML page is loaded directly.

uri

[required][EL expressions allowed]

The URI of the page/servlet to forward to. It may be another ZUML page, a JSP page or any servlet.

If an EL expression is specified and it is evaluated to an empty string, it is considered as no forwarding at all.

if

[Optional][Default: true][EL expressions allowed]

The condition to forward to the specified URI. If both if and unless are omitted, this page won't be evaluated and ZK always forwards the request to the specified URI.

unless

[Optional][Default: false][EL expressions allowed]

The condition not to forward to the specified URI. If both if and unless are omitted, this page won't be evaluated and ZK always forwards the request to the specified URI.

The function-mapper Directive

<?function-mapper class="..." [arg0="..."] [arg1="..."] [arg2="..."] [arg3="..."]?>

Specifies the function mapper that will be used by the EL expressions to resolve unknown function. The specified class must implement the org.zkoss.xel.FunctionMapper interface.

You can specify multiple function mappers with multiple function-mapper directives. The later declared one has higher priority.

Notice that the function-mapper directives are evaluated before the init directives.

class

[Optional]

A class name that must implement the org.zkoss.xel.FunctionMapper interface. Unlike the init directive, the class name cannot be the class that is defined in zscript codes.

arg0, arg1...

[Optional]

You could specify any number of arguments. If not specified, the default constructor is assumed. If specified, it will look for the constructor with the signature in the following order:

  1. Foo(Map args)

  2. Foo(Object[] args)

  3. Foo()

If the first signature is found, the arguments with the name and value are passed to the constructor as an instance of Map. If the second signature is found, the values of arguments are passed to the constructor in an array of objects.

Prior to ZK 3.6.2, only the second signature is checked if one or more argument is specified, and it assumes arg0 as the first argument, arg1 as the second, and so on.

On the hand, you, with ZK 3.6.2 or later, can use any readable name for arguments as follows.

<?function-mapper class="foo.Foo" whatever="anything"?>

The import Directive

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

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

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="/WEB-INF/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 -->

Notes

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

  • The imported directives in the imported page are also imported. For example, if A imports B and B imports C, then A imports both C and B component definitions. If there is a name conflict, A overrides B, while B overrides C.

  • Once the directives are imported, they won't be changed until the importing page is change, no matter the imported page is changed or not.

uri

[Required]

The URI of a ZUML page which the component definitions will be imported from.

directives

[Optional]

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.

The init Directive

<?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. The specified class must implement the org.zkoss.zk.ui.util.Initator interface.

<?init class="MyInit1"?>
<?init class="MyInit2"?>

class

[Optional]

A class name that must implement the org.zkoss.zk.ui.util.Initator interface. Unlike the init directive, the class name cannot be the class that is defined in zscript codes.

An instance of the specified class is constructed and its doInit method is called in the Page Initial phase (i.e., before the page is evaluated). The doFinally method is called after the page has been evaluated. The doCatch method is called if an exception occurs during the evaluation.

Thus, you could also use it for cleanup and error handling.

zscript

[Optional]

A script file that will be evaluated in the Page Initial phase.

arg0, arg1...

[Optional]

You could specify any number of arguments. It will be passed to the doInit method if the first format is used. Since 3.6.2, you can use any name for the arguments, but, in the prior version, the first argument is arg0, the second is arg1 and follows.

The link, meta and script Directives

<?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>

The page Directive

<?page [id="..."] [title="..."] [style="..."] [cacheable="false|true"] [language="xul/html"] [zscriptLanguage="Java"] [contentType="text/html;charset=UTF-8"] [docType="tag PUBLIC &quot;doctype name&quot; &quot;doctype UI&quot;"] [xml="version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;"] [complete="true|false"]?>

It specifies how a page shall be handled. The id and title arguments are the two most important ones.

cacheable

[Optional][Default: false if Ajax devices, true if XML and MIL devices]

It specifies whether the client can cache the output.

Note: Browsers, such as Firefox and IE, don't handle the cache of DHTML correctly, so it is not safe to specify cacheable with true for Ajax devices.

complete

[Optional][Default: false]

It specifies that this page is a complete page. By complete we mean the page has everything that the client expects. For example, if the client is a HTML browser, then a complete page will generate all necessary HTML tags, such as <html>, <head> and <body>.

By default (false), a ZK page is assumed to be complete if and only if it is not included by other page. In other words, if a ZK page is included by other page, ZK will generate <div> (if the client is a HTML browser) to enclose the output of the (incomplete) ZK page.

If you have a ZK page that contains a complete HTML page and is included by other page, you have to specify true for this option. For example, the includer is nothing but including another page:

//includer.jsp
<jsp:include page="includee.zhtml"/>

And, the included page contains a complete HTML page:

<?page complete="true"?>
    <html xmlns="http://www.zkoss.org/2005/zk/native"><head>    
        <title>My Title</tile>        
    </head>    
    <body>    
        My Content        

</body>

</html>

contentType

[Optional][Default: depends on the device]

It specifies the content type. If not specified, it depends on the device. For Ajax devices, it is text/html;charset=UTF-8. For XML and MIL devices, it is text/xml;charset=UTF-8.

Application developers rarely need to change it, unless for XML devices.

docType

[Optional][Default: depends on the device]

It specifies the DOCTYPE (the root tag and DTD) that will be generated to the output directly. This directive is mainly used by XML devices. You rarely need to specify the DOCTYPE directive for Ajax or MIL devices. For example,

<?DOCTYPE value="svg PUBLIC &quot;-//W3C//DTD SVG 1.1//EN&quot; &quot;http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd&quot;"?>

will cause the output to be generated with the following snippet

<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"">

Notice that the <!DOCTYPE...> specified in a ZUML page is processed by ZK Loader. It is not part of the output.

id

[Optional][Default: generated automatically][EL allowed]

Specifies the identifier of the page, such that we can retrieve it back. If an alphabetical identifier is assigned, it will be available to scripts (aka., zscript) and EL expressions embedded in ZUML pages.

<?page id="${param.id}"?>

language

[Optional][Default: depending on the extension][Allowed values: xul/html | xhtml]

Specifies the markup language for this page. The markup language determines the default component set. Currently, it supports xul/html and xhtml.

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.

style

[Optional][Default: width:100%][EL allowed]

Specifies the CSS style used to render the page. If not specified, it depends on the mold. The default mold uses width:100% as the default value.

<?page style="width:100%;height:100%"?>

title

[Optional][Default: none][EL allowed]

Specifies the page title that will be shown as the title of the browser.

It can be changed dynamically by calling the setTitle method in the org.zkoss.zk.ui.Page interface.

<?page title="${param.title}"?>

xml

[Optional][Default: none]

Specifies the xml processing instruction (i.e., <?xml?>) that will be generated to the output. Currently only XML devices support this option.

For example,

<?page xml="version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;"?>

will generate the following as the first line of the output

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

zscriptLanguage

[Optional][Default: Java][Allowed values: Java | JavaScript | Ruby | Groovy]

Specifies the default scripting language, which is assumed if an zscript element doesn't specify any scripting language explicitly.

<?page zscriptLanguage="JavaScript"?>

<zscript>
    var m = round(box.value); //JavaScript is assumed.    
</zscript>

If this option is omitted, Java is assumed. Currently ZK supports four different languages: Java, JavaScript, Ruby and Groovy. This option is case insensitive.

Note: Deployers can extend the number of supported scripting languages. Refer to the How to Support More Scripting Language section in the Developer's Guide.

The root-attributes Directive

<?root-attributes any-name1="any-value2" any-name2="any-value2"?>

It specifies the additional attributes for the root element of the generated output, which depends on the device types.

Currently, only Ajax devices support this feature and the root element is the html tag. In other words, the attributes specified in the root-attribute directives will become the attributes of the html element of the generated output. For example,

<?root-attributes xmlns:v="urn:schemas-microsoft-com:vml"?>

will cause the HTML output to be generated with the following snippet

<html xmlns="http://www.w3.org/1999/xhtml"xmlns:v="urn:schemas-microsoft-com:vml">

Note: xmlns="http://www.w3.org/1999/xhtml" is always generated.

Note: If the value is specified with an EL expression and it is evaluated to null, the corresponding attribute won't be generated.

any-name="any-value"

Any numbers of names and values are allowed. The value could contain EL expressions.

The taglib Directive

<?tablib uri="myURI" prefix="my"?>

This directive is used to load a taglib file, which defines a set of EL functions. The format of a taglib file is the same as that of JSP taglib files.

In the following example, we loads functions defined in the built-in TLD files identified as http://www.zkoss.org/dsp/web/core and then use one of these function called l.

<?taglib uri="http://www.zkoss.org/dsp/web/core" prefix="c"?>
<window title="${c:l('my.title')}">
...
</window>

Tip: ZK searches all TLD files defined in the /metainfo/tld/config.xml file from the classpath. If you want ZK to load your custom TLD files, add them to class path and then specify the following content in the /metainfo/tld/config.xml file. <taglib><taglib-uri>http://your-domain.com/your-path</taglib-uri><taglib-location>/the/path/of/your/tld/file</taglib-location></taglib>

If you to load a TLD file from your Web application, you can specify the path as follows.

<?taglib uri="/WEB-INF/tld/my.tld" prefix="my"?>

uri

[Required][EL is not allowed]

A URL of the taglib file. Unlike other URL and URI, it doesn't interpret ~ or * specially. And, the page and the taglib files it references must be in the same Web application.

prefix

[Required]

A prefix used to identify functions defined in this taglib file. The prefix could be any non-empty string.

The variable-resolver Directive

<?variable-resolver class="..." [arg0="..."] [arg1="..."] [arg2="..."] [arg3="..."]?>

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.

Notice that the variable-resolver directives are evaluated before the init directives, so the zscript codes referenced by the init directives are affected by the variable resolver.

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

class

[Optional]

A class name that must implement the org.zkoss.xel.VariableResolver interface. Unlike the init directive, the class name cannot be the class that is defined in zscript codes.

arg0, arg1...

[Optional]

You could specify any number of arguments. If not specified, the default constructor is assumed. If specified, it will look for the constructor with the signature in the following order:

  1. Foo(Map args)

  2. Foo(Object[] args)

  3. Foo()

If the first signature is found, the arguments with the name and value are passed to the constructor as an instance of Map. If the second signature is found, the values of arguments are passed to the constructor in an array of objects.

Prior to ZK 3.6.2, only the second signature is checked if one or more argument is specified, and it assumes arg0 as the first argument, arg1 as the second, and so on.

On the hand, you, with ZK 3.6.2 or later, can use any readable name for arguments as follows.

<?variable-resolver class="foo.Foo" whatever="anything"?>

The xel-method Directive

<?xel-method prefix="..." name="..." class="..."signature="..."?>

Specifies a method that shall be imported by the EL evaluator. For example,

<?xel-method prefix="c" name="forName"class="java.lang.Class"signature="java.lang.Class forName(java.lang.String)"?><textbox value="${c:forName('java.util.List')}"/>        

prefix

[Required]

Specifies the prefix used to identify this method.

name

[Required]

Specifies the name used to identify this method. The full name is "prefix:name".

class

[Required]

Specifies the class that the method is defined in.

signature

[Required]

The signature of the method. Note: the method must be public static.

ZK Elements

ZK elements are special XML elements that are used to control ZUML pages other than creating components.

The XML Namespace

If there is name conflicts, you could specify the XML name space:

http://www.zkoss.org/2005/zk

<zk:attribute xmlns:zk="http://www.zkoss.org/2005/zk">
...

The attribute Element

<attribute name="myName" [trim="true|false"]>myValue</attribute>

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.

<button label="Hi">
<attribute name="onClick">alert("Hi")</attribute>
</button>

It is equivalent to

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

Another example:

<button>
<attribute name="label" if="${param.happy}">Hello World!</attribute>
</button>

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>

name

[Required]

Specifies the attribute name.

trim

[Optional][Default: false]

Specifies whether to omit the leading and trailing whitespaces of the attribute value.

if

[Optional][Default: true]

Specifies the condition to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to false.

unless

[Optional][Default: false]

Specifies the condition not to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to true.

The custom-attributes Element

<custom-attributes [scope="component|space|page|desktop|session|application] attr1="value1" [attr2="value2"...]/>

It defines a set of custom attributes of the specified scope. You could specify as many as attributes you want. These attributes can be retrieved by the getAttribute method of the Component interface with the specified scope.

<custom-attributes cd="${param.cd}" a.b="ab"/>

scope

[optional][Default: component]

Specifies the scope to which the custom attributes are associated. If not specified, the component enclosing this element is the default scope to use.

composite

[Optional][Default: none]

Specifies the format of the value. It could be none, list or map.

By default, the value is assigned to the attribute directly after evaluating EL expressions, if any. For example, "apple, ${more}" is evaluated to "apple, orange", if more is "orange", and assigned to the attribute.

If you want to specify a list of values, you can specify the composite attribute with list as follows.

<custom-attributes simple="apple, ${more}" composite="list"/>

Then, it is converted to a list with two elements. The first element is "apple" and the second "orange".

If you want to specify a map of values, you can specify the composite attribute with map as follows.

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

Then, it is converted to a map with two entries. The first entry is ("juice", "apple") and the second ("flavor", "orange").

if

[Optional][Default: true]

Specifies the condition to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to false.

unless

[Optional][Default: false]

Specifies the condition not to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to true.

The variables Element

<variables [local="false|true] var1="value1" [var2="value2"...]/>

It defines a set of variables for the ID space it belongs. 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.

You could specify as many as variables you want. These variables are stored to the namespace of the ID space it belongs. Thus, they can be accessible by the interpreters and EL expressions.

<variables cd="${param.cd}" less="more"/>

local

[optional][Default: false]

Specifies whether to store the variable always at the current ID space. By default, it is false. It means ZK will check the existence of any variable with the same name by looking up the current ID space, the parent ID space, and parent's parent, and so on. If found, the variable's value is replaced with the value specified here. If not, a local variable is created. If true is specified, it doesn't look up any parent ID space.

composite

[Optional][Default: none]

Specifies the format of the value. It could be none, list or map.

By default, the value is assigned to the variable directly after evaluating EL expressions, if any. For example, "apple, ${more}" is evaluated to "apple, orange", if more is "orange", and assigned to the variable.

If you want to specify a list of values, you can specify the composite attribute with list as follows.

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

Then, it is converted to a list with two elements. The first element is "apple" and the second "orange".

If you want to specify a map of values, you can specify the composite attribute with map as follows.

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

Then, it is converted to a map with two entries. The first entry is ("juice", "apple") and the second ("flavor", "orange").

if

[Optional][Default: true]

Specifies the condition to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to false.

unless

[Optional][Default: false]

Specifies the condition not to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to true.

The zk Element

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

The main use is to represent multiple root elements in XML format.

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

The other use is to iterate over versatile components.

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

if

[Optional][Default: true]

Specifies the condition to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to false.

unless

[Optional][Default: false]

Specifies the condition not to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to true.

forEach

[Optional][Default: ignored]

It specifies a collection of objects, such that the zk 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.

forEachBegin

[Optional][Default: 0]

It is used with the forEach attribute to specify the starting offset when iterating a collection of objects. If not specified, it iterates from the first element, i.e., 0 is assumed.

forEachBegin

[Optional][Default: 0]

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.

forEachEnd

[Optional][Default: the last element]

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.

switch

[Optional][Default: none]

Provide the context for mutually exclusive evaluation. The value specified in this attribute is called the switch condition.

<zk swtich="${condition}"/>

The only allowed children are the zk elements.

case

[Optional][Default: none]

Provides an alternative within the switch evaluation.

<zk case="apple"/>

If the value is a string starting and ending with slash, such as /a[p]*/, it is considered as a regular expression, which is used to match the switch condition.

<zk case="/a[a-z]*/"/>

You can specify multiple cases by separating them with comma.

<zk case="apple, ${special}"/>

choose

[Optional][Default: none]

Provide the context for mutually exclusive evaluation.

<zk choose="">

The only allowed children are the zk elements.

when

[Optional][Default: none]

Provides an alternative within the choose evaluation.

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

It is evaluated if the condition matches.

The zscript Element

<zscript [language="Java|JavaScript|Ruby|Groovy"]>Scripting codes</zscript><zscript src="uri" [language="Java|JavaScript|Ruby|Groovy"]/>

It defines a piece of scripting codes that will be interpreted when the page is evaluated. The language of the scripting codes is, by default, Java. You can select a different language by use the language attribute[3].

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.

<zscript>
alert("Hi");
</zscript>
<zscript src="/codes/my.bs"/>

Like other ZK elements, it is not a component but a special XML element.

src

[Optional][Default: none]

Specifies the URI of the file containing the scripting codes. If specified, the scripting codes will be loaded as if they are embedded directly.

Note: the file shall contain the source codes in the selected scripting language. The encoding must be UTF-8. Don't specify a class file (aka. byte codes).

Like other URL and URI, it has several characteristics as follows.

  1. It is relative to the servlet context path (aka., the getContextPath method from the javax.servlet.http.HttpServletRequest interface). In other words, ZK will prefix it with the servlet context automatically.

  2. It resolves "~" to other Web application (aka., different ServletContext). Notice that Web server administrator might disable Web applications from peeking other's content[4].

  3. It accepts "*" for loading browser and Locale dependent style sheet.

The algorithm to resolve "*" is as follows.

  • If there is one "*" is specified in an URL or URI such as /my*.css, then "*" will be replaced with a proper Locale depending on the preferences of user's browser.For example, user's preferences is de_DE, then ZK searches /my_de_DE.css, /my_de.css, and /my.css one-by-one from your Web site, until any of them is found. If none of them is found, /my.css is still used.

  • If two or more "*" are specified in an URL or URI such as "/my*/lang*.css", then the first "*" will be replaced with "ie" for Internet Explorer and "moz" for other browsers[5]. If the last "*" will be replaced with a proper Locale as described above.

  • All other "*" are ignored.

language

[Optional][Default: the page's default scripting language][Allowed Values: Java | JavaScript | Ruby | Groovy]

It specifies the scripting language which the scripting codes are written in.

deferred

[Optional][Default: false]

Specifies whether to defer the evaluation of this element until the first non-deferred zscript codes of the same language has to be evaluated. It is used to defer the loading of the interpreter and then speed up the loading of a ZUML page. For example, if all zscript elements are deferred, they are evaluated only when the first event listened by a handler implemented in zscript is received.

Refer to the How to Defer the Evaluation section in the Developer's Guide.

if

[Optional][Default: true]

Specifies the condition to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to false.

unless

[Optional][Default: false]

Specifies the condition not to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to true.

ZK Attributes

ZK attributes are used to control the associated element, other than initializing the data member.

The apply Attribute

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 it is the root 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.

The forEach Attribute

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

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.

For each iteration, two variables, each and forEachStatus, are assigned automatically to let developers control how to evaluate the associated element.

<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.index]}"/>
</listbox>
</hbox>

The forEachBegin Attribute

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 always starts from 0, no matter what forEachBegin is.

The forEachEnd Attribute

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.

The forward Attribute

forward="orginalEvent=targetId1/targetId2.targetEvent"forward="orginalEvent=targetId1/targetId2.targetEvent(eventData)"forward="originalEvent=${el-target}.targetEvent(${el-eventdata})"forward="targetEvent"

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

The forward event is an instance of the org.zkoss.zk.ui.event.ForwardEvent class. you can invoke the getOrigin method to retrieve the original event.

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.

The data specified in the parenthesis is the application-specific data, which can be retrieved by calling the getData method.

<button forward="onCancel(abort)"/><!-- "abort" is passed -->

<button forward="onPrint(${inf})"/><!-- the object returned by ${inf} is passed -->

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

The target component and the event data can be specified in EL expressions, while the event names cannot.

The fulfill Attribute

fulfill="event-name"fulfill="target-id.event-name"fulfill="id1/id2/id3.event-name"fulfill="${el-expr}.event-name"

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, at the time 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.

The onFulfill Event

After ZK applies the fulfill condition, i.e., creates all descendant components, it fires the onFulfill event with an instance of org.zkoss.zk.ui.event.FulfillEvent to notify the component for further processing if any.

For example, if you use the wireVariables method of the org.zkoss.zk.ui.Components class, you might have to call wireVariables again to wire the new components in the onFulfill event.

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

...

</div>

The if Attribute

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.

The unless Attribute

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.

The use Attribute

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.html.Window.

<window use="MyWindow"/>

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



[1] ZK session actually encapsulates the HTTP session to make ZK applications independent of HTTP.

[2] MVEL is a powerful expression language. Refer to http://mvel.codehaus.org/ for more information.

[3] Furthermore, you can use the page directive to change the default scripting language other than Java.

[4] Refer to the getContext meth from the javax.servlet.ServletContext interface.

[5] In the future editions, we will use different codes for browsers other than IE and FF.

3. EL Expressions

This chapter describes the details about applying EL expressions to ZUML pages.

Overview

EL expressions use the syntax ${expr}. For example,

<element attr1=”${bean.property}”.../>
${map[entry]}
<another-element>${3+counter} is ${empty map}</another-element>

When an EL expression is used as an attribute value, it could return any kind of objects as long as the component accepts it. For example, the following expression will be evaluated to a Boolean object.

<window if="${some > 10}">

Using EL Expressions

EL expressions can be used

  • In static text

  • In any attribute's value including XML elements and XML processing instructions.

Variables

Implicit Objects

Literals

Operators

Functions

Using Functions

Defining Functions

Standard Implicit Objects that ZK supports

Like using EL expressions in JSP pages, you could use most of standard implicit objects in ZUML pages.

applicationScope - java.util.Map

A map of application-scoped attributes (String, Object).

cookie - java.util.Map

A map of cookies of the request. (String, Cookie).

header - java.util.Map

A map of headers of the request. (String, String).

headerValues - java.util.Map

A map of headers of the request. (String, String[]).

pageScope - java.util.Map

A map of page-scoped attributes (String, Object).

Notice: the page concept is a bit different from JSP because a ZK page exists across requests.

param - java.util.Map

A map of parameters of the request (String, String).

paramValues - java.util.Map

A map of parameters of the request. (String, String[]).

requestScope - java.util.Map

A map of request-scoped attributes (String, Object).

sessionScope - java.util.Map

A map of session-scoped attributes (String, Object).

ZK Implicit Objects

All variables defined in ZK scripts (aka., zscript) are available for the EL expressions. Thus, all implicit objects described in the previous chapter are also the implicit objects for the EL expressions. You are free to use self, event, componentScope and others. Refer to the Implict Objects section in the ZK User Interface Markup Language chapter.

4. The XUL Components

Overview

  • All XUL components are packed in the org.zkoss.zul.html package.

  • The XML name space is http://www.zkoss.org/2005/zul

  • The extensions include xul and zul.

  • The component names are case-sensitive. They are all in lower-cases.

AbstractComponent

A skeletal implementation of Component. Though it is OK to implement Component from scratch, this class simplifies some of the chores.

Class Name

org.zkoss.zk.ui.AbstractComponent

Properties

Property

Description

Data Type

Default Value

id

Sets the ID.

java.lang.String

UUID (universal unique ID)

mold

Sets the mold for this component.

java.lang.String

default

visible

Sets whether this component is visible.

boolean

true

Methods

Name

Description

Return Data Type

AddAnnotation

(java.lang.String annotName, java.util.Map annotAttrs)

Associates an annotation to this component.

void

addAnnotation(java.lang.String propName, java.lang.String annotName, java.util.Map annotAttrs)

Adds an annotation to the specified proeprty of this component.

void

addEventHandler(java.lang.String name, EventHandler evthd)

Adds an event handler.

void

addEventListener(java.lang.String evtnm, EventListener listener)

Adds an event listener to specified event for this component.

boolean

addSharedAnnotationMap(AnnotationMap annots)

Add a map of annotations which is shared by other components.

void

addSharedEventHandlerMap(EventHandlerMap evthds)

Adds a map of event handlers which is shared by other components.

void

appendChild(Component child)

Appends a child to the end of all children.

boolean

applyProperties()

Initializes the properties (aka. members) and custom-attributes based on what are defined in the component definition.

void

clone()

Clones the component.

java.lang.Object

containsVariable(java.lang.String name, boolean local)

Returns whether the specified variable is defined.

boolean

detach()

Detaches this component such that it won't belong to any page.

void

getAnnotatedProperties()

Returns a read-only list of the name (String) of properties that are associated at least one annotation (never null).

java.util.List

getAnnotatedPropertiesBy(java.lang.String annotName)

Returns a read-only list of the names (String) of the properties that are associated with the specified annotation (never null).

java.util.List

getAnnotation(java.lang.String annotName)

Returns the annotation associated with the component, or null if not available.

org.zkoss.zk.ui.metainfo.Annotation

getAnnotation(java.lang.String propName, java.lang.String annotName)

Returns the annotation associated with the definition of the specified property, or null if not available.

org.zkoss.zk.ui.metainfo.Annotation

getAnnotations()

Returns a read-only collection of all annotations associated with this component (never null).

java.util.Collection

getAnnotations(java.lang.String propName)

Returns a read-only collection of all annotations associated with the specified property (never null).

java.util.Collection

getAttribute(java.lang.String name)

Returns the custom attribute associated with this component, i.e., Component.COMPONENT_SCOPE.

java.lang.Object

getAttribute(java.lang.String name, int scope)

Returns the value of the specified custom attribute in the specified scope, or null if not defined.

java.lang.Object

getAttributes()

Returns all custom attributes associated with this component, i.e., Component.COMPONENT_SCOPE.

java.util.Map

getAttributes(int scope)

Returns all custom attributes of the specified scope.

java.util.Map

getChildren()

Returns a live list of children.

java.util.List

getDefinition()

Returns the component definition of this component (never null).

org.zkoss.zk.ui.metainfo. ComponentDefinition

getDesktop()

Returns the desktop of this component, or null if this component doesn't belong to any desktop.

org.zkoss.zk.ui .Desktop

getEventHandler(java.lang.String evtnm)

Returns the event handler of the specified name, or null if not found.

org.zkoss.zk.ui.metainfo.ZScript

getExtraCtrl()

Returns the extra controls that tell ZK how to handle this component specially.

java.lang.Object

getFellow(java.lang.String compId)

Returns a component of the specified ID in the same ID space.

org.zkoss.zk.ui .Component

getFellowIfAny(java.lang.String compId)

Returns a component of the specified ID in the same ID space, or null if not found.

org.zkoss.zk.ui .Component

getListenerIterator(java.lang.String evtnm)

Returns an iterator for iterating listener for the specified event.

java.util.Iterator

getNamespace()

Returns the namespace to store variables and functions belonging to the ID space of this component.

org.zkoss.zk.scripting.Namespace

getPage()

Returns the page that this component belongs to, or null if it doesn't belong to any page.

Page

getParent()

Returns the parent component, or null if this is the root component.

org.zkoss.zk.ui.Component

getPropagatee(java.lang.String evtnm)

Default: null (no propagation at all).

org.zkoss.zk.ui.Component

getRoot()

Returns the root of the specified component.

org.zkoss.zk.ui.Component

getSpaceOwner()

Returns the owner of the ID space that this component belongs to.

org.zkoss.zk.ui.IdSpace

getUuid()

Returns UUID (universal unique ID) which is unquie in the whole session.

java.lang.String

getVariable(java.lang.String name, boolean local)

Returns the value of a variable defined in the namespace, or null if not defined or the value is null.

java.lang.Object

insertBefore(Component newChild, Component refChild)

Inserts a child before the reference child.

boolean

invalidate()

Invalidates this component by setting the dirty flag such that it will be redraw the whole content later.

void

isChildable()

Default: return true (allows to have children).

boolean

isListenerAvailable(java.lang.String evtnm, boolean asap)

Returns whether the event listener is available.

boolean

onChildAdded(Component child)

Default: does nothing.

void

onChildRemoved(Component child)

Default: does nothing.

void

onDrawNewChild(Component child, java.lang.StringBuffer out)

Called when a new-created child is drawn.

void

onWrongValue(WrongValueException ex)

Notifies that an WrongValueException instance is thrown, and WrongValueException.getComponent() is this component.

org.zkoss.zk.ui.WrongValueException

redraw(java.io.Writer out)

Includes the page returned by getMoldURI() and set the self attribute to be this component.

void

removeAttribute(java.lang.String name)

Removes the custom attribute associated with this component, i.e., Component.COMPONENT_SCOPE.

java.lang.Object

removeAttribute(java.lang.String name, int scope)

Removes the specified custom attribute in the specified scope.

java.lang.Object

removeChild(Component child)

Removes a child.

boolean

removeEventListener(java.lang.String evtnm, EventListener listener)

Removes an event listener.

boolean

response(java.lang.String key, AuResponse response)

Causes a response (aka., a command) to be sent to the client.

void

sessionDidActivate(Page page)

Notification that the session, which owns this component, has just been activated (aka., deserialized).

void

sessionWillPassivate(Page page)

Notification that the session, which owns this component, is about to be passivated (aka., serialized).

void

setAttribute(java.lang.String name, java.lang.Object value)

Sets the custom attribute associated with this component, i.e., Component.COMPONENT_SCOPE.

java.lang.Object

setAttribute(java.lang.String name, java.lang.Object value, int scope)

Sets the value of the specified custom attribute in the specified scope.

java.lang.Object

setComponentDefinition(ComponentDefinition compdef)

Sets the component definition.

void

setPage(Page page)

Sets the page that this component belongs to.

void

setParent(Component parent)

Sets the parent component.

void

setVariable(java.lang.String name, java.lang.Object val, boolean local)

Sets a variable to the namespace.

void

smartUpdate(java.lang.String attr, boolean value)

A special smart-update that update a value in boolean.

void

smartUpdate(java.lang.String attr, int value)

A special smart-update that update a value in int.

void

smartUpdate(java.lang.String attr, java.lang.String value)

Smart-updates a property with the specified value.

void

toString()

java.lang.String

unsetVariable(java.lang.String name, boolean local)

Unsets a variable defined in the namespace.

void

FormatInputElement

A skeletal implementation for an input box with format. .

Class Name

org.zkoss.zul.impl.FormatInputElement

Properties

Property

Description

Data Type

Default Values

Format

Sets the format

String

<empty string>

Methods

Name

Description

Return Data Type

getOuterAttrs()

String

HeaderElement

A skeletal implementation for a header.

Class Name

org.zkoss.zul.impl.HeaderElement

Properties

Property

Description

Data Type

Default Value

align

Sets the horizontal alignment of this column.

java.lang.String

null

valign

Sets the vertical alignment of this grid.

java.lang.String

null

Methods

Name

Description

Return Data Type

getColAttrs()

Returns the attributes used to generate HTML TD tag for each cell of the rows contained in the parent control, e.g., Listcell.

java.lang.String

getOuterAttrs()

java.lang.String

isChildable()

Children are not allowed.

boolean

setWidth(java.lang.String width)

void

HeadersElement

A skeletal implementation for headers, the parent of a group of HeaderElement.

Class Name

org.zkoss.zul.impl.HeadersElement

Properties

Property

Description

Data Type

Default Value

sizeable

Sets the horizontal alignment of this column. Sets whether the width of the child column is sizable.

boolean

false

Methods

Name

Description

Return Data Type

getOuterAttrs()

java.lang.String

HtmlBasedComponent

A skeletal implementation for HTML based components. It simplifies to implement methods common to HTML based components.

Class Name

org.zkoss.zk.ui.HtmlBasedComponent

Supported Child Components

*ALL

Supported Events

Event Name

Event Type

onDrop

org.zkoss.zk.ui.event.DropEvent

Description: Represents an event cause by user's dragging and dropping a component.

Properties

Property

Description

Data Type

Default Value

droppable

Sets "true" or "false" to denote whether a component is droppable, or a list of identifiers of draggable types of objects that could be dropped to this component.

Value:true | false|the identifier of a draggable type of objects

java.lang.String

<null>

droppable

Sets "true" or "false" to denote whether a component is droppable, or a list of identifiers of draggable types of objects that could be droped to this component.

Value:true | false|

the identifier of a draggable type of objects

java.lang.String

<null>

height

Sets the height.

java.lang.String

<null>

left

Sets the left position.

java.lang.String

<null>

sclass

Sets the CSS class.

java.lang.String

<null>

style

Sets the CSS style.

java.lang.String

<null>

tooltiptext

Sets the text as the tooltip.

java.lang.String

<null>

top

Sets the top position.

java.lang.String

<null>

width

Sets the width.

java.lang.String

<null>

zIndex

Sets the Z index.

int

0

Methods

Name

Description

Return Data Type

addEventListener(java.lang.String, EventListener)

Adds an event listener to specified event for this component.

boolean

focus()

Sets focus to this element.

void

getInnerAttrs()

Returns the interior attributes for generating the inner HTML tag; never return null.

Used only by component developers.

Default: empty string. Refer to getOuterAttrs for more details.

java.lang.String

getOuterAttrs()

Returns the exterior attributes for generating the enclosing HTML tag; never return null.

Used only by component developers.

Default: Generates the tooltip text, style, sclass, draggable and droppable attribute if necessary. In other words, the corresponding attribute is generated if getTooltiptext, getRealStyle, getSclass, getDraggable, getDroppable are defined.

You have to call both getOuterAttrs and getInnerAttrs to generate complete attributes.

For simple components that all attributes are put on the outset HTML element, all you need is as follows.

<xx id="${self.uuid}"${self.outerAttrs}${self.innerAttrs}>

If you want to put attributes in a nested HTML element, you shall use the following pattern. Notice: if getInnerAttrs in a different tag, the tag must be named with "${self.uuid}!real".

<xx id="${self.uuid}"$ {self.outerAttrs}>

<yy id="${self.uuid}!real"${self.innerAttrs}>...

Note: This class handles non-deferrable event listeners automatically. However, you have to invoke appendAsapAttr for each event the component handles in getOuterAttrs as follows.

appendAsapAttr(sb, Events.ON_OPEN);

appendAsapAttr(sb, Events.ON_CHANGE);

Theoretically, you could put any attributes in either getInnerAttrs or getOuterAttrs. However, zkau.js assumes all attributes are put at the outer one. If you want something different, you have to provide your own setAttr (refer to how checkbox is implemented).

java.lang.String

removeEventListener(java.lang.String, EventListener)

Removes an event listener.

boolean

Inherited From

InputElement

InputElement is a super class for components which provie user key input, such as Textbox, Intbox, etc.

Some features are implemented in this class, such as constraint, disabled, maxlength, name, readonly, etc.

You sholuld not deirectly use this class, please use the inherited class.

Class Name

org.zkoss.zul.InputElement

Supported Events

Properties

Property

Description

Data Type

Default Value

cols

Sets the columns.

Note: non-positive means the same as browser's default

int

0

Property

Description

Data Type

Default Value

constraint

Sets the constraint, must be a default constraint expression. The value,except regular expression , could be a combination String by comma

Values : no positive | no negative | no zero | no empty | nofuture | no past | no today | a regular expression.

String

<empty string>

disabled

Sets whether it is disabled.

Values : true|false

boolean

false

maxlength

Sets the max length.

Note : non-postive means unlimited.

int

0

name

Sets the name of this component.

Don't use this method if your application is purely based on ZK's event-driven model.

The name is used only to work with "legacy" Web application that handles user's request by servlets. It works only with HTTP/HTML-based browsers. It doesn't work with other kind of clients.

String

null

readonly

Sets whether it is read only

Values : true|false

int

false

tabindex

Sets the tab order of this component.

Note : -1 means the same as browser's default

int

-1

text

Sets the value in the String format.

Note : default value depends on implementation of sub-class.

String

null

Methods

*NONE

LabelElement

A HTML element with a label.

Class Name

org.zkoss.zul.impl.LabelElement

Properties

Property

Description

Data Type

Values

label

Sets the label

String

Any text

LabelImageElement

A HTML element with a label and an image.

Class Name

org.zkoss.zul.impl.LabelImageElement

Properties

Property

Description

Data Type

Default Value

image

Sets the label

String

null

imageContent

Sets the content directly

org.zkoss.image.Image

null

src

Sets the image URI

String

null

Methods

Name

Description

Return Data Type

isImageAssigned()

Returns whether the image is available.

It return true if setImage(java.lang.String) or setImageContent(org.zkoss.image.Image) is called with non-null.

boolean

getImgTag()

Returns the HTML IMG tag for the image part.

Used only for component template, not for application developers.

Note: the component template shall use this method to generate the HTML tag, instead of using getImage().

String

LayoutRegion

This class represents a region in a layout manager.

Class Name

org.zkoss.zkex.zul.LayoutRegion

Supported Child Components

*NONE

Supported Events

Name

Inherited From

onOpen

org.zkoss.zk.ui.event.OpenEvent

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

Properties

Property

Description

Data Type

Default Value

flex

Sets whether to grow and shrink vertical/horizontal to fit their given space, so called flexibility.

java.lang.String

false

size

Sets the size of this region. This method is shortcut for setHeight(String) and setWidth(String). If this region is North or South, this method will invoke setHeight(String). If this region is West or East, this method will invoke setWidth(String). Otherwise it will throw a UnsupportedOperationException.

java.lang.String

null

splittable

Sets whether enable the split functionality.

boolean

false

collapsible

Sets whether set the initial display to collapse.

boolean

false

margins

Sets margins for the element "0,1,2,3" that direction is "top,left,right,bottom".

java.lang.String

0,0,0,0

open

Opens or collapses the splitter. Meaningful only if isCollapsible is not false.

boolean

true

autoscroll

Sets whether enable overflow scrolling.

boolean

false

border

Sets the border (either none or normal).

java.lang.String

normal

maxsize

Sets the maximum size of the resizing element.

int

2000

minsize

Sets the minimum size of the resizing element.

int

0

Methods

Name

Description

Return Data Type

getOuterAttrs()

insertBefore(org.zkoss.zk.ui.Component child, org.zkoss.zk.ui.Component insertBefore)

onChildRemoved(org.zkoss.zk.ui.Component child)

NumberInputElement

A skeletal implementation for number-type input box.

Class Name

org.zkoss.zul.impl.NumberInputElement

Properties

Property

Description

Data Type

Default Values

RoundingMode

the rounding mode.

int

BigDecimal.ROUND_HALF_EVEN.

XulElement

The fundamental class for XUL elements.

Class Name

org.zkoss.zul.impl.XulElement

Properties

Property

Description

Data Type

Default Value

action

Sets the label

String

null

context

Sets the ID of Popup that should appear when the user right-clicks on the element (aka., context menu).

String

null

popup

Sets the ID of Popup that should appear when the user clicks on the element.

String

null

tooltip

Sets the ID of Popup that should be used as a tooltip window when the mouse hovers over the element for a moment.

String

null

Methods

Name

Description

Return Data Type

getInnerAttrs()

Generates the Client-Side-Action attributes to the interior tag.

Reason: onfocus is the main use.

String

getOuterAttrs()

String

Components

Audio

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.

<audio id="audio" height="20"/>

Class Name

org.zkoss.zul.Audio

Supported Child Components

*NONE

Supported Events

*NONE

Properties

Property

Description

Data Type

Default Value

align

Sets the alignment: one of top,

Value: texttop, middle, absmiddle, bottom, absbottom, baseline, left, right and center.

java.lang.String

<null>

aut ostart

Sets whether to auto start playing the audio.

boolean

false

border

Sets the width of the border.

java.lang.Str ing

<null>

con tent

Sets the content directly.

org.zkoss.sound.Audio

<null>

src

Sets the src.

java.lang.Str ing

<null>

Methods

Name

Description

Return Data Type

isChildable()

Determines whether it accepts child components

Value: false

Note: No child is allowed.

boolean

pause()

Pauses the audio at the client.

void

play()

Plays the audio at the client.

void

stop()

Stops the audio at the client.

void

Auxhead

Used to define a collection of auxiliary headers (Auxheader).

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

Class Name

org.zkoss.zul.Auxhead

Supported Child Components

Auxheader

Supported Events

*NONE

Properties

*NONE

Methods

Name

Description

Return Data Type

insertBefore(org.zkoss.zk.ui.Component child, org.zkoss.zk.ui.Component insertBefore)

boolean

Auxheader

An auxiliary header.

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

Class Name

org.zkoss.zul.Auxheader

Supported Child Components

*NONE

Supported Events

*NONE

Properties

Property

Description

Data Type

colspan

Sets the number of columns to span this header.

int

rowspan

Sets the number of rows to span this header.

int

Methods

Name

Description

Return Data Type

getOuterAttrs()

java.lang.String

setParent(org.zkoss.zk.ui.Component parent)

Bandbox

A band box is a special text box that embeds a customizable popup window (aka., a dropdown window). Like comboboxes, a bandbox consists of an input box and a popup window. The popup window is opened automatically, when users presses Alt+DOWN or clicks the

button.

Unlike comboboxes, the popup window of a bandbox could be anything. It is designed to give developers the maximal flexibility. A typical use is to represent the popup window as a search dialog.

        <bandboxid="bd">        
        <bandpopup>        
                <vbox>                
            <hbox>Search<textbox/></hbox>            
            <listboxwidth="200px"            
            onSelect="bd.value=self.selectedItem.label;bd.closeDropdown();">            
            <listhead>            
                    <listheaderlabel="Name"/>                    
                    <listheaderlabel="Description"/>                    
            </listhead>            
            <listitem>            
                    <listcelllabel="John"/>                    
                    <listcelllabel="CEO"/>                    
            </listitem>            
            <listitem>            
                    <listcelllabel="Joe"/>                    
                    <listcelllabel="Engineer"/>                    
            </listitem>            
            <listitem>            
                    <listcelllabel="Mary"/>                    
                    <listcelllabel="Supervisor"/>                    
            </listitem>            
        </listbox>        
        </vbox>        
        </bandpopup>        
    </bandbox>    

Class Name

org.zkoss.zul.Bandbox

Supported Child Components

Bandpopup

Supported Events

Name

Event Type

onOpen

Event: org.zkoss.zk.ui.event.OpenEvent

Denotes user has opened or closed a component. Note: unlike onClose, this event is only a notification. The client sends this event after opening or closing the component.

Properties

Property

Description

Data Type

Default Value

autodrop

Sets whether to automatically drop the list if users is changing this text box.

boolean

false

buttonVisible

Sets whether the button (on the right of the textbox) is visible.

boolean

true

image

Sets the image URI that is displayed as the button to open Bandpopup.

java.lang.String

"~./zul/img/bandbtn.gif".

Methods

Name

Description

Return Data Type

clone()

java.lang.Object

closeDropdown()

Closes the popup (getDropdown()).

void

getDropdown()

Returns the dropdown window belonging to this band box.

org.zkoss.zul.Bandpopup

getInnerAttrs()

Generates the Client-Side-Action attributes to the interior tag.

java.lang.String

getOuterAttrs()

Returns west componennt

java.lang.String

getRealStyleFlags()

Returns RS_NO_WIDTH|RS_NO_HEIGHT.

insertBefore(org.zkoss.zk.ui.Component newChild, org.zkoss.zk.ui.Component refChild)

boolean

Inherited From

Bandpopup

The popup that belongs to a Bandbox instance.

Developer usually listen to the onOpen event that is sent to Bandbox and then creates proper components as children of this component.

        <bandboxid="bd">        
        <bandpopup>        
                <vbox>                
            <hbox>Search<textbox/></hbox>            
            <listboxwidth="200px"            
            onSelect="bd.value=self.selectedItem.label;bd.closeDropdown();">            
            <listhead>            
                    <listheaderlabel="Name"/>                    
                    <listheaderlabel="Description"/>                    
            </listhead>            
            <listitem>            
                    <listcelllabel="John"/>                    
                    <listcelllabel="CEO"/>                    
            </listitem>            
            <listitem>            
                    <listcelllabel="Joe"/>                    
                    <listcelllabel="Engineer"/>                    
            </listitem>            
            <listitem>            
                    <listcelllabel="Mary"/>                    
                    <listcelllabel="Supervisor"/>                    
            </listitem>            
        </listbox>        
        </vbox>        
        </bandpopup>        
    </bandbox>    

Class Name

org.zkoss.zul.Bandpopup

Supported Child Components

*NONE

Supported Events

*NONE

Properties

Property

Description

Data Type

Default Value

visible

Sets whether this component is visible.

boolean

true

Methods

Name

Description

Return Data Type

setParent(org.zkoss.zk.ui.Component parent)

void

Inherited From

Calendar

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>

Class Name

org.zkoss.zul.Calendar

Supported Child Components

*NONE

Supported Events

*NONE

Properties

Property

Description

Data Type

Default Value

compact

Sets whether to use a compact layout.

boolean

true

name

Sets the name of this component.

java.lang.String

null

timeZone

Sets the time zone that this date box belongs to, or null if the default time zone is used.

java.util.TimeZone

Determined by TimeZones.getCurrent()

value

Assigns a value to this component.

java.util.Date

today

visible

Sets whether this component is visible.

boolean

true

Methods

Name

Description

Return Data Type

getOuterAttrs()

java.lang.String

Borderlayout

The layout component is a nested component. The parent component is borderlayout, and its children components include north, south, center, west, and east. The combination of children components of borderlayout is free.

<borderlayout height="500px">
    <north size="50%" border="0">    
        <borderlayout>        
            <west size="25%" border="none" flex="true">            
                <div style="background:#B8D335">                
                    <label value="25%"                    
                        style="color:white;font-size:50px" />                        
                </div>                
            </west>            
            <center border="none" flex="true">            
                <div style="background:#E6D92C">                
                    <label value="25%"                    
                        style="color:white;font-size:50px" />                        
                </div>                
            </center>            
            <east size="50%" border="none" flex="true">            
                <label value="Here is a non-border"                
                    style="color:gray;font-size:30px" />                    
            </east>            
        </borderlayout>        
    </north>    
    <center border="0">    
        <borderlayout>        
            <west size="30%" flex="true" border="0">            
                <div style="background:#E6D92C">                
                    <label value="30%"                    
                        style="color:white;font-size:50px" />                        
                </div>                
            </west>            
            <center>            
                <label value="Here is a border"                
                    style="color:gray;font-size:30px" />                    
            </center>            
            <east size="30%" flex="true" border="0">            
                <div style="background:#B8D335">                
                    <label value="30%"                    
                        style="color:white;font-size:50px" />                        
                </div>                
            </east>            
        </borderlayout>        
    </center>    
</borderlayout>

Class Name

org.zkoss.zkex.zul.Borderlayout

Supported Child Components

North , East , West, South , Center

Supported Events

*None

Properties

*None

Methods

Name

Description

Return Data Type

getCenter()

Returns center component

Center

getEast()

Returns east component

East

getNorth()

Returns north component

North

getSouth()

Returns south component

South

getWest()

Returns west componennt

West

insertBefore(org.zkoss.zk.ui.Component child, org.zkoss.zk.ui.Component insertBefore)

resize()

Re-size the layout component.

Box

The box model of XUL is used to divide a portion of the display into a series of boxes. Components inside of a box will orient themselves horizontally or vertically. By combining a series of boxes and separators, you can control the layout of the visual presentation.

A box can lay out its children in one of two orientations, either horizontally or vertically. A horizontal box lines up its components horizontally and a vertical box orients its components vertically. You can think of a box as one row or one column from an HTML table.

<zk>
    <box orient="vertical">    
        <button label="Button 1"/>        
        <button label="Button 2"/>        
    </box>    
    <box orient="horizontal">    
        <button label="Button 3"/>        
        <button label="Button 4"/>        
    </box>    
</zk>

Class Name

org.zkoss.zul.Box

Supported Child Components

*ALL

Supported Events

*NONE

Properties

Property

Description

Data Type

Default Value

heights

Sets the widths/heights, which is a list of numbers separated by comma to denote the width/height of each cell in a box.

java.lang.String

<null>

ori ent

Sets the orient.

Values:horizontal | ver tical

java.lang.String

<null>

spacing

Sets the spacing.(such as "0", "5px", "3pt" or "1em")

java.lang.String

<null>

val ign

Sets the vertical alignment of the adjacent cells of a box.

Value:top|middle|bottom

java.lang.String

top

widths

Sets the widths/heights, which is a list of numbers separated by comma to denote the width/height of each cell in a box.

java.lang.String

<empty>

Methods

Name

Description

Return Data Type

getChildInnerAttrs(org.zkoss.zk.ui.Component)

Returns the inner attributes used to wrap the children (never null).

java.lang.String

getChildOuterAttrs(org.zkoss.zk.ui.Component)

Returns the outer attributes used to wrap the children (never null).

java.lang.String

onDrawNewChild(org.zkoss.zk.ui.Component, java.lang.StringBuffer)

void

Button

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

Class Name

org.zkoss.zul.Button

Supported Child Components

*NONE

Supported Events

Name

Event Type

onClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has clicked the component.

onRightClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has right-clicked the component.

onDoubleClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has double-clicked the component.

onFocus

org.zkoss.zk.ui.event.Event

Description: Denotes when a component gets the focus.

onBlur

org.zkoss.zk.ui.even.Event

Description: Denotes when a component loses the focus.

Properties

Property

Description

Data Type

Default Value

dir

Sets the direction of button

Value:normal | reverse

java.lang.String

normal

disabled

Sets whether it is disabled or not

boolean

false

href

Provides a hyper link

java.lang.String

<empty string>

orient

Sets the orientation of button

Value:horizontal | vertical

java.lang.String

horizontal

target

Sets the target frame or window

java.lang.String

<null>

tabindex

Sets the tab order of this component

int

-1

Methods

Name

Description

Return Data Type

isChildable()

Determines whether it accepts child components

Value: false

Note: No child is allowed.

boo lean

Captcha

A captcha component can generate a special distortion image, also called a CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) image. Developers could set height and width for dimension of captcha. By default, captcha render the image with a randomly generated text, and developers can set value to assign a purposive text.

<vbox>
<captcha id="cpa" length="5" width="200px" height="50px"/>
</vbox>

Class Name

org.zkoss.zul.Captcha

Supported Child Components

*NONE

Supported Events

Name

Event Type

onClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has clicked the component.

Use getX(), getY() method get coo rdinates.

Properties

Property

Description

Data Type

Default Value

bgColor

Sets the background color of the chart. It must be #RRGGBB format (hexdecimal).

String

"#74979B"

exclude

Sets exclude characters that will not be generated. Note that only digit and character is used in generating text value. If you leave exclude null, the default exclude list will be applied; i.e., 0123456789IilOo (only character (no digits) are used except I, i, l, O(big O), o(small o))

String

" 0123456789IOilo "

fontColor

Sets font color. It must in #RRGGBB format (hexdecimal).

String

#404040

height

Sets height of captcha, it colud be a px, pt or em value and it will transfer to px.

String

50

length

Sets length of the autogenerated text value

int

5

noise

Sets the flag of noise generation

boolean

true

value

Sets the text value to be shown as the distortion captcha

String

Random Value

width

Set width of captcha, it colud be a px, pt or em value and it will transfer to px.

String

200

Methods

Name

Description

Return Data Type

addFont

Adds fonts into fonts list.

void

getBgRGB

Gets the background color in int

int

getCaptchaEngine

Gets the captcha engine.

CaptchaEngine

getDefaultFonts

Gets the default font list.

java.awt.Font[]

getFont

Gets n-th Font

java.awt.Font

getFontRGB

Gets the font color in int.

int

getFonts

Gets fonts list, default provide two fonts.

java.util.List

getIntHeight

Gets the captcha int height in pixel; to be used by the derived subclass.

int

getIntWidth

Get the captcha int width in pixel; to be used by the derived subclass.

int

newCaptchaEngine

Instantiates the default captcha engine.

CaptchaEngine

randomValue

Regenerates new captcha text value and redraw

String

setEngine

Set the captcha engine instance or by a class name string.

void

smartDrawCaptcha

Marks a draw flag to inform that this Chart needs update.

void

Caption

A header for a Groupbox. It may contain either a text label, using LabelElement.setLabel(java.lang.String), or child elements for a more complex caption.

<zk>
<window border="normal" width="350px">
<caption label="This is a caption"/>
        <groupbox width="300px">        
                 <caption label="fruits"/>                
        <radiogroup onCheck="fruit.value = self.selectedItem.label">        
        <radio label="Apple"/>        
    <radio label="Orange"/>    
    <radio label="Banana"/>     
        </radiogroup>        
        </groupbox>        
</window>
            </zk>            

Class Name

org.zkoss.zul.Caption

Supported Child Components

*ALL

Supported Events

Name

Event Type

onClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has clicked the component.

onRightClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has right-clicked the component.

onDoubleClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has double-clicked the component.

Properties

*NONE

Methods

Name

Description

Return Data Type

getCompoundLabel()

Returns a compound label, which is the catenation of parent's title, if the parent is Window, and LabelElement.getLabel().

java.lang.String

getOuterAttrs()

java.lang.String

getSclass()

Returns the style class.

java.lang.String

invalidate()

void

isClosableVisible()

Returns whether to display the closable button.

boo lean

isLegend()

Returns whether the legend mold shall be used.

boo lean

setParent(org.zkoss.zk.ui.Component)

void

Center

This component is a center region. The default class of CSS is specified "layout-region-center".

<borderlayout height="500px">
    <north size="50%" border="0">    
        <borderlayout>        
            <west size="25%" border="none" flex="true">            
                <div style="background:#B8D335">                
                    <label value="25%"                    
                        style="color:white;font-size:50px" />                        
                </div>                
            </west>            
            <center border="none" flex="true">            
                <div style="background:#E6D92C">                
                    <label value="25%"                    
                        style="color:white;font-size:50px" />                        
                </div>                
            </center>            
            <east size="50%" border="none" flex="true">            
                <label value="Here is a non-border"                
                    style="color:gray;font-size:30px" />                    
            </east>            
        </borderlayout>        
    </north>    
    <center border="0">    
        <borderlayout>        
            <west size="30%" flex="true" border="0">            
                <div style="background:#E6D92C">                
                    <label value="30%"                    
                        style="color:white;font-size:50px" />                        
                </div>                
            </west>            
            <center>            
                <label value="Here is a border"                
                    style="color:gray;font-size:30px" />                    
            </center>            
            <east size="30%" flex="true" border="0">            
                <div style="background:#B8D335">                
                    <label value="30%"                    
                        style="color:white;font-size:50px" />                        
                </div>                
            </east>            
        </borderlayout>        
    </center>    
</borderlayout>

Class Name

org.zkoss.zkex.zul.Center

Supported Child Components

*NONE

Supported Events

Name

Inherited From

OnOpen

org.zkoss.zk.ui.event.OpenEvent

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

Properties

Property

Description

Data Type

Default Value

size

Sets the size of this region.

java.lang.String

null

Methods

Name

Description

Return Data Type

getPosition()

Returns Borderlayout.NORTH.

java.lang.String

setWidth(java.lang.String width)

The width can't be specified in this component because its width is determined by other region components (West or East).

void

Chart

A chart is used to show a set of data as a graph. It helps users to judge things with a snapshot. To use a chart component , developers must prepare a ChartModel and a ChartEngine. Developers also set proper chart type, and the threeD (3D) attribute to draw proper chart. The model and type must match to each other; or the result is unpredictable. The 3D chart is not supported on all chart type.

Type

Model

3D

pie

PieModel

o

ring

PieModel

x

bar

CategoryModel

o

line

CategoryModel or XYModel

o

area

CategoryModel or XYModel

x

stacked_bar

CategoryModel

o

stacked_area

CategoryModel or XYModel

x

waterfall

CategoryModel

x

polar

XYModel

x

scatter

XYModel

x

time_series

XYModel

x

polar

XYModel

x

step_area

XYModel

x

step

XYModel

x

histogram

XYModel

x

candlestick

HiLoModel

x

hilow

HiLoModel

x

<vbox>
<chart id="mychart" title="Pie Chart Demo" width="500" height="250" type="pie" threeD="true" fgAlpha="128"/>
<zscript>
PieModel model = new MyPieModel();
mychart.setModel(model);
</zscript>
</vbox>

Class Name

org.zkoss.zul.Chart

Supported Child Components

*NONE

Supported Events

Name

Event Type

onClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has clicked the component.

Use getX(), getY() method to get coo rdinates.

Use getArea() method to get the area component which user clicks on.

Properties

Property

Description

Data Type

Default Value

bgAlpha

Sets the background alpha (transparency, 0 ~ 255).

int

255

bgColor

Sets the background color of the chart.It must be in #RRGGBB format (hexdecimal).

String

null

fgAlpha

Sets the foreground alpha (transparency, 0 ~ 255).

int

255

height

Sets height of chart, it must be a integer string

String

200

orient

Sets the chart orientation.

Values: vertical | horizontal

String

vertical

paneAlpha

Sets the pane alpha (transparency, 0 ~ 255).

int

255

panelColor

Sets the pane color of the chart.It must be #RRGGBB format (hexdecimal).

String

null

per iod

Sets the period used in Time Series Chart.

Values : millisecond | second | minute | | hour | day | week | month | quarter | year

String

null

showLegend

Sets the flag of showing the chart's legend

boolean

true

showTooltiptext

Sets the flag of showing the chart's tool tip text

boolean

true

threeD

Sets true to show three dimensional graph (If a type of chart got no 3d peer, this is ignored).

boolean

false

title

Sets the chart's title.

String

null

type

Set the chart's type

Values: pie | ring | bar | line | area | stacked_bar | stacked_area | waterfall | polar | scatter | time_series | polar | step_area | step | histogram | candlestick | hilow

String

null

width

Sets width of chart, it must be a integer string

String

400

xAxis

Sets the label in xAxis.

String

null

yAxis

Sets the label in yAxis.

String

null

Methods

Name

Description

Return Data Type

getAreaListener

Returns the renderer to render each area, or null if the default renderer is used.

ChartAreaListener

getBgRGB

Get the background color in int array (0: red, 1: green, 2:blue).

int[]

getEngine

Returns the implemetation chart engine.

ChartEngine

getIntHeight

Get the chart int width in pixel

int

getIntWidth

Get the chart int width in pixel

int

getModel

Returns the chart model associated with this chart, or null if this chart is not associated with any chart data model

ChartModel

getPaneRGB

Get the pane color in int array (0: red, 1: green, 2:blue).

int[]

getTimeZone

Returns the time zone that this Time Series Chart belongs to, or null if the default time zone is used.

TimeZone

newChartEngine

Instantiates the default chart engine

ChartEngine

setAreaListener

Sets the renderer which is used to render each area

setEngine

Sets the chart engine

setModel

Sets the chart model associated with this chart

setTimeZone

Sets the time zone that this Time Series Chart belongs to, or null if the default time zone is used

smartDrawChart

mark a draw flag to inform that this Chart needs update

Checkbox

A checkbox.

<window title="Checkbox demo" border="normal" width="350px">
        <checkbox id="apple" label="Apple" onCheck="doChecked()" />        
        <checkbox id="orange" label="Orange" onCheck="doChecked()" />        
        <checkbox id="banana" label="Banana" onCheck="doChecked()" />        
        <hbox>You have selected :<label id="fruit2"/></hbox>        
        <zscript>        
            void doChecked() {            
                fruit2.value = (apple.isChecked() ? apple.label+' ' : &quot;&quot;)                 
                    + (orange.isChecked() ? orange.label+' ' : &quot;&quot;)                     
                    + (banana.isChecked() ? banana.label+' ' : &quot;&quot;);                    
            }            
        </zscript>        
</window>

Class Name

org.zkoss.zul.Button

Supported Child Components

*ALL

Supported Events

Name

Event Type

onRightClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has right-clicked the component.

onDoubleClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has double-clicked the component.

onFocus

org.zkoss.zk.ui.event.Event

Description: Denotes when a component gets the focus.

onBlur

org.zkoss.zk.ui.even.Event

Description: Denotes when a component loses the focus.

onCheck

org.zkoss.zk.ui.event.CheckEvent

Description: Denotes when a component loses the focus.

Properties

Property

Description

Data Type

Default Value

checked

Sets whether it is checked.

boo lean

false

dis abled

Sets whether it is disabled.

boolean

false

name

Sets the name of this component.

java.lang.String

<null>

tabindex

Sets the tab order of this component.

int

-1

Methods

Name

Description

Return Data Type

getInnerAttrs()

Appends interior attributes for generating the HTML checkbox tag (the name, disabled and other attribute).

java.lang.String

getLabelAttrs()

Returns the attributes used by the embedded HTML LABEL tag.

java.lang.String

getOuterAttrs()

Appends exterior attributes for generating the HTML span tag (the event relevant attribute).

java.lang.String

Column

A single column in a Columns element. Each child of the Column element is placed in each successive cell of the grid. The column with the most child elements determines the number of rows in each column. The use of column is mainly to define attributes for each cell in the grid.

<window title="Grid Demo" border="normal" width="360px">
    <zscript>    
    class Comp implements Comparator {    
        private boolean _asc;        
        public Comp(boolean asc) {        
            _asc = asc;            
        }        
        public int compare(Object o1, Object o2) {        
            String s1 = o1.getChildren().get(0).getValue(),            
                s2 = o2.getChildren().get(0).getValue();                
            int v = s1.compareTo(s2);            
            return _asc ? v: -v;            
        }        
    }    
    Comp asc = new Comp(true), dsc = new Comp(false);    
    </zscript>    
    <grid>    
        <columns sizable="true">        
            <column label="Type" sortAscending="&#36;{asc}" sortDescending="&#36;{dsc}"/>            
            <column label="Content"/>            
        </columns>        
        <rows>        
            <row>            
                <label value="File:"/>                
                <textbox width="99%"/>                
            </row>            
            <row>            
                <label value="Type:"/>                
                <hbox>                
                    <listbox rows="1" mold="select">                    
                        <listitem label="Java Files,(*.java)"/>                        
                        <listitem label="All Files,(*.*)"/>                        
                    </listbox>                    
                    <button label="Browse..."/>                    
                </hbox>                
            </row>            
            <row>            
                <label value="Options:"/>                
                <textbox rows="3" width="99%"/>                
            </row>            
        </rows>        
    </grid>    
</window>

Class Name

org.zkoss.zul.Column

Supported Child Components

*ALL

Supported Events

Name

Event Type

onClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has clicked the component.

onRightClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has right-clicked the component.

onDoubleClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has double-clicked the component.

Properties

Property

Description

Data Type

Default Value

sortAscending

Sets the ascending sorter, or null for no sorter for the ascending order.

java.util.Comparator

<null>

sortDescending

Sets the descending sorter, or null for no sorter for the descending order.

java.util.Comparator

<null>

sortDirection

Sets the sort direction.

Value: ascending|descending|natural

java.lang.String

natural

Methods

Name

Description

Return Data Type

getGrid()

Returns the grid that contains this column.

org.zkoss.zul.Grid

getOuterAttrs()

java.lang.String

getSclass()

Returns the style class.

java.lang.String

onSort()

It invokes sort(boolean) to sort list items and maintain getSortDirection().

void

setParent(org.zkoss.zk.ui.Component parent)

void

setSortAscending(java.lang.String)

Sets the ascending sorter with the class name, or null for no sorter for the ascending order.

void

setSortDescending(java.lang.String)

Sets the descending sorter with the class name, or null for no sorter for the descending order.

void

sort(boolean)

Sorts the rows (Row) based on getSortAscending() and getSortDescending(), if getSortDirection() doesn't matches the ascending argument.

boo lean

sort(boolean, boolean)

Sorts the rows (Row) based on getSortAscending() and getSortDescending().

boo lean

Columnchildren

Child of Columnchildren only can be Panel.

<columnlayout>
    <columnchildren width="30%" style="padding: 5px">    
        <panel height="100px" style="margin-bottom:10px"        
            title="column1-1" border="normal" maximizable="true" collapsible="true">            
            <panelchildren>Panel</panelchildren>            
        </panel>        
        <panel height="100px" framable="true" title="column1-2"        
            border="normal" maximizable="true" style="margin-bottom:10px">            
            <panelchildren>Panel</panelchildren>            
        </panel>        
        <panel height="100px" title="column1-3" border="normal" closable="true">        
            <panelchildren>Panel</panelchildren>            
        </panel>        
    </columnchildren>    
    <columnchildren width="40%" style="padding: 10px">    
        <panel title="Data" maximizable="true" border="normal" style="margin-bottom:10px">        
            <panelchildren>            
                <grid fixedLayout="true" style="border:0px" height="100%">                
                    <columns>                    
                        <column label="category" />                        
                        <column label="value" />                        
                    </columns>                    
                    <rows>                    
                        <row>                        
                            <label id="c0" value="C/C++" />                            
                            <decimalbox id="v0" value="21.2"                            
                                constraint="no empty" onChange="update(0)" />                                
                        </row>                        
                        <row>                        
                            <label id="c1" value="VB" />                            
                            <decimalbox id="v1" value="10.2"                            
                                constraint="no empty" onChange="update(1)" />                                
                        </row>                        
                        <row>                        
                            <label id="c2" value="Java" />                            
                            <decimalbox id="v2" value="40.4"                            
                                constraint="no empty" onChange="update(2)" />                                
                        </row>                        
                        <row>                        
                            <label id="c3" value="PHP" />                            
                            <decimalbox id="v3" value="28.2"                            
                                constraint="no empty" onChange="update(3)" />                                
                        </row>                        
                    </rows>                    
                </grid>                
            </panelchildren>            
        </panel>        
        <panel border="normal">        
            <panelchildren>            
                <checkbox label="3D Chart" checked="true"                
                    onCheck="mychart.setThreeD(self.isChecked())" />                    
                <chart id="mychart" title="Pie Chart Demo" width="320px"                
                    type="pie" threeD="true" fgAlpha="128">                    
                    <attribute name="onClick">                    
                            String areaid = event.getArea();                             
                            if (areaid!= null) {                             
                            Area area = self.getFellow(areaid);                            
                            alert(""+area.getAttribute("entity")+":"+area.getTooltiptext());                            
                            }                            
                        </attribute>                        
                    <zscript>                    
                            void update(int rowIndex) {                             
                            Label lb = (Label) self.getFellow("c"+rowIndex);                            
                            Decimalbox db = (Decimalbox)self.getFellow("v"+rowIndex);                            
                            model.setValue(lb.value, newDouble(db.getValue().doubleValue())); }                            
                            PieModel model = new SimplePieModel();                            
                            for(int j=0; j &lt; 4; ++j) { update(j); }                            
                            mychart.setModel(model);                            
                        </zscript>                        
                </chart>                
            </panelchildren>            
        </panel>        
    </columnchildren>    
</columnlayout>

Class Name

org.zkoss.zkex.zul.Columnchildren

Supported Child Components

Panel

Supported Events

*None

Properties

*None

Methods

Name

Description

Return Data Type

getMoldSclass()

String

insertBefore(org.zkoss.zk.ui.Component child, org.zkoss.zk.ui.Component insertBefore)

boolean

setParent(org.zkoss.zk.ui.Component parent)

void

Columnlayout

A columnlayout lays out a container which can have multiple columns, and each column may contain one or more panel.Use Columnlayout need assign width (either present or pixel) on every Columnchildren, or we cannot make sure about layout look.

<columnlayout>
    <columnchildren width="30%" style="padding: 5px">    
        <panel height="100px" style="margin-bottom:10px"        
            title="column1-1" border="normal" maximizable="true" collapsible="true">            
            <panelchildren>Panel</panelchildren>            
        </panel>        
        <panel height="100px" framable="true" title="column1-2"        
            border="normal" maximizable="true" style="margin-bottom:10px">            
            <panelchildren>Panel</panelchildren>            
        </panel>        
        <panel height="100px" title="column1-3" border="normal" closable="true">        
            <panelchildren>Panel</panelchildren>            
        </panel>        
    </columnchildren>    
    <columnchildren width="40%" style="padding: 10px">    
        <panel title="Data" maximizable="true" border="normal" style="margin-bottom:10px">        
            <panelchildren>            
                <grid fixedLayout="true" style="border:0px" height="100%">                
                    <columns>                    
                        <column label="category" />                        
                        <column label="value" />                        
                    </columns>                    
                    <rows>                    
                        <row>                        
                            <label id="c0" value="C/C++" />                            
                            <decimalbox id="v0" value="21.2"                            
                                constraint="no empty" onChange="update(0)" />                                
                        </row>                        
                        <row>                        
                            <label id="c1" value="VB" />                            
                            <decimalbox id="v1" value="10.2"                            
                                constraint="no empty" onChange="update(1)" />                                
                        </row>                        
                        <row>                        
                            <label id="c2" value="Java" />                            
                            <decimalbox id="v2" value="40.4"                            
                                constraint="no empty" onChange="update(2)" />                                
                        </row>                        
                        <row>                        
                            <label id="c3" value="PHP" />                            
                            <decimalbox id="v3" value="28.2"                            
                                constraint="no empty" onChange="update(3)" />                                
                        </row>                        
                    </rows>                    
                </grid>                
            </panelchildren>            
        </panel>        
        <panel border="normal">        
            <panelchildren>            
                <checkbox label="3D Chart" checked="true"                
                    onCheck="mychart.setThreeD(self.isChecked())" />                    
                <chart id="mychart" title="Pie Chart Demo" width="320px"                
                    type="pie" threeD="true" fgAlpha="128">                    
                    <attribute name="onClick">                    
                            String areaid = event.getArea();                             
                            if (areaid!= null) {                             
                            Area area = self.getFellow(areaid);                            
                            alert(""+area.getAttribute("entity")+":"+area.getTooltiptext());                            
                            }                            
                        </attribute>                        
                    <zscript>                    
                            void update(int rowIndex) {                             
                            Label lb = (Label) self.getFellow("c"+rowIndex);                            
                            Decimalbox db = (Decimalbox)self.getFellow("v"+rowIndex);                            
                            model.setValue(lb.value, newDouble(db.getValue().doubleValue())); }                            
                            PieModel model = new SimplePieModel();                            
                            for(int j=0; j &lt; 4; ++j) { update(j); }                            
                            mychart.setModel(model);                            
                        </zscript>                        
                </chart>                
            </panelchildren>            
        </panel>        
    </columnchildren>    
</columnlayout>

Class Name

org.zkoss.zkex.zul.Columnlayout

Supported Child Components

Columnchildern

Supported Events

*None

Properties

*None

Methods

Name

Description

Return Data Type

getMoldSclass()

String

insertBefore(org.zkoss.zk.ui.Component child, org.zkoss.zk.ui.Component insertBefore)

boolean

setParent(org.zkoss.zk.ui.Component parent)

void

Columns

Defines the columns of a grid.

Each child of a columns element should be a org.zkoss.zul.Column element.

<window title="Grid Demo" border="normal" width="360px">
    <zscript>    
    class Comp implements Comparator {    
        private boolean _asc;        
        public Comp(boolean asc) {        
            _asc = asc;            
        }        
        public int compare(Object o1, Object o2) {        
            String s1 = o1.getChildren().get(0).getValue(),            
                s2 = o2.getChildren().get(0).getValue();                
            int v = s1.compareTo(s2);            
            return _asc ? v: -v;            
        }        
    }    
    Comp asc = new Comp(true), dsc = new Comp(false);    
    </zscript>    
    <grid>    
        <columns sizable="true">        
            <column label="Type" sortAscending="&#36;{asc}" sortDescending="&#36;{dsc}"/>            
            <column label="Content"/>            
        </columns>        
        <rows>        
            <row>            
                <label value="File:"/>                
                <textbox width="99%"/>                
            </row>            
            <row>            
                <label value="Type:"/>                
                <hbox>                
                    <listbox rows="1" mold="select">                    
                        <listitem label="Java Files,(*.java)"/>                        
                        <listitem label="All Files,(*.*)"/>                        
                    </listbox>                    
                    <button label="Browse..."/>                    
                </hbox>                
            </row>            
            <row>            
                <label value="Options:"/>                
                <textbox rows="3" width="99%"/>                
            </row>            
        </rows>        
    </grid>    
</window>

Class Name

org.zkoss.zul.Columns

Supported Child Components

*Column

Supported Events

Name

Event Type

onColSize

org.zkoss.zul.event.ColSizeEvent

Description: Notifies the parent of a group of headers that the widths

of two of its children are changed by the user.

Properties

*NONE

Methods

Name

Description

Return Data Type

ins ertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)

boo lean

removeChild(org.zkoss.zk.ui.Component)

boo lean

setParent(org.zkoss.zk.ui.Component)

void

Combobox

Components: combobox and comboitem.

A combobox is a special text box that embeds a drop-down list. With comboboxes, users are allowed to select from a drop-down list, in addition to entering the text manually.

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

Class Name

org.zkoss.zul.Combobox

Supported Child Components

Comboitem

Supported Events

Name

Event Type

onChange

org.zkoss.zk.ui.event.InputEvent

Description: Denotes the content of an input component has been

modified by the user.

onChanging

org.zkoss.zk.ui.event.InputEvent

Description: Denotes that user is changing the content of an input component. Notice that the component's content (at the server) won't be changed until onChange is received.

Thus, you have to invoke the getValue method in the InputEvent class to retrieve the temporary value.

onSelection

org.zkoss.zk.ui.event.SelectionEvent

Description: Denotes that user is selecting a portion of the text of an input component. You can retrieve the start and end position of the selected text by use of the getStart and getEnd methods.

onFocus

org.zkoss.zk.ui.event.Event

Description: Denotes when a component gets the focus.

onBlur

org.zkoss.zk.ui.even.Event

Description: Denotes when a component loses the focus.

onOpen

org.zkoss.zk.ui.event.OpenEvent

Description: Denotes user has opened or closed a component. Note:

unlike onClose, this event is only a notification. The

client sends this event after opening or closing the

component.

It is useful to implement load-on-demand by listening to

the onOpen event, and creating components when the

first time the component is opened.

onSelect

org.zkoss.zul.event.SelectEvent

Description: Represents an event cause by user's the list selection is changed at the client.

Properties

Property

Description

Data Type

Default Value

aut ocomplete

Sets whether to automatically complete this text box by matching the nearest item.

boo lean

false

aut odrop

Sets whether to automatically drop the list if users is changing this text box.

boolean

false

buttonVisible

Sets whether the button (on the right of the textbox) is visible.

boo lean

true

image

Sets the URI of the button image.

java.lang.String

<null>

Methods

Name

Description

Return Data Type

isChildable()

Determines whether it accepts child components

Value: true

Note: child is allowed.

boo lean

appendItem(java.lang.String)

Appends an item.

org .zkoss.zul.Comboitem

getInnerAttrs()

Generates the Client-Side-Action attributes to the interior tag.

java.lang.Str ing

getItemAtIndex(int)

Returns the item at the specified index.

org .zkoss.zul.Comboitem

getItemCount()

Returns the number of items.

int

getItems()

Returns a 'live' list of all org.zkoss.zul.Comboitem.

java.util.List

getOuterAttrs()

java.lang.String

getSelectedItem()

Returns the selected item, or null if no matched.

org .zkoss.zul.Comboitem

ins ertBefore(org.zkoss.zk.ui.Component)

boo lean

onChildAdded(org.zkoss.zk.ui.Component)

void

onChildRemoved(org. zkoss.zk.ui.Component)

void

removeItemAt(int)

Removes the child item in the list box at the given index.

org .zkoss.zul.Comboitem

setMultiline(boolean)

Sets whether it is multiline.

Note: Combobox doesn't support multiline.

void

setRows(int)

Sets the rows.

Note: Combobox doesn't support multiple rows.

void

Comboitem

An item of a combo box.

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

Class Name

org.zkoss.zul.C omboitem

Supported Child Components

*NONE

Supported Events

*NONE

Properties

Property

Description

Data Type

Default Value

value

Associate the value with this combo item.

java.lang.Object

<null>

des cription

Sets the description.

java.lang.String

<empty>

Methods

Name

Description

Return Data Type

isChildable()

Determines whether it accepts child components

Value: false

Note: No child is allowed.

boo lean

setParent(org.zkoss.zk.ui.Component)

void

Datebox

An edit box for holding a date. After click on the calender, a calender will pop-up for inputting date.

Mouseless Entry datebox

• Alt+DOWN to pop up the calendar.

• LEFT, RIGHT, UP and DOWN to change the selected day from the calendar.

• ENTER to activate the selection by copying the selected day to the datebox control.

• Alt+UP or ESC to give up the selection and close the calendar.

<datebox lenient="true" image="newButton.jpg" buttonVisible="false" />
<datebox lenient="false" compact="false" buttonVisible="true" />

Class Name

org.zkoss.zul.Datebox

Supported Child Components

*NONE

Supported Events

Name

Event Type

OnClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has clicked the component.

OnSelection

org.zkoss.zk.ui.event.SelectionEvent

Description: Denotes that user is selecting a portion of the text of an input component. You can retrieve the start and end position of the selected text by use of the getStart and getEnd methods.

OnFocus

org.zkoss.zk.ui.event.Event

Description: Denotes when a component gets the focus.

OnBlur

org.zkoss.zk.ui.even.Event

Description: Denotes when a component loses the focus.

OnChange

org.zkoss.zk.ui.even.InputEvent

Description: An input control notifies the application with the onChange event if its content is changed

by the user.

OnChanging

org.zkoss.zk.ui.even.InputEvent

Desczription: An input control also notifies the application with the onChanging event, when user is

changing the content.

Attributes

Property

Description

Data Type

Default Value

image

the URI of the button image

Values: url

String

<empty string>

lenient

whether or not date/time parsing is to be lenient

With lenient parsing, the parser may use heuristics to interpret inputs that do not precisely match this object's format.

With strict parsing, inputs must match this object's format

Values:true|false

Boolean

true

compact

whether to use a compact layout

Values:true|false

Boolean

false

buttonVisible

whether the button (on the right of the textbox) is visible

Values:true|false

Boolean

true

timezone

the time zone that this date box belongs to, or null if the default time zone is used.

java.util.TimeZone

<null>

Value

the value (in Date)

java.util.Date

<empty string>

Methods

Name

Description

Data Type

getDateFormat()

Returns the date format of the specified format Default: it uses SimpleDateFormat to format the date.

java.text.Dateformat

getDefaultFormat()

Returns the default format, which is used when constructing a datebox.

String

getRealStyleFlags()

Returns RS_NO_WIDTH|RS_NO_HEIGHT

int

GetInnerAttrs()

String

getOuterAttrs()

String

Detail

The detail component is used to display a detailed section where a master row and

multiple detail rows are on the same row.

<?xml version="1.0" encoding="UTF-8"?>
<zk>
    Please open/close the +/- button, and the layout of this page shows properly.    
    <grid fixedLayout="true" width="600px">    
        <columns>        
            <column width="25px" />            
            <column>Product Name</column>            
            <column>Price</column>            
            <column>Item location</column>            
        </columns>        
        <rows>        
            <row>            
                <detail>                
                                            <hbox>                                            
                        <image width="200px" height="200px" src="/img/icon_update.png"/>                        
                        <vbox>                        
                            <label value="Item Specifics - Item Condition"                            
                                style="font-weight:bold;font-style: italic;" />                                
                        <hbox>                        
                            <label value="Condition:" />                            
                            <label value="Used"                            
                                style="font-weight:bold;" />                                
                        </hbox>                        
                        <hbox>                        
                            <label value="Brand:" />                            
                            <label value="Apple"                            
                                style="font-weight:bold;" />                                
                        </hbox>                        
                        <hbox>                        
                            <label value="Technology:" />                            
                            <label value="DVI"                            
                                style="font-weight:bold;" />                                
                        </hbox>                        
                        <hbox>                        
                            <label value="Monitor Type:" />                            
                            <label value="LCD/Flat Panel"                            
                                style="font-weight:bold;" />                                
                        </hbox>                        
                        </vbox>                        
                    </hbox>                    
                </detail>                
                <label value="Apple 20-inch Aluminum Cinema Display M9177/A" />                
                <label style="color:green;float:right;" value="US $202.50" />                
                <label value="tulsa, ok, United States" />                
            </row>            
        </rows>        
    </grid>    
</zk>

Class Name

org.zkoss.zul.Detail

Supported Child Components

*ALL

Supported Events

Name

Event Type

Properties

Property

Description

Data Type

Default Value

contentStyle

Sets the CSS style for the content block of the window.

jave.lang.String

image

Sets the URI of the button image.

jave.lang.String

open

Sets whether the detail is open.

boolean

Methods

Name

Description

Return Data Type

Doublebox

An edit box for holding an float point value (double).

<doublebox value="2.3"/>

Class Name

org.zkoss.zul.Doublebox

Supported Child Components

*NONE

Supported Events

Name

Inherited From

OnClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has clicked the component.

OnSelection

org.zkoss.zk.ui.event.SelectionEvent

Description: Denotes that user is selecting a portion of the text of an input component. You can retrieve the start and end position of the selected text by use of the getStart and getEnd methods.

OnFocus

org.zkoss.zk.ui.event.Event

Description: Denotes when a component gets the focus.

OnBlur

org.zkoss.zk.ui.even.Event

Description: Denotes when a component loses the focus.

OnChange

org.zkoss.zk.ui.even.InputEvent

Description: An input control notifies the application with the onChange event if its content is changed

by the user.

OnChanging

org.zkoss.zk.ui.even.InputEvent

Description: An input control also notifies the application with the onChanging event, when user is

changing the content.

Attributes

Property

Description

Data Type

Default Values

value

the value (in Double), might be null unless a constraint stops it.

java.math.BigDecimal

0

Methods

Name

Description

Data Type

intValue()

Returns the value in integer.

int

longValue()

Returns the value in long.

long

doubleValue()

Returns the value in double.

double

shortValue()

Returns the value in short.

short

Div

The same as HTML DIV tag.

An extension. It has the same effect as <h:div xmlns:h="http://www.w3.org/1999/xhtml">. Note: a Window without title and caption has the same visual effect as Div, but Div doesn't implement IdSpace. In other words, Div won't affect the uniqueness of identifiers.

<div align="left" width="300px">
    <doublebox />    
</div>
<div align="right" width="300px">
    <doublebox />    
</div>

Class Name

org.zkoss.zul.Div

Supported Child Components

*All

Supported Events

*NONE

Attributes

Property

Description

Data Type

Values

align

The alignment

Values: one of left, center, right, ustify.

String

<null>

Description: use browser default

Methods

Name

Description

Return Data Type

getOuterAttrs()

String

East

This component is a east region. The default class of CSS is specified "layout-region-east".

<borderlayout height="500px">
    <north size="50%" border="0">    
        <borderlayout>        
            <west size="25%" border="none" flex="true">            
                <div style="background:#B8D335">                
                    <label value="25%"                    
                        style="color:white;font-size:50px" />                        
                </div>                
            </west>            
            <center border="none" flex="true">            
                <div style="background:#E6D92C">                
                    <label value="25%"                    
                        style="color:white;font-size:50px" />                        
                </div>                
            </center>            
            <east size="50%" border="none" flex="true">            
                <label value="Here is a non-border"                
                    style="color:gray;font-size:30px" />                    
            </east>            
        </borderlayout>        
    </north>    
    <center border="0">    
        <borderlayout>        
            <west size="30%" flex="true" border="0">            
                <div style="background:#E6D92C">                
                    <label value="30%"                    
                        style="color:white;font-size:50px" />                        
                </div>                
            </west>            
            <center>            
                <label value="Here is a border"                
                    style="color:gray;font-size:30px" />                    
            </center>            
            <east size="30%" flex="true" border="0">            
                <div style="background:#B8D335">                
                    <label value="30%"                    
                        style="color:white;font-size:50px" />                        
                </div>                
            </east>            
        </borderlayout>        
    </center>    
</borderlayout>

Class Name

org.zkoss.zkex.zul.East

Supported Child Components

*NONE

Supported Events

Name

Inherited From

OnOpen

org.zkoss.zk.ui.event.OpenEvent

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

Properties

Property

Description

Data Type

Default Value

size

Sets the size of this region.

java.lang.String

null

Methods

Name

Description

Return Data Type

getPosition()

Returns Borderlayout.NORTH.

java.lang.String

setWidth(java.lang.String width)

The width can't be specified in this component because its width is determined by other region components (West or East).

void

Fisheyebar

A fisheye bar is a bar of fisheye that is a menu similar to the fish eye menu on the Mac OS.

<window>
        Click "Change orient" button and move cursor over the fisheyebar before it changes.        
    <separator/>    
    Fisheyebar will be out of expected.(That is wrong)    
    <fisheyebar id="fish" style="position: absolute; top: 50px;    
        left:100px;margin:20px;" attachEdge="top">        
        <fisheye image="/img/icon_browser.png" label="Web Browser"        
            onClick="alert(self.label)" />            
        <fisheye image="/img/icon_calendar.png" label="Calendar"        
            onClick="alert(self.label)" />            
        <fisheye image="/img/icon_email.png" label="Email"        
            onClick="alert(self.label)" />            
        <fisheye image="/img/icon_texteditor.png" label="Text Editor"        
            onClick="alert(self.label)" />            
        <fisheye image="/img/icon_update.png" label="Software Update"        
            onClick="alert(self.label)" />            
        <fisheye image="/img/icon_users.png" label="Users"        
            onClick="alert(self.label)" />            
    </fisheyebar>    
    <button label="Change orient">    
        <attribute name="onClick">        
            if (fish.orient.equals("horizontal")) {            
                fish.orient = "vertical";                
            } else {            
                fish.orient = "horizontal";                
            }            
        </attribute>        
    </button>    
</window>

Class Name

org.zkoss.zkex.zul.Fisheyebar

Supported Child Components

*org.zkoss.zzulkex..fisheye

Supported Events

Name

Event Type

Properties

Property

Description

Data Type

Default Value

orient

Sets the orientation of fisheye.

Value: horizontal |vertical

jave.lang.String

horizontal

attachEdge

Returns the attach edge.

Value: center |left|right|top|bottom

jave.lang.String

center

labelEdge

Returns the label edge.

Value: center|left|right|top|bottom

java.lang.String

bottom

Methods

Name

Description

Return Data Type

Fisheye

A fisheye item.

<window>
        Click "Change orient" button and move cursor over the fisheyebar before it changes.        
    <separator/>    
    Fisheyebar will be out of expected.(That is wrong)    
    <fisheyebar id="fish" style="position: absolute; top: 50px;    
        left:100px;margin:20px;" attachEdge="top">        
        <fisheye image="/img/icon_browser.png" label="Web Browser"        
            onClick="alert(self.label)" />            
        <fisheye image="/img/icon_calendar.png" label="Calendar"        
            onClick="alert(self.label)" />            
        <fisheye image="/img/icon_email.png" label="Email"        
            onClick="alert(self.label)" />            
        <fisheye image="/img/icon_texteditor.png" label="Text Editor"        
            onClick="alert(self.label)" />            
        <fisheye image="/img/icon_update.png" label="Software Update"        
            onClick="alert(self.label)" />            
        <fisheye image="/img/icon_users.png" label="Users"        
            onClick="alert(self.label)" />            
    </fisheyebar>    
    <button label="Change orient">    
        <attribute name="onClick">        
            if (fish.orient.equals("horizontal")) {            
                fish.orient = "vertical";                
            } else {            
                fish.orient = "horizontal";                
            }            
        </attribute>        
    </button>    
</window>

Class Name

org.zkoss.zkex.zul.Fisheye

Supported Child Components

*None

Supported Events

Name

Event Type

Properties

Property

Description

Data Type

Default Value

label

Sets the label.

jave.lang.String

image

Returns the image URI.

jave.lang.String

null

Methods

Name

Description

Return Data Type

Flash

A generic flash component.

<flash src="SWF/cc.milestones.121503.swf" height="320" width="620"></flash>

Class Name

org.zkoss.zul.Flash

Supported Child Components

*NONE

Supported Events

*NONE

Properties

Property

Description

Data Type

Default Value

autoPlay

Sets wether the song Flash movie playing automatically

void

false

bgcolor

Sets the background color of Flash movie

void

<empty string>

loop

Sets whether the Flash movie plays repeatly

void

true

src

Sets the source path of Flash movie and redraw the component

java.lang.String

<empty string>

wode

Sets the Window Mode property of the Flash movie for transparency, layering, and positioning in the browser.

values:

  • window - movie plays in its own rectangular window on a web page.

  • opaque - the movie hides everything on the page behind it.

  • transparent - the background of the HTML page shows through all transparent portions of the movie, this may slow animation performance.

java.lang.String

transparent

Methods

*NONE

Footer

A column of the footer of a grid (Grid). Its parent must be Foot.

Unlike Column, you could place any child in a grid footer.

<grid>
    <columns>    
        <column label="Type"/>        
        <column label="Content"/>        
    </columns>    
    <rows>    
        <row>        
            <label value="File:"/>            
            <textbox width="99%"/>            
        </row>        
        <row>        
            <label value="Type:"/>            
            <hbox>            
                <listbox rows="1" mold="select">                
                    <listitem label="Java Files,(*.java)"/>                    
                    <listitem label="All Files,(*.*)"/>                    
                </listbox>                
                <button label="Browse..."/>                
            </hbox>            
        </row>        
    </rows>    
    <foot>    
        <footer>footer1</footer>        
        <footer>footer2</footer>        
    <foot>    
</grid>

Class Name

org.zkoss.zul.Footer

Supported Child Components

*ALL

Supported Events

*NONE

Properties

Property

Description

Data Type

Default Value

span

Sets wether the song Flash movie playing automatically

int

1

Methods

Name

Description

Return Data Type

getColumn()

Returns the column that is in the same column as this footer, or null if not available.

org.zkoss.zul.Column

getColumnIndex()

Returns the column index, starting from 0.

int

getGrid()

Returns the grid that this belongs to.

org.zkoss.zul.Grid

setParent(org.zkoss.zk.ui.Component parent)

void

Inherited From

Foot

Defines a set of footers (Footer) for a grid (Grid).

<grid>
    <columns>    
        <column label="Type"/>        
        <column label="Content"/>        
    </columns>    
    <rows>    
        <row>        
            <label value="File:"/>            
            <textbox width="99%"/>            
        </row>        
        <row>        
            <label value="Type:"/>            
            <hbox>            
                <listbox rows="1" mold="select">                
                    <listitem label="Java Files,(*.java)"/>                    
                    <listitem label="All Files,(*.*)"/>                    
                </listbox>                
                <button label="Browse..."/>                
            </hbox>            
        </row>        
    </rows>    
    <foot>    
        <footer>footer1</footer>        
        <footer>footer2</footer>        
    <foot>    
</grid>

Class Name

org.zkoss.zul.Foot

Supported Child Components

Footer

Supported Events

*NONE

Properties

Property

Description

Data Type

value

Sets the current value of the progress meter.

java.langString

Methods

Name

Description

Return Data Type

getGrid()

Returns the grid that this belongs to.

org.zkoss.zul.Grid

insertBefore(org.zkoss.zk.ui.Component child, org.zkoss.zk.ui.Component insertBefore)

boolean

setParent(org.zkoss.zk.ui.Component parent)

void

Grid

Components: grid, columns, column, rows and row.

A grid contains components that are aligned in rows like tables. Inside a grid, you declare two things, the columns, that define the header and column attributes, and the rows, that provide the content. To declare a set of rows, use the rows component, which should be a child element of grid. Inside that you should add row components, which are used for each row. Inside the row element, you should place the content that you want inside that row. Each child is a column of the specific row. Similarly, the columns are declared with the columns component, which should be placed as a child element of the grid. Unlike row is used to hold the content of each row, column declares the common attributes of each column, such as the width and alignment, and and optional headers, i.e., label and/or image.

<window title="Grid Demo" border="normal" width="360px">
    <zscript>    
    class Comp implements Comparator {    
        private boolean _asc;        
        public Comp(boolean asc) {        
            _asc = asc;            
        }        
        public int compare(Object o1, Object o2) {        
            String s1 = o1.getChildren().get(0).getValue(),            
                s2 = o2.getChildren().get(0).getValue();                
            int v = s1.compareTo(s2);            
            return _asc ? v: -v;            
        }        
    }    
    Comp asc = new Comp(true), dsc = new Comp(false);    
    </zscript>    
    <grid>    
        <columns sizable="true">        
            <column label="Type" sortAscending="&#36;{asc}" sortDescending="&#36;{dsc}"/>            
            <column label="Content"/>            
        </columns>        
        <rows>        
            <row>            
                <label value="File:"/>                
                <textbox width="99%"/>                
            </row>            
            <row>            
                <label value="Type:"/>                
                <hbox>                
                    <listbox rows="1" mold="select">                    
                        <listitem label="Java Files,(*.java)"/>                        
                        <listitem label="All Files,(*.*)"/>                        
                    </listbox>                    
                    <button label="Browse..."/>                    
                </hbox>                
            </row>            
            <row>            
                <label value="Options:"/>                
                <textbox rows="3" width="99%"/>                
            </row>            
        </rows>        
    </grid>    
</window>

Class Name

org.zkoss.zul.Grid

Supported Child Components

Columns Rows

Supported Events

Name

Event Type

onPaging

org.zkoss.zul.event.PagingEvent

Description: Notifies one of the pages of a multi-page component is

selected by the user.

Properties

Property

Description

Data Type

Default Value

align

Sets the horizontal alignment of the whole grid.

Val ue: left|center|right

java.lang.String

<null>

mod el

Sets the list model associated with this grid.

org.zkoss.zul.ListModel

<null>

pageSize

Sets the page size, aka., the number rows per page.

Note: Available only the paging mold

int

<null>

paginal

org.zkoss.zul.ext.Paginal

<null>

pre loadSize

Sets the number of rows to preload when receiving the rendering request from the client.

int

7

rowrenderer

Sets the renderer which is used to render each row if getModel() is not null.

org .zkoss.zul.RowRenderer

<null>

Methods

Name

Description

Return Data Type

clone()

java.lang.Object

getCell(int, int)

Returns the specified cell, or null if not available.

org.zkoss.zk.ui.Component

getColumns()

Returns the columns.

org .zkoss.zul.Columns

getFoot()

Returns the foot.

org .zkoss.zul.Foot

getOuterAttrs()

java.lang.String

getPaging()

Returns the child paging controller that is created automatically, or null if mold is not "paging", or the controller is specified externally by setPaginal(org.zkoss.zul.ext.Paginal).

org .zkoss.zul.Paging

getRows()

Returns the rows.

org .zkoss.zul.Rows

ins ertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)

boo lean

onInitRender()

Handles a private event, onInitRender.

void

onPaging()

Called when the onPaging event is received (from getPaginal()).

void

removeChild(org.zkoss.zk.ui.Component)

boo lean

renderAll()

Renders all Row if not loaded yet, with getRowRenderer().

void

renderItems(java.util.Set)

void

renderRow(Row)

Renders the specified Row if not loaded yet, with getRowRenderer().

void

renderRows(java.util.Set)

Renders a set of specified rows.

void

setMold(ListModel)

void

setRowRenderer(java.lang.String)

Sets the renderer by use of a class name.

void

Group

Adds the ability for single level grouping to the Grid.

Default getSclass(): the same as grid's sclass.

<?xml version="1.0" encoding="UTF-8"?>
<zk>
    Grid support Groupfoot in Group    

    <grid id="grid">    
        <columns id="h" sizable="true">        
            <column id="col1" label="Type"/>            
            <column id="col2" label="Content"/>            
        </columns>        
        <rows id="rows">        
            <group id="gp1">            
            <label value="Group1: (gp1)"/>            
            <label value="Group1:"/>            
            </group>            
            <row>            
                <label value="File:"/>                
                <label value="File:"/>                
            </row>            
            <row id="row1">            
                <label value="Type:"/>                
                <hbox>                
                    <listbox rows="1" mold="select">                    
                        <listitem label="Java Files,(*.java)"/>                        
                        <listitem label="All Files,(*.*)"/>                        
                    </listbox>                    
                    <button label="Browse..."/>                    
                </hbox>                
            </row>            
            <groupfoot>            
                <label value="2 Java Files"/>                
                <label value="10 Files"/>                
            </groupfoot>            
            <group id="gp2" label="Group 2 (gp2)" onOpen='alert("Group is open: "+self.open);'/>            
            <row>            
                <label value="Options:"/>                
                <label value="Options:"/>                
            </row>            
                <groupfoot>                
                <label value="2 Options"/>                
                <label value="10 Options"/>                
            </groupfoot>            
        </rows>        
    </grid>    
</zk>

Class Name

org.zkoss.zul.Group

Supported Child Components

*ALL

Supported Events

*NONE

Properties

Property

Description

Data Type

Default Value

align

Sets the horizontal alignment of the whole grid.

Val ue: left|center|right

java.lang.String

<null>

nowrap

Sets the nowrap.

boo lean

false

sclass

Sets the style class.

java.lang.String

<null>

spans

Sets the spans, which is a list of numbers separated by comma.

java.lang.String

<null>

valign

Sets the vertical alignment of the whole row.

java.lang.String

<null>

val ue

Sets the value.

java.lang.Object

<null>

label

Sets the value of the Label it contains

java.lang.String

<null>

Methods

Name

Description

Return Data Type

getChildAttrs(int)

Returns the HTML attributes for the child of the specified index.

java.lang.String

getGrid()

Returns the grid that contains this row.

org.zkoss.zul.Grid

getOuterAttrs()

java.lang.String

onDrawNewChild(org.zkoss.zk.ui.Component, java.lang.StringBuffer)

void

setParent(org.zkoss.zk.ui.Component)

void

setStyle(java.lang.String)

void

Groupbox

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>

Class Name

org.zkoss.zul.Groupbox

Supported Child Components

*ALL

Supported Events

Name

Event Type

onClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has clicked the component.

onRightClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has right-clicked the component.

onDoubleClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has double-clicked the component.

onOpen

org.zkoss.zk.ui.event.OpenEvent

Description: Denotes user has opened or closed a component. Note:

unlike onClose, this event is only a notification. The client sends this event after opening or closing the component.

It is useful to implement load-on-demand by listening to the onOpen event, and creating components when the first time the component is opened.

Properties

Property

Description

Data Type

Default Value

closable

Sets whether user can open or close the group box.

boo lean

true

con tentStyle

Sets the CSS style for the content block of the groupbox.

java.lang.Str ing

<null>

ope n

Opens or closes this groupbox.

boo lean

true

Methods

Name

Description

Return Data Type

getCaption()

Returns the caption of this groupbox.

org.zkoss.zul.Caption

get ContentSclass()

Returns the style class used for the content block of the groupbox.

jav a.lang.String

get OuterAttrs()

jav a.lang.String

ins ertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)

boo lean

onChildRemoved(org.zkoss.zk.ui.Component)

void

Groupfoot

Adds the ability for single level grouping to the Grid.

Default getSclass(): the same as grid's sclass.

<?xml version="1.0" encoding="UTF-8"?>
<zk>
    Grid support Groupfoot in Group    

    <grid id="grid">    
        <columns id="h" sizable="true">        
            <column id="col1" label="Type"/>            
            <column id="col2" label="Content"/>            
        </columns>        
        <rows id="rows">        
            <group id="gp1">            
            <label value="Group1: (gp1)"/>            
            <label value="Group1:"/>            
            </group>            
            <row>            
                <label value="File:"/>                
                <label value="File:"/>                
            </row>            
            <row id="row1">            
                <label value="Type:"/>                
                <hbox>                
                    <listbox rows="1" mold="select">                    
                        <listitem label="Java Files,(*.java)"/>                        
                        <listitem label="All Files,(*.*)"/>                        
                    </listbox>                    
                    <button label="Browse..."/>                    
                </hbox>                
            </row>            
            <groupfoot>            
                <label value="2 Java Files"/>                
                <label value="10 Files"/>                
            </groupfoot>            
            <group id="gp2" label="Group 2 (gp2)" onOpen='alert("Group is open: "+self.open);'/>            
            <row>            
                <label value="Options:"/>                
                <label value="Options:"/>                
            </row>            
                <groupfoot>                
                <label value="2 Options"/>                
                <label value="10 Options"/>                
            </groupfoot>            
        </rows>        
    </grid>    
</zk>

Class Name

org.zkoss.zul.Groupfoot

Supported Child Components

*ALL

Supported Events

*NONE

Properties

Property

Description

Data Type

Default Value

align

Sets the horizontal alignment of the whole grid.

Val ue: left|center|right

java.lang.String

<null>

nowrap

Sets the nowrap.

boo lean

false

sclass

Sets the style class.

java.lang.String

<null>

spans

Sets the spans, which is a list of numbers separated by comma.

java.lang.String

<null>

valign

Sets the vertical alignment of the whole row.

java.lang.String

<null>

val ue

Sets the value.

java.lang.Object

<null>

label

Sets the value of the Label it contains

java.lang.String

<null>

Methods

Name

Description

Return Data Type

getChildAttrs(int)

Returns the HTML attributes for the child of the specified index.

java.lang.String

getGrid()

Returns the grid that contains this row.

org.zkoss.zul.Grid

getOuterAttrs()

java.lang.String

onDrawNewChild(org.zkoss.zk.ui.Component, java.lang.StringBuffer)

void

setParent(org.zkoss.zk.ui.Component)

void

setStyle(java.lang.String)

void

Hbox

The hbox component is used to create a horizontally oriented box. Each component placed in the hbox will be placed horizontally in a row.

<zk>
    <vbox>    
        <button label="Button 1"/>        
        <button label="Button 2"/>        
    </vbox>    
    <hbox>    
        <button label="Button 3"/>        
        <button label="Button 4"/>        
    </hbox>    
</zk>

Class Name

org.zkoss.zul.Hbox

Supported Child Components

*ALL

Supported Events

*NONE

Properties

*NONE

Methods

*NONE

Html

The simplest way is to use a XUL component called html 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. Notice you can use EL expressions in it.

<window id="win" title="Html Demo">
<html><![CDATA[
<h4>Hi, ${win.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).

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=”...”>
<h4>Hi, Html Demo</h4>
<p>It is the content of the html component.</p>
</span>

Class Name

org.zkoss.zul.Html

Supported Child Components

*NONE

Supported Events

*NONE

Properties

Property

Description

Data Type

Default Value

content

Returns the embedded content (i.e., HTML tags).

String

empty ("")

Methods

Name

Description

Data Type

Values

IsChildable

(Source Text)

Determines whether it accepts child components

Note: No child is allowed.

Boolean

(Source Text)

false

Iframe

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.

<window id="win" title="This is an Iframe Demo!">
<iframe style="width:99%; height:400px;border:3px inset;" 
src="/zk-devguide.pdf" />
</window>

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 components47, you could specify the dynamically generated

content. A typical example is you could use JasperReport 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.

Class Name

org.zkoss.zul.Iframe

Supported Child Components

*NONE

Supported Events

Name

Event Type

onURIChange

org.zkoss.zk.ui.event.URIEvent

Description: Denotes the associated URI ( src ) has been changed by user.

Use getURI() to retrieve the URI being changed to .

Properties

Property

Description

Data Type

Default Value

content

org.zkoss.util.media.Media any binary content that client side browser accept (i.e., mp3, pdf...).

Media

null

Methods

Name

Description

Return Data Type

IsChildable

Determines whether it accepts child components

Note: No child is allowed.

Boolean

Image

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="/my.png">

Like using any other properties that accept an URI, you could specify "*" for identifying a

Locale dependent image. For example, if you have different image for different Locales,

you could use as follows.

<image src="/my*.png">

Then, assume one of your users is visiting your page with de_DE as the preferred Locale.

Zk will try to locate the image file called /my_de_DE.png. If not found, it will try

/my_de.png and finally /my.png.

Class Name

org.zkoss.zul.Image

Supported Child Components

*NONE

Supported Events

*NONE

Properties

Property

Description

Data Type

Default Value

content

org.zkoss.image.Image an image object (i.e., jpeg, png...).

Image

null

Methods

Name

Description

Data Type

Values

IsChildable

Determines whether it accepts child components

Note: No child is allowed.

Boolean

false

Imagemap

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.

Class Name

org.zkoss.zul.Imagemap

Supported Child Components

*NONE

Supported Events

Name

Event Type

onClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has clicked the component.

Use getX(), getY() method get coo rdinates.

Properties

Property

Description

Data Type

Default Value

content

org.zkoss.image.Image an image object (i.e., jpeg, png...).

Image

null

Methods

Name

Description

Return Data Type

IsChildable

Determines whether it accepts child components

Note: No child is allowed.

Boolean

Include

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?some=any"/>    
    <include src="mypage" argument="${anyValue}" other="${anotherValue}"/>    
</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.

If the include component is used to include a ZUML page, the included page will become part of the desktop. However, the included page is not visible until the request is processed completely. In other words, it is visible only in the following events, triggered by user or timer.

The reason is that the include component includes a page as late as the Rendering phase. On the other hand, zscript takes place at the Component Creation phase, and onCreate takes place at the Event Processing Phase. They both execute before the inclusion.

Pass Values to the Included Page

There are two ways to pass values to the included page. First, you can pass them with the query string.

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

Then, in the included page, you can access them with the getParameter method of the Execution interface or the ServletRequest interface. In EL expressions (of the included page), you can use the param variable to access them. However, you can only pass String-typed values with the query string.

${param.some}

Alternatively, we can pass any kind of values with the so-called dynamic properties by use of the setDynamicProperty method or, in ZUL, a dynamic property as follows:

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

With the dynamic properties, you can pass non-String-typed values. In the included page, you can access them with the getAttribute method of the Execution interface or the ServletRequest interface. In EL expressions (of the included page), you can use the requestScope variable to access them.

${requestScope.some}

Class Name

org.zkoss.zul.Include

Supported Child Components

*NONE

Supported Events

*NONE

Properties

Property

Description

Data Type

Default Value

src

Sets whether user can open or close the group box.

boo lean

true

localized

Sets the CSS style for the content block of the groupbox.

java.lang.Str ing

<null>

ope n

Opens or closes this groupbox.

boo lean

true

Methods

Name

Description

Data Type

Values

IsChildable

Determines whether it accepts child components

Note: No child is allowed.

Boolean

false

Intbox

A intbox is used to let users input integer data.

While input invalid data:

<window title="Intbox Demo" border="normal" width="200px">
    int box:<intbox/>    
</window>

Class Name

org.zkoss.zul.Intbox

Supported Child Components

*NONE

Supported Events

Event Name

Event Type

onChange

org.zkoss.zk.ui.event.InputEvent

Description:

Denotes the content of an input component has been modified by the user.

onChanging

org.zkoss.zk.ui.event.InputEvent

Description:

Denotes that user is changing the content of an input component. Notice that the component's content (at the server) won't be changed until onChange is received. Thus, you have to invoke the getValue method in the InputEvent class to retrieve the temporary value.

onSelection

org.zkoss.zk.ui.event.SelectionEvent

Description:

Denotes that user is selecting a portion of the text of an input component. You can retrieve the start and end position of the selected text by use of the getStart and getEnd methods.

onFocus

org.zkoss.zk.ui.event.Event

Description:

Denotes when a component gets the focus. Remember event listeners execute at the server, so the focus at the client might be changed when the event listener for onFocus got executed.

onBlur

org.zkoss.zk.ui.event.Event

Description:

Denotes when a component loses the focus. Remember event listeners execute at the server, so the focus at the client might be changed when the event listener for onBlur got executed.

onCreate

org.zkoss.ui.zk.ui.event.CreateEvent

Description:

Denotes a component is created when rendering a ZUML page.

onDrop

org.zkoss.ui.zk.ui.event.DropEvent

Description:

Denotes another component is dropped to the component that receives this event.

Properties

Property

Description

Return Data Type

val ue

Sets the text value.

Integer

Methods

*NONE

Label

A label component represents a piece of text.

<window title="Label Demo" >
<grid>
<rows>
<row>Label(normal): <label id="lb1"/></row>
<row>Label(color): <label id="lb2" style="color:red"/></row>
<row>Label(font): <label id="lb3" style="font-weight:bold"/></row>
<row>Label(size): <label id="lb4" style="font-size:14pt"/></row>
<row>Label(maxlength): <label id="lb5" maxlength="5"/></row>
<row>Label(pre): <label id="lb6" pre="true"/></row>
<row>input:
<textbox id="txt" rows="2"><attribute name="onChange">
lb1.value=self.value;
lb2.value=self.value;
lb3.value=self.value;
lb4.value=self.value;
lb5.value=self.value;
lb6.value=self.value;
</attribute></textbox>
</row>
</rows>
</grid>
</window>

You can control how a label is displayed with the style, pre and maxlength Properties.

For example, if you specify pre to be true, all white spaces, such as new line, space and tab, are preserved.

Class Name

org.zkoss.zul.Label

Supported Child Components

*NONE

Supported Events

*NONE

Properties

Property

Description

Data Type

value

The String value denote this label.

String

pre

If true, all white spaces, such as new line, space and tab, are preserved.

boolean

maxlength

Truncated the characters that exceeds the specified

Positive Int eger

Methods

Name

Description

Return Data Type

IsChildable

Determines whether it accepts child components

Note: No child is allowed.

Boolean

Listbox

Components: listbox, listitem, listcell, listhead and listheader.

A list box is used to display a number of items in a list. The user may select an item from the list.

<window title="listbox demo" border="normal">
        <listbox id="box" width="250px">        
            <listhead sizable="true">            
                <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>            
            <listfoot >            
                <listfooter><label value="This is footer1"/></listfooter>                
                <listfooter><label value="This is footer2"/></listfooter>                
            </listfoot>            
                </listbox>                
</window>

Listbox has two molds: default and select. If the select mold is used, the HTML's SELECT tag is generated instead.

Class Name

org.zkoss.zul.Listbox

Supported Child Components

Listitem Listhead Listfoot

Supported Events

Name

Event Type

onPaging

org.zkoss.zul.event.PagingEvent

Description: Notifies one of the pages of a multi-page component is

selected by the user.

Properties

Property

Description

Data Type

Default Value

align

Sets the horizontal alignment of the whole Listbox.

Val ue: left|center|right

java.lang.String

<null>

mod el

Sets the list model associated with this Listbox.

org.zkoss.zul.ListModel

<null>

pageSize

Sets the page size, aka., the number rows per page.

Note: Available only the paging mold

int

<null>

paginal

org.zkoss.zul.ext.Paginal

<null>

pre loadSize

Sets the number of rows to preload when receiving the rendering request from the client.

int

7

itemRenderer

Sets the renderer which is used to render each Listitem if getModel() is not null.

org .zkoss.zul.RowRenderer

<null>

maxlength

the maximal length of each item's label.

int

0(no effect)

multiple

Is multiple selections are allowed.

boolean

false

checkmark

Is the check mark shall be displayed in front of each item.

boolean

false

disable

Is this Listbox is disabled.

boolean

false

vflex

To grow and shrink vertical to fit their given space, so called vertial flexibility.

boolean

false

Methods

Name

Description

clone()

getIndexOfItem(Listitem)

Returns the index of the specified item, or -1 if not found.

ClearSelection()

Clears the selection.

addItemToSelection(Listitem)

Selects the given item, without deselecting any other items that are already selected..

appendItem(String,String)

Appends an item.

getItemAtIndex(int)

Returns the item at the specified index.

getSelectedIndex()

Returns the index of the selected item (-1 if no one is selected).

setSelectedIndex(int)

Deselects all of the currently selected items and selects the item with the given index.

GetItemCount()

Returns the number of items.

GetListHead()

Returns Listhead belonging to this Listbox, or null if no list headers at all.

GetListfoot()

Returns Listfoot belonging to this Listbox, or null if no list footers at all.

getOuterAttrs()

getPaging()

Returns the child paging controller that is created automatically, or null if mold is not "paging", or the controller is specified externally by setPaginal(org.zkoss.zul.ext.Paginal).

Sel ectAll()

Select all items.

ins ertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)

onInitRender()

Handles a private event, onInitRender.

onPaging()

Called when the onPaging event is received (from getPaginal()).

removeChild(org.zkoss.zk.ui.Component)

renderAll()

Renders all Listitem if not loaded yet, with getItemRenderer().

renderItems(java.util.Set)

renderItem(Listitem)

Renders the specified Row if not loaded yet, with getRowRenderer().

renderItems(java.util.Set)

Renders a set of specified rows.

setTabindex(int)

Sets the tab order of this component.

Currently, only the "select" mold supports this property.

getTabindex()

Returns the tab order of this component.

Currently, only the "select" mold supports this property.

Default: -1 (means the same as browser's default).

setItemRenderer(java.lang.String)

Sets the renderer by use of a class name.

toggleItemSelection(Listitem)

If the specified item is selected, it is deselected.

Listcell

A list cell.

<window title="listbox demo" border="normal">
        <listbox id="box" width="250px">        
            <listhead sizable="true">            
                <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>            
            <listfoot >            
                <listfooter><label value="This is footer1"/></listfooter>                
                <listfooter><label value="This is footer2"/></listfooter>                
            </listfoot>            
                </listbox>                
</window>

Class Name

org.zkoss.zul.Listcell

Supported Child Components

*ALL

Supported Events

*NONE

Properties

Name

Description

Return Data Type

span

Number of columns to span this footer.

int

value

The value this cell stored.

java.lang.Object

width

the width which the same as getListheader()'s width.

String

Methods

Name

Description

Return Data Type

getListbox()

Returns the listbox that contains this column.

org.zkoss.zul.Listbox

getColumnHtmlPostfix()

java.lang.String

getColumnHtmlPrefix()

java.lang.String

getOuterAttrs()

java.lang.String

getColumnIndex()

Returns the column index, starting from 0.

int

setParent(org.zkoss.zk.ui.Component parent)

Can only be Listhead

void

getListheader()

Returns the list header that is in the same column as this footer, or null if not available.

org.zkoss.zul.ListHeader

Invalidate()

Listfoot

Like Listhead, each listbox has at most one Listfoot.

<window title="listbox demo" border="normal">
        <listbox id="box" width="250px">        
            <listhead sizable="true">            
                <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>            
            <listfoot >            
                <listfooter><label value="This is footer1"/></listfooter>                
                <listfooter><label value="This is footer2"/></listfooter>                
            </listfoot>            
                </listbox>                
</window>

Class Name

org.zkoss.zul.Listfoot

Supported Child Components

Listfooter

Supported Events

*NONE

Properties

*NONE

Methods

Name

Description

Return Data Type

getListbox()

Returns the listbox that contains this column.

org.zkoss.zul.Listbox

Listfooter

A column of the footer of a list box (Listbox). Its parent must be Listfoot. Unlike Listheader, you could place any child in a list footer.

Note: Listcell also accepts children.

<window title="listbox demo" border="normal">
        <listbox id="box" width="250px">        
            <listhead sizable="true">            
                <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>            
            <listfoot >            
                <listfooter><label value="This is footer1"/></listfooter>                
                <listfooter><label value="This is footer2"/></listfooter>                
            </listfoot>            
                </listbox>                
</window>

Class Name

org.zkoss.zul.Listfooter

Supported Child Components

*ALL

Supported Events

*NONE

Properties

Name

Description

Return Data Type

span

Number of columns to span this footer.

int

Methods

Name

Description

Return Data Type

getListbox()

Returns the listbox that contains this column.

org.zkoss.zul.Listbox

getOuterAttrs()

java.lang.String

getColumnIndex()

Returns the column index, starting from 0.

int

setParent(org.zkoss.zk.ui.Component parent)

Can only be Listhead

void

getListfoot()

Returns the set of footers that this belongs to.

org.zkoss.zul.Listfoot

getListheader()

Returns the list header that is in the same column as this footer, or null if not available.

org.zkoss.zul.ListHeader

Listgroup

Adds the ability for single level grouping to the Listbox.

<?xml version="1.0" encoding="UTF-8"?>
<zk>
    Listbox support Grouping    
    <listbox id="listbox" width="250px">    
        <listhead sizable="true" id="h">        
            <listheader id="h1" label="name" sort="auto" />            
            <listheader id="h2" label="gender" sort="auto" />            
        </listhead>        
        <listgroup id="gp1" open="false">        
            <listcell label="Group1"/>            
            <listcell label="Group2"/>            
        </listgroup>        
        <listitem>        
            <listcell label="a Mary" />            
            <listcell label="a FEMALE" />            
        </listitem>        
        <listitem>        
            <listcell label="b Mary" />            
            <listcell label="b FEMALE" />            
        </listitem>        
        <listitem id="li1">        
            <listcell label="c Mary1" />            
            <listcell label="c FEMALE1" />            
        </listitem>        
        <listitem>        
            <listcell label="d Mary" />            
            <listcell label="d FEMALE" />            
        </listitem>        
        <listitem>        
            <listcell label="e John" />            
            <listcell label="e MALE" />            
        </listitem>        
        <listgroup id="g2" label="Grouping 2" />        
        <listitem>        
            <listcell label="Jane" />            
            <listcell label="FEMALE" />            
        </listitem>        
        <listitem>        
            <listcell label="Henry" />            
            <listcell label="MALE" />            
        </listitem>        

    </listbox>    
</zk>

Class Name

org.zkoss.zul.Listgrroup

Supported Child Components

*org.zkoss.zul.Listcell

Supported Events

Name

Event Type

Properties

Property

Description

Data Type

Default Value

maxlength

the maximal length of this item's label.

int

index

the index of this item (aka., the order in the listbox).

int

value

The value this cell stored.

Java.lang.Object

label

the width which the same as getListheader()'s width.

String

src

the src of the Listcell it contains, or null if no such cell.

String

image

Returns the image of the Listcell it contains.

String

disable

Is this Listitem is disabled.

boolean

false

sel ected

Is this Listitem is selected.

boolean

false

Methods

Name

Description

Return Data Type

getListbox()

Returns the listbox that contains this column.

org.zkoss.zul.Listbox

getOuterAttrs()

java.lang.String

setParent(org.zkoss.zk.ui.Component parent)

Can only be Listbox

void

Invalidate()

Listgroupfoot

GroupFooter serves as a summary listitem of listgroup.

<?xml version="1.0" encoding="UTF-8"?>
<zk>
    Listbox support Grouping    
    <listbox id="listbox" width="250px">    
        <listhead sizable="true" id="h">        
            <listheader id="h1" label="name" sort="auto" />            
            <listheader id="h2" label="gender" sort="auto" />            
        </listhead>        
        <listgroup id="gp1" open="false">        
            <listcell label="Group1"/>            
            <listcell label="Group2"/>            
        </listgroup>        
        <listitem>        
            <listcell label="a Mary" />            
            <listcell label="a FEMALE" />            
        </listitem>        
        <listitem>        
            <listcell label="b Mary" />            
            <listcell label="b FEMALE" />            
        </listitem>        
        <listitem id="li1">        
            <listcell label="c Mary1" />            
            <listcell label="c FEMALE1" />            
        </listitem>        
        <listitem>        
            <listcell label="d Mary" />            
            <listcell label="d FEMALE" />            
        </listitem>        
        <listitem>        
            <listcell label="e John" />            
            <listcell label="e MALE" />            
        </listitem>        
        <listgroupfoot id="f1">        
            <listcell label="10 emails" />            
            <listcell label="zk1" />            
        </listgroupfoot>        
        <listgroup id="g2" label="Grouping 2" />        
        <listitem>        
            <listcell label="Jane" />            
            <listcell label="FEMALE" />            
        </listitem>        
        <listitem>        
            <listcell label="Henry" />            
            <listcell label="MALE" />            
        </listitem>        

    </listbox>    
</zk>

Class Name

org.zkoss.zul.Listgroupfoot

Supported Child Components

*Listcell

Supported Events

Name

Event Type

Properties

Property

Description

Data Type

Default Value

maxlength

the maximal length of this item's label.

int

index

the index of this item (aka., the order in the listbox).

int

value

The value this cell stored.

Java.lang.Object

label

the width which the same as getListheader()'s width.

String

src

the src of the Listcell it contains, or null if no such cell.

String

image

Returns the image of the Listcell it contains.

String

disable

Is this Listitem is disabled.

boolean

false

sel ected

Is this Listitem is selected.

boolean

false

Methods

Name

Description

Return Data Type

getListbox()

Returns the listbox that contains this column.

org.zkoss.zul.Listbox

getOuterAttrs()

java.lang.String

setParent(org.zkoss.zk.ui.Component parent)

Can only be Listbox

void

Invalidate()

Listhead

A list headers used to define multi-columns and/or headers. Can only surpport Listheader as its child.

<window title="listbox demo" border="normal">
        <listbox id="box" width="250px">        
            <listhead sizable="true">            
                <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>            
            <listfoot >            
                <listfooter><label value="This is footer1"/></listfooter>                
                <listfooter><label value="This is footer2"/></listfooter>                
            </listfoot>            
                </listbox>                
</window>

Class Name

org.zkoss.zul.Listhead

Supported Child Components

Listheader

Supported Events

*NONE

Properties

*NONE

Methods

Name

Description

Return Data Type

getListbox()

Returns the listbox that contains this column.

org.zkoss.zul.Listbox

Listheader

The list header which defines the attributes and header of a columen of a list box. Its parent must be Listhead.

<window title="listbox demo" border="normal">
        <listbox id="box" width="250px">        
            <listhead sizable="true">            
                <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>            
            <listfoot >            
                <listfooter><label value="This is footer1"/></listfooter>                
                <listfooter><label value="This is footer2"/></listfooter>                
            </listfoot>            
                </listbox>                
</window>

Class Name

org.zkoss.zul.Listheader

Supported Child Components

*NONE

Supported Events

Name

Event Type

onClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has clicked the component.

onRightClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has right-clicked the component.

onDoubleClick

org.zkoss.zk.ui.event.MouseEvent

Description: Denotes user has double-clicked the component.

Properties

Property

Description

Data Type

sortAscending

Sets the ascending sorter, or null for no sorter for the ascending order.

java.util.Comparator

sortDescending

Sets the descending sorter, or null for no sorter for the descending order.

java.util.Comparator

sortDirection

Sets the sort direction.

Value: ascending|descending|natural

java.lang.String

maxlength

the maximal length of each item's label.

Positive integer

Methods

Name

Description

Return Data Type

getListbox()

Returns the listbox that contains this column.

org.zkoss.zul.Listbox

getOuterAttrs()

java.lang.String

getSclass()

Returns the style class.

java.lang.String

onSort()

It invokes sort(boolean) to sort list items and maintain getSortDirection().

void

getColumnIndex()

Returns the column index, starting from 0.

int

setParent(org.zkoss.zk.ui.Component parent)

Can only be Listhead

void

setSortAscending(java.lang.String)

Sets the ascending sorter with the class name, or null for no sorter for the ascending order.

void

setSortDescending(java.lang.String)

Sets the descending sorter with the class name, or null for no sorter for the descending order.

void

sort(boolean)

Sorts the rows (Row) based on getSortAscending() and getSortDescending(), if getSortDirection() doesn't matches the ascending argument.

boo lean

sort(boolean, boolean)

Sorts the rows (Row) based on getSortAscending() and getSortDescending().

boo lean

Listitem

A list item.

<window title="listbox demo" border="normal">
        <listbox id="box" width="250px">        
            <listhead sizable="true">            
                <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>            
            <listfoot >            
                <listfooter><label value="This is footer1"/></listfooter>                
                <listfooter><label value="This is footer2"/></listfooter>                
            </listfoot>            
                </listbox>                
</window>

Class Name

org.zkoss.zul.Listitem

Supported Child Components

Listcell

Supported Events

Name

Event Type

onSelect

org.zkoss.zul.event.SelectEvent

Description: Represents an event cause by user's the list selection is changed at the client.

Properties

Name

Description

Data Type

Default Value

maxlength

the maximal length of this item's label.

int

index

the index of this item (aka., the order in the listbox).

int

value

The value this cell stored.

java.lang.Object

label

the width which the same as getListheader()'s width.

String

src

the src of the Listcell it contains, or null if no such cell.

String

image

Returns the image of the Listcell it contains.

String

disable

Is this Listitem is disabled.

boolean

false

sel ected

Is this Listitem is selected.

boolean

false

Methods

Name

Description

Return Data Type

getListbox()

Returns the listbox that contains this column.

org.zkoss.zul.Listbox

getOuterAttrs()

java.lang.String

setParent(org.zkoss.zk.ui.Component parent)

Can only be Listbox

void

Invalidate()

Longbox

A longbox is used to let users input long data.

<window title="Longbox Demo" border="normal" width="200px">
    long box:<longbox/>    
</window>

Class Name

org.zkoss.zul.Longbox

Supported Child Components

*NONE

Supported Events

Event Name

Event Type

onChange

org.zkoss.zk.ui.event.InputEvent

Description:

Denotes the content of an input component has been modified by the user.

onChanging

org.zkoss.zk.ui.event.InputEvent

Description:

Denotes that user is changing the content of an input component. Notice that the component's content (at the server) won't be changed until onChange is received. Thus, you have to invoke the getValue method in the InputEvent class to retrieve the temporary value.

onSelection

org.zkoss.zk.ui.event.SelectionEvent

Description:

Denotes that user is selecting a portion of the text of an input component. You can retrieve the start and end position of the selected text by use of the getStart and getEnd methods.

onFocus

org.zkoss.zk.ui.event.Event

Description:

Denotes when a component gets the focus. Remember event listeners execute at the server, so the focus at the client might be changed when the event listener for onFocus got executed.

onBlur

org.zkoss.zk.ui.event.Event

Description:

Denotes when a component loses the focus. Remember event listeners execute at the server, so the focus at the client might be changed when the event listener for onBlur got executed.

onCreate

org.zkoss.ui.zk.ui.event.CreateEvent

Description:

Denotes a component is created when rendering a ZUML page.

onDrop

org.zkoss.ui.zk.ui.event.DropEvent

Description:

Denotes another component is dropped to the component that receives this event.

Properties

Property

Description

Return Data Type

val ue

Sets the value.

Long

Methods

Name

Description

Data Type

Values

intValue()

Returns the value in int.

int

longValue()

Returns the value in long.

long

Menu

An element, much like a button, that is placed on a menu bar. When the user clicks the menu element, the child Menupopup of the menu will be displayed. This element is also used to create submenus of Menupopup .

<menu label="File">
    <menupopup>    
        <menuitem label="New" onClick="alert(self.label)"/>        
        <menuitem label="Open" onClick="alert(self.label)"/>        
        <menuitem label="Save" onClick="alert(self.label)"/>        
        <menuseparator/>        
        <menuitem label="Exit" onClick="alert(self.label)"/>        
    </menupopup>    
</menu>

Class Name

org.zkoss.zul.Menu

Supported Child Components

Menupopup

Supported Events

*NONE

Properties

*NONE

Methods

Name

Description

Data Type

Values

getMenupopup()

Returns the Menupopup it owns, or null if not available.

Object

<null>

isTopmost()

Returns whether this is an top-level menu, i.e., not owning by another Menupopup.

Values: true | false

Boolean

True

getOutAttrs()

String

insertBefore(org.zkoss.zk.ui.Component child, org.zkoss.zk.ui.Component insertBefore)

boolean

Menubar

A container that usually contains menu elements.

<menubar id="menubar">
        <menu label="File">        
            <menupopup onOpen="alert(self.id)">            
                <menuitem label="New" onClick="alert(self.label)"/>                
                <menuitem label="Open" onClick="alert(self.label)"/>                
                <menuitem label="Save" onClick="alert(self.label)"/>                
                <menuseparator/>                
                <menuitem label="Exit" onClick="alert(self.label)"/>                
            </menupopup>            
        </menu>        
        <menu label="Help">        
            <menupopup>            
                <menuitem label="Index" onClick="alert(self.label)"/>                
                <menu label="About">                
                    <menupopup>                    
                        <menuitem label="About ZK" onClick="alert(self.label)"/>                        
                        <menuitem label="About Potix" onClick="alert(self.label)"/>                        
                    </menupopup>                    
                </menu>                
            </menupopup>            
        </menu>        
    </menubar>    

Class Name

org.zkoss.zul.Menubar

Supported Child Components

*NONE

Supported Events

*NONE

Properties

Property

Description

Data Type

Default Values

orient

The orient

Values: horizontal | vertical

String

vertical

autodrop

Returns whether to automatically drop down menus if user moves mouse over it.

Values: true | false

Boolean

false

Methods

Name

Description

Data Type

onDrawNewChild(org.zkoss.zk.ui.Component child, java.lang.StringBuffer out)

void

getOuterAttrs()

String