|
|
| (14 intermediate revisions by 3 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 [[ZUML_Reference|ZUML Reference]].
| + | '''Auto-completion with Schema''' |
| | | | |
| − | == Auto-completion with Schema ==
| + | 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''. |
| − | Many IDEs, such Eclipse, supports auto-completion if XML schema is specified as follows. | + | |
| | + | 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. |
| | | | |
| | <source lang="xml" > | | <source lang="xml" > |
| Line 25: |
Line 25: |
| | </source> | | </source> |
| | | | |
| − | In addition to downloading from [http://www.zkoss.org/2005/zul/zul.xsd http://www.zkoss.org/2005/zul/zul.xsd], you can find <tt>zul.xsd</tt> under the <tt>dist/xsd</tt> directory in the ZK binary distribution.
| + | 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]]. |
| | | | |
| | + | This section is about the general use of ZUML. For a complete reference, please refer to [[ZUML_Reference|ZUML Reference]]. |
| | {{ZKDevelopersReferenceHeadingToc}} | | {{ZKDevelopersReferenceHeadingToc}} |
| − |
| |
| − | =Language=
| |
| − |
| |
| − | A language (<javadoc>org.zkoss.zk.ui.metainfo.LanguageDefinition</javadoc>) is a collection of component definitions. It is also known as a component set.
| |
| − |
| |
| − | For example, <javadoc>org.zkoss.zul.Window</javadoc>, <javadoc>org.zkoss.zul.Button</javadoc> and <javadoc>org.zkoss.zul.Combobox</javadoc> all belong to the same language called <code>xul/html</code>, which is also known as <code>zul</code>.
| |
| − |
| |
| − | Component designers are free to designate a component definition to any component set they prefer, as long as there is no name conflict. In additions, it is OK to use components from several languages in the same ZUML page.
| |
| − |
| |
| − | ==Language Identification==
| |
| − |
| |
| − | When parsing a ZUML document, ZK Loader have to decide the language that a XML element is associated, such that the correct component definition (<javadoc>org.zkoss.zk.ui.metainfo.ComponentDefinition</javadoc>) can be resolved. For example, in the following example, ZK needs to know <code>window</code> belongs to the xul/html language.
| |
| − |
| |
| − | <source lang="xml">
| |
| − | <window>
| |
| − | </source>
| |
| − |
| |
| − | There are two ways to identify a language: filename's extension and XML namespace. Here are an overview of them.
| |
| − | For more information please refer to [[ZUML Reference/ZUML/Languages|ZUML Reference]].
| |
| − |
| |
| − | ===Identify by Filename's Extension===
| |
| − |
| |
| − | First, when a ZUML file is parsed, the language will be decided based on the extension of the filename or a URI (<javadoc method="getByExtension(java.lang.String)">org.zkoss.zk.ui.metainfo.LanguageDefinition</javadoc>). For example, the extensions associated with <code>xul/html</code> are <code>zul</code> and <code>xul</code>. Thus, if any file whose extension is <code>zul</code> or <code>xul</code>, the default language used to parse it will be assumed to be the <code>xul/html</code> language.
| |
| − |
| |
| − | Another example: <code>xhtml</code> is another language (aka., a component set). It is associated with the extensions including <code>zhtml</code>, <code>html</code>, <code>html</code>, and <code>xhtml</code>. Thus, any file whose extension matches one of them will be considered as applying the <code>zhtml</code> language as default.
| |
| − |
| |
| − | '''Notice''' that the association of filename's extension with a language is about how ZK Loader processes a ZUML page. To really have ZK Loader to process a file, you have to configure <code>WEB-INF/web.xml</code> correctly. For example, if you want to map all XUL files to ZK Loader, you could add the following to <code>WEB-INF/web.xml</code>:
| |
| − |
| |
| − | <source lang="xml">
| |
| − | <servlet-mapping>
| |
| − | <servlet-name>zkLoader</servlet-name>
| |
| − | <url-pattern>*.xul</url-pattern>
| |
| − | </servlet-mapping>
| |
| − | </source>
| |
| − |
| |
| − | ===Identify by XML Namespace===
| |
| − |
| |
| − | If you map ZK Loader to a filename's extension that is not recognized, you could use XML namespaces to specify the language used to parse it. Each language is associated with a unique XML namespace that you can identify it easily in a ZUML document.
| |
| − |
| |
| − | For example, you map ZK Loader to <code>*.foo</code>, then you could specify the xul/html language's namespace, which is <code>http://www.zkoss.org/2005/zul</code>:
| |
| − |
| |
| − | <source lang="xml">
| |
| − | <window xmlns="http://www.zkoss.org/2005/zul">
| |
| − | ...
| |
| − | </source>
| |
| − |
| |
| − | where the xmlns attribute declares a XML namespace to associate all element without explicit prefix, such as window in this case.
| |
| − |
| |
| − | If you want to use several languages in the same XML document, you could use XML namespaces to distinguish them too. For example, the xhtml language's namespace is <code>http://www.w3.org/1999/xhtml</code>, and we could do as follows.
| |
| − |
| |
| − | <source lang="xml">
| |
| − | <window xmlns:h="http://www.w3.org/1999/xhtml">
| |
| − | <h:table>
| |
| − | <h:tr>
| |
| − | <h:td>
| |
| − | <button/>
| |
| − | </h:td>
| |
| − | </h:tr>
| |
| − | </h:table>
| |
| − | </window>
| |
| − | </source>
| |
| − |
| |
| − | Notice that table, tr and td are also components though they are very simple -- a simple wrapper of HTML tags. There is a better way to generate HTML tags: the native namespace. For more information please refer to the [[ZK_Developer's_Reference/Performance_Tips/Use_Native_Namespace_instead_of_XHTML_Namespace|Native Namespace]] section.
| |
| − |
| |
| − | ===Identify by XML Namespace with Shortcut===
| |
| − |
| |
| − | To make it easy to specify a namespace, you could specify a shortcut instead of the full namespace URI. For languages, the shortcut is the last word of the namespace URI. For example, <code>zul</code> for <code>http://www.zkoss.org/2005/zul</code>, and <code>xhtml</code> for http://www.w3.org/1999/xhtml. Thus, we can simply the previous example as follows.
| |
| − |
| |
| − | <source lang="xml" high="1">
| |
| − | <window xmlns:h="xhtml">
| |
| − | <h:span>
| |
| − | <h:tr>
| |
| − | <h:td>
| |
| − | <button/>
| |
| − | </h:td>
| |
| − | </h:tr>
| |
| − | </h:table>
| |
| − | </window>
| |
| − | </source>
| |
| − |
| |
| − | =Version History=
| |
| − | Last Update : {{REVISIONYEAR}}/{{REVISIONMONTH}}/{{REVISIONDAY}}
| |
| − | {| border='1px' | width="100%"
| |
| − | ! Version !! Date !! Content
| |
| − | |-
| |
| − | | 5.0.4
| |
| − | | August, 2010
| |
| − | | The shortcut was introduced to make it easy to specify a standard namespace, such as native, client and zk.
| |
| − | |-
| |
| − | | 5.0.5
| |
| − | | October, 2010
| |
| − | | The shortcut was introduced to make it easy to specify a component set, such as zul and zhtml.
| |
| − | |}
| |
| − |
| |
| | {{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.