UI Components"
Tmillsclare (talk | contribs) |
m (correct highlight (via JWB)) |
||
| (9 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
{{ZKDevelopersGuidePageHeader}} | {{ZKDevelopersGuidePageHeader}} | ||
| + | {{Old Version | ||
| + | |url=http://books.zkoss.org/wiki/ZK_Developer%27s_Reference/UI_Composing/Component-based_UI | ||
| + | |}} | ||
===Component: an UI object=== | ===Component: an UI object=== | ||
| − | A component is an UI object, such as a < | + | A component is an UI object, such as a <code>label</code> , a <code>button</code> and a <code>tree</code> . 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 <javadoc type="interface">org.zkoss.zk.ui.Component</javadoc> interface. | A component must implement the <javadoc type="interface">org.zkoss.zk.ui.Component</javadoc> interface. | ||
===Component = Visual Part + Java Object=== | ===Component = Visual Part + Java Object=== | ||
| − | Besides being a Java object in the server, a component has a visual part<ref>If the client is a browser, the visual presentation is a DOM element or a set of DOM elements.</ref> in the browser, if and only if it belongs to a [ | + | Besides being a Java object in the server, a component has a visual part<ref>If the client is a browser, the visual presentation is a DOM element or a set of DOM elements.</ref> in the browser, if and only if it belongs to a [[ZK_Component_Reference/Base_Components | page]]. When a component is attached to a page, its visual part is created<ref>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.</ref>. 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 < | + | In Java, There are two ways to attach a component into a page. First, you could call the <code>setPage</code> method to make a component to become a '''root component'''<ref>A node without a parent node is a root component.</ref> of the specified page. Second, you could call the <code>setParent</code> , <code>insertBefore</code> or <code>appendChild</code> 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 < | + | Similarly, you could detach a root component from a page by calling <code>setPage</code> with <code>null</code> . A child is detached if it is detached from a parent or its parent is detached from a page. |
| Line 17: | Line 20: | ||
<references/> | <references/> | ||
| − | ===Use < | + | ===Use <code>id</code> 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 [http://en.wikipedia.org/wiki/Expression_Language EL] expression embedded in the ZUML page. | 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 [http://en.wikipedia.org/wiki/Expression_Language EL] expression embedded in the ZUML page. | ||
| Line 29: | Line 32: | ||
</source> | </source> | ||
| − | The naming of identifier is so unlimited, you can even give it a name as component name like < | + | The naming of identifier is so unlimited, you can even give it a name as component name like <code>label</code>. First <code>label</code> in <code><label id="label"/></code> is a component name, the second label in <FONT FACE="Courier"><label id="label"></FONT> is the value of id of the component. <code>label</code> in <FONT FACE="Courier"><button label="yes"/></FONT> is a property of button, |
<source lang="xml" > | <source lang="xml" > | ||
<button label="Yes" onClick="label.value = self.label"/> | <button label="Yes" onClick="label.value = self.label"/> | ||
</source> | </source> | ||
| − | Above code means when you click the < | + | Above code means when you click the <code>button</code> , change the value of component whose id is label to the <code>button</code> 's label:<code>yes</code>. <code>self</code> is an [[ZK Developer's Guide/Fundamental ZK/ZK User Interface Markup Language/Implicit Objects | implicit object]] depicting the closest component, it is <code>button</code> here. |
===Versatile Widgets=== | ===Versatile Widgets=== | ||
| − | ZK provides more than 150 off the shelf widgets ready to use. You can look it up at [[ZK Component Reference | ZK Component Reference]] for basic usage. Or look it up at [[ | + | ZK provides more than 150 off the shelf widgets ready to use. You can look it up at [[ZK Component Reference | ZK Component Reference]] for basic usage. Or look it up at [[ZUML Reference | 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 [http://www.zkoss.org/zkdemo/ ZK Live Demo] to experience the look and feel of ZK components. |
| − | *[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zul/package-summary.html Package org.zkoss.zul] : ZUL component set that are used for HTML-based clients. It includes < | + | *[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zul/package-summary.html Package org.zkoss.zul] : ZUL component set that are used for HTML-based clients. It includes <code>window</code>, <code>button</code>, <code>listbox</code>. |
| − | *[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zkex/zul/package-summary.html Package org.zkoss.zkex.zul] : Zul Extension library. It includes < | + | *[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zkex/zul/package-summary.html Package org.zkoss.zkex.zul] : Zul Extension library. It includes <code>borderlayout</code>, <code>jasperreport</code>. |
| − | *[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zkmax/zul/package-summary.html 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 < | + | *[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zkmax/zul/package-summary.html 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 <code>filedownload</code> and <code>tablelayout</code>. |
| − | Inside ZK forge package, ZK has integrated [http://www.zkoss.org/javadoc/zkforge/fckez/ FCKeditor] and [http://www.zkoss.org/javadoc/zkforge/gmapsz/ gmaps] as a ZK component. Please refer to [ | + | Inside ZK forge package, ZK has integrated [http://www.zkoss.org/javadoc/zkforge/fckez/ FCKeditor] and [http://www.zkoss.org/javadoc/zkforge/gmapsz/ gmaps] as a ZK component. Please refer to [[Small_Talks| 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=== | ===How to find out what properties a component has=== | ||
| − | Please refer to previous section: [ | + | Please refer to previous section: [[ZK_Component_Reference/Base_Components | 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 <javadoc>org.zkoss.zul.Button</javadoc>, its corresponding java class is '''org.zkoss.zul.Button'''. And <code><button label="ok"/></code> will correspond to <code>Button.setLabel("OK")</code>. |
{{ ZKDevelopersGuidePageFooter}} | {{ ZKDevelopersGuidePageFooter}} | ||
Latest revision as of 10:36, 19 January 2022
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").