|
|
| (40 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| | {{ZKDevelopersReferencePageHeader}} | | {{ZKDevelopersReferencePageHeader}} |
| − | =Overview=
| |
| | | | |
| − | There are two ways to compose UI: XML-based approach and pure-Java approach. Here we describe XML-based approach. For pure-Java approach, please refer the next chapter. | + | There are two ways to compose UI: XML-based approach and pure-Java approach. Here we will describe XML-based approach. For pure-Java approach, please refer to the next chapter. |
| | | | |
| − | The declaration language is called ZK User Interface Markup Language (ZUML). It is based on XML. Each XML element instructs the ZK Loader which component to create. Each XML attribute describes what value to be assigned to the created component. Each XML processing instruction describes how to process the whole page, such as the page title. For example, | + | The declaration language is called ZK User Interface Markup Language (ZUML). It is based on XML. Each XML element instructs ZK Loader to create a component. Each XML attribute describes what value to be assigned to the created component. Each XML processing instruction describes how to process the whole page, such as the page title. For example, |
| | | | |
| | <source lang="xml"> | | <source lang="xml"> |
| Line 14: |
Line 13: |
| | where the first line specifies the page title, the second line creates a root component with title and border, and the third line creates a button with label and an event listener. | | where the first line specifies the page title, the second line creates a root component with title and border, and the third line creates a button with label and an event listener. |
| | | | |
| − | This chapter is about the general use of ZUML. For a complete reference, please refer to [[ZK_ZUML_Reference|ZUML Reference]].
| + | '''Auto-completion with Schema''' |
| | | | |
| − | =Basic Rules=
| + | When working with a ZUML document, it is suggested to use [http://www.zkoss.org/product/zkstudio.dsp ZK Studio] since it provides a lot of features to simplify editing, such as ''content assist'' and ''visual editor''. |
| | | | |
| − | If you are not familiar with XML, please take a look at [[ZK Developer's Reference/UI Composing/ZUML/XML Background|XML Background]] first. | + | If you prefer not to use ZK Studio, you could specify the XML schema in a ZUML document as shown below. Many XML editors work better, such as when with auto-complete, if XML schema is specified correctly. |
| − | | |
| − | ==A XML Element Represents a Component==
| |
| − | | |
| − | Each XML element represents a component, except special elements like <zk> and <attribute>. Thus, the following will cause three components (window, textbox and button) being created when ZK Loader processes it.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <window>
| |
| − | <textbox/>
| |
| − | <button/>
| |
| − | </window>
| |
| − | </source>
| |
| − | | |
| − | In additions, the parent-child relationship of the created components will follow the same hierarchical structure of the XML document. In the previous example, window will be the parent of textbox and button, while textbox is the first child and button is the second.
| |
| − | | |
| − | ===Special XML Elements===
| |
| − | | |
| − | There are a few elements dedicated to special functionality rather than a component. For example,
| |
| | | | |
| | <source lang="xml" > | | <source lang="xml" > |
| − | <zk>...</zk> | + | <window xmlns="http://www.zkoss.org/2005/zul" |
| | + | xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| | + | xsi:schemaLocation="http://www.zkoss.org/2005/zul http://www.zkoss.org/2005/zul/zul.xsd"> |
| | </source> | | </source> |
| | + | |
| | + | The ZUL schema can be downloaded from [http://www.zkoss.org/2005/zul/zul.xsd http://www.zkoss.org/2005/zul/zul.xsd]. In addition, you can find <code>zul.xsd</code> under the <code>dist/xsd</code> directory in the [[ZK Installation Guide/ZK Background/The Content of ZK Binary Distribution|ZK binary distribution]]. |
| | | | |
| − | [[ZK ZUML Reference/The ZK User Interface Markup Language/ZK Elements/The zk Element|The zk element]] is a special element used to aggregate other components. Unlike a real component (say, <tt>hbox</tt> or <tt>div</tt>), it is not part of the component tree being created. In other words, it doesn't represent any component. For example,
| + | This section is about the general use of ZUML. For a complete reference, please refer to [[ZUML_Reference|ZUML Reference]]. |
| − | | + | {{ZKDevelopersReferenceHeadingToc}} |
| − | <source lang="xml" >
| |
| − | <window>
| |
| − | <zk if="${whater}">
| |
| − | <textbox/>
| |
| − | <textbox/>
| |
| − | </zk>
| |
| − | </window>
| |
| − | </source>
| |
| − | | |
| − | is equivalent to
| |
| − | | |
| − | <source lang="xml" >
| |
| − | <window>
| |
| − | <textbox if="${whater}"/>
| |
| − | <textbox if="${whater}"/>
| |
| − | </window>
| |
| − | </source>
| |
| − | | |
| − | For more information about special elements, please refer to [[ZK ZUML Reference/The ZK User Interface Markup Language/ZK Elements|ZUML Reference]]
| |
| − | | |
| − | ==A XML Attribute Assigns a Value to a Component's Property or Event Listener==
| |
| − | | |
| − | Each attribute, except special attributes like <code>if</code> and <code>forEach</code>, represents a value that shall be assigned to a property of a component after it is created. The attribute name is the property name, while the attribute value is the value to assign. For example, the following assigns <code>"Hello"</code> to window's title property. More precisely, <javadoc method="setTitle(java.lang.String)">org.zkoss.zul.Window</javadoc> will be called with <code>"Hello"</code>.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <window title="Hello"/>
| |
| − | </source>
| |
| − | | |
| − | Like JSP, you could use EL as the value of any attribute. For example, the following assigns the value of the request parameter called name to window's title.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <window title="${param.name}"/>
| |
| − | </source>
| |
| − | | |
| − | For more information about EL expressions, please refer to [[ZK ZUML Reference/EL Expressions|ZUML Reference]].
| |
| − | | |
| − | ===Assign Event Listener if Name Starts With <code>on</code>===
| |
| − | | |
| − | If the attribute name starts with <code>on</code> and the third letter is uppercase, an event listener is assigned. For example, we can register an event listener to handle the onClick event as follows.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <button onClick="do_something_in_Java())"/>
| |
| − | </source>
| |
| − | | |
| − | The attribute value must be a valid Java code, and it will be interpreted<ref>ZK uses [http://www.beanshell.org BeanShell] to interpret it at run time</ref> when the event is received. You could specify different languages by prefixing the language name. For example, we could write the event listener in Groovy as follows.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <vlayout onClick="groovy:self.appendChild(new Label('New'));">
| |
| − | Click me!
| |
| − | </vlayout>
| |
| − | </source>
| |
| − | | |
| − | <blockquote>
| |
| − | ----
| |
| − | <references/>
| |
| − | </blockquote>
| |
| − | | |
| − | ===Special Attributes===
| |
| − | | |
| − | There are a few special attributes dedicated to special functionality rather than assigning properties or handling events. For example, the forEach attribute is used to specify a collection of object such that the XML element it belongs will be evaluated repeatedly for each object of the collection.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <listbox>
| |
| − | <listitem forEach="${customers}" label="${each.name}"/>
| |
| − | </listbox>
| |
| − | </source>
| |
| − | | |
| − | For more information about special attributes, please refer to [[ZK ZUML Reference/The ZK User Interface Markup Language/ZK Attributes|ZUML Reference]]
| |
| − | | |
| − | ==A XML Text Represents Label Component or Property's Value==
| |
| − | | |
| − | In general, a XML text is interpreted as a label component. For example,
| |
| − | | |
| − | <source lang="xml">
| |
| − | <window>
| |
| − | Begin ${foo.whatever}
| |
| − | </window>
| |
| − | </source>
| |
| − | | |
| − | is equivalent to
| |
| − | | |
| − | <source lang="xml">
| |
| − | <window>
| |
| − | <label value="Begin ${foo.whatever}"/>
| |
| − | </window>
| |
| − | </source>
| |
| − | | |
| − | ===A XML Text as Property's Value===
| |
| − | | |
| − | Depending on component's implementation, the text nested in a XML element could be interpreted as the value of a component's particular property. For example, <javadoc>org.zkoss.zul.Html</javadoc> is one of this kind of components, and
| |
| − | | |
| − | <source lang="xml">
| |
| − | <html>Begin ${foo.whatever}</html>
| |
| − | </source>
| |
| − | | |
| − | is equivalent to
| |
| − | | |
| − | <source lang="xml">
| |
| − | <html content="Begin ${foo.whatever}"/>
| |
| − | </source>
| |
| − | | |
| − | It is designed to make it easy to specify multiple-line value, so it is usually used by particular components that requires the multi-line value. Here is a list of components that interprets the XML text as a property's value.
| |
| − | | |
| − | {| border='1px'
| |
| − | ! Component Name !! Property Name !! Method
| |
| − | |-
| |
| − | | a
| |
| − | | label
| |
| − | | <javadoc method="setLabel(java.lang.String)">org.zkoss.zul.A</javadoc>
| |
| − | |-
| |
| − | | button
| |
| − | | label
| |
| − | | <javadoc method="setLabel(java.lang.String)">org.zkoss.zul.Button</javadoc>
| |
| − | |-
| |
| − | | comboitem
| |
| − | | content
| |
| − | | <javadoc method="setContent(java.lang.String)">org.zkoss.zul.Comboitem</javadoc>
| |
| − | |-
| |
| − | | html
| |
| − | | content
| |
| − | | <javadoc method="setContent(java.lang.String)">org.zkoss.zul.Html</javadoc>
| |
| − | |-
| |
| − | | label
| |
| − | | value
| |
| − | | <javadoc method="setValue(java.lang.String)">org.zkoss.zul.Label</javadoc>
| |
| − | |-
| |
| − | | script
| |
| − | | content
| |
| − | | <javadoc method="setContent(java.lang.String)">org.zkoss.zul.Script</javadoc>
| |
| − | |-
| |
| − | | style
| |
| − | | content
| |
| − | | <javadoc method="setContent(java.lang.String)">org.zkoss.zul.Style</javadoc>
| |
| − | |}
| |
| − | | |
| − | ==A XML Processing Instruction Specifies the Page-wide Information==
| |
| − | | |
| − | Each XML processing instruction specifies the instruction how to process the XML document. It is called directives in ZK. For example, the following specifies the page title and style.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <?page title="Grey background" style="background: grey"?>
| |
| − | </source>
| |
| − | | |
| − | Notice that there shall be ''no'' whitespace between the question mark and the processing instruction's name (i.e., page in the above example).
| |
| − | | |
| − | The other directives include the declaration of components, the class to initialize a page, the variable resolver for EL expressions, and so on.
| |
| − | For more information about directives, please refer to [[ZK ZUML Reference/The ZK User Interface Markup Language/Processing Instructions|ZUML Reference]].
| |
| − | | |
| − | =Component Set and File Extension=
| |
| − | | |
| − | =Create Components from ZUML Document=
| |
| − | | |
| − | =Version History=
| |
| − | Last Update : {{REVISIONYEAR}}/{{REVISIONMONTH}}/{{REVISIONDAY}}
| |
| − | {| border='1px' | width="100%"
| |
| − | ! Version !! Date !! Content
| |
| − | |-
| |
| − | |
| |
| − | |
| |
| − | |
| |
| − | |}
| |
| − | | |
| | {{ZKDevelopersReferencePageFooter}} | | {{ZKDevelopersReferencePageFooter}} |
There are two ways to compose UI: XML-based approach and pure-Java approach. Here we will describe XML-based approach. For pure-Java approach, please refer to the next chapter.
The declaration language is called ZK User Interface Markup Language (ZUML). It is based on XML. Each XML element instructs ZK Loader to create a component. Each XML attribute describes what value to be assigned to the created component. Each XML processing instruction describes how to process the whole page, such as the page title. For example,
<?page title="Super Application"?>
<window title="Super Hello" border="normal">
<button label="hi" onClick='alert("hi")'/>
where the first line specifies the page title, the second line creates a root component with title and border, and the third line creates a button with label and an event listener.
Auto-completion with Schema
When working with a ZUML document, it is suggested to use ZK Studio since it provides a lot of features to simplify editing, such as content assist and visual editor.
If you prefer not to use ZK Studio, you could specify the XML schema in a ZUML document as shown below. Many XML editors work better, such as when with auto-complete, if XML schema is specified correctly.
<window xmlns="http://www.zkoss.org/2005/zul"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.zkoss.org/2005/zul http://www.zkoss.org/2005/zul/zul.xsd">
The ZUL schema can be downloaded from http://www.zkoss.org/2005/zul/zul.xsd. In addition, you can find zul.xsd under the dist/xsd directory in the ZK binary distribution.
This section is about the general use of ZUML. For a complete reference, please refer to ZUML Reference.