UI Components
This documentation is for an older version of ZK. For the latest one, please click here.
This documentation is for an older version of ZK. For the latest one, please click here.
Component: an UI object
A component is an UI object, such as a label , a button and a tree . It defines the visual presentation and behaviors of a particular user interface. By manipulating them, developers control how to represent an application visually in the client.
A component must implement the Component interface.
Component = Visual Part + Java Object
Besides being a Java object in the server, a component has a visual part[1] in the browser, if and only if it belongs to a page. When a component is attached to a page, its visual part is created[2]. When a component is detached from a page, its visual part is removed.
In Java, There are two ways to attach a component into a page. First, you could call the setPage method to make a component to become a root component[3] of the specified page. Second, you could call the setParent , insertBefore or appendChild method to make it to become a child of another component. Then, the child component belongs to the same page as to which the parent belongs.
Similarly, you could detach a root component from a page by calling setPage with null . A child is detached if it is detached from a parent or its parent is detached from a page.
Notes
- ↑ If the client is a browser, the visual presentation is a DOM element or a set of DOM elements.
- ↑ The visual part is created, updated and removed automatically. Application developers rarely need to notice its existence. Rather, they manipulate the object part in the server.
- ↑ A node without a parent node is a root component.
Use id to identify component
Each component has an identifier. It is created automatically when a component is created. Developers could change it anytime. There is no limitation about how an identifier shall be named. However, if an alphabetical identifier is assigned, developers could access it directly in Java codes and EL expression embedded in the ZUML page.
<window title="Vote" border="normal">
Do you like ZK? <label id="label"/>
<separator/>
<button label="Yes" onClick="label.value = self.label"/>
<button label="No" onClick="label.value = self.label"/>
</window>
The naming of identifier is so unlimited, you can even give it a name as component name like label. First label in <label id="label"/> is a component name, the second label in <label id="label"> is the value of id of the component. label in <button label="yes"/> is a property of button,
<button label="Yes" onClick="label.value = self.label"/>
Above code means when you click the button , change the value of component whose id is label to the button 's label:yes. self is an implicit object depicting the closest component, it is button here.
Versatile Widgets
ZK provides more than 150 off the shelf widgets ready to use. You can look it up at ZK Component Reference for basic usage. Or look it up at ZUML Reference for detail. Also, java doc of their corresponding java classes is a good reference. After all, each property of the component is mapping to the setter/getter methods of java class, therefore javadoc is a good reference to find out what properties a component has. You can also visit ZK Live Demo to experience the look and feel of ZK components.
- Package org.zkoss.zul : ZUL component set that are used for HTML-based clients. It includes
window,button,listbox.
- Package org.zkoss.zkex.zul : Zul Extension library. It includes
borderlayout,jasperreport.
- Package org.zkoss.zkmax.zul : Components and UI utilities available in the Enterprise edition. It includes performance enhanced version of ZUL components. It also includes
filedownloadandtablelayout.
Inside ZK forge package, ZK has integrated FCKeditor and gmaps as a ZK component. Please refer to ZK's small talks to see the introduction of how to integrate existing 3rd party library to an exciting ZK component.
How to find out what properties a component has
Please refer to previous section: Versatile Widgets. Look into javadoc of java class of GUI component. A property always has its corresponding setter/getter methods. The mapping from tag/attribute name to class/method name is intuitive. For the tag Button, its corresponding java class is org.zkoss.zul.Button. And <button label="ok"/> will correspond to Button.setLabel("OK").