Component Sets and XML Namespaces"

Revision as of 10:15, 19 July 2010

This documentation is for an older version of ZK. For the latest one, please click here.

Overview

Namespaces and Component Sets is the fundamental for ZK to co-work with other UI framework.

To allow mix two or more component sets in the same ZUML page, ZK uses XML namespaces to distinguish different sets of components. For example, the namespace of XUL is http://www.zkoss.org/2005/zul, and that of XHTML is http://www.w3.org/1999/xhtml.

On the other hand, most pages uses only one component set. To make such pages easier to write, ZK determines the default namespace based on the extension. For example, the xul and zul extensions imply the XUL namespace. Therefore, developers need only to associate ZUML pages with a proper extension, and then don't need to worry about XML namespace any more.

Standard Namespaces

As stated before, each set of components is associated with an unique namespace. However, developers might develop or use additional components from 3^rd party, so here we list only the namespaces that are shipped with the ZK distribution.

Namespaces
`http://www.potix.com/2005/zul` The namespace of the XUL component set.
`http://www.w3.org/1999/xhtml` The namespace of the XHTML component set.
`http://www.zkoss.org/2005/zk` The ZK namespace. It is the reserved namespace for specifying ZK specific elements and attributes.
`http://www.zkoss.org/2005/zk/native` The Native namespace. It is the reserved namespace for specifying inline elements. Refer to the Work with HTML Tags section for details.
`native:URI-of-another-namespace` Alternative way to specify the Native namespace. With the Native namespace, a XML element in a ZUML page denotes that it shall be sent to the browser directly rather than becoming a ZK component Refer to the Work with HTML Tags section for details.
`http://www.zkoss.org/2005/zk/client` [since 5.0.0] The namespace for ZK client-side widgets. It is used to specify the properties and listeners of a widget (at the client). See also Client Side Programming ZK5: Client Computing with ZUML
`http://www.zkoss.org/2005/zk/annotation` The Annotation namespace. It is the reserved namespace for specifying the annotations. However, you rarely need to use this namespace directly. Rather, use `@{whatever_annotation}` instead. Refer to the Annotations section for details

It is optional to specify namespaces in ZUML pages, until there are conflicts. ZK determined which namespace to use by examining the extension of a ZUML page. For the .zul and .xul extensions, the namespace of XUL is assumed. For html, xhtml and zhtml, the namespace of XHTML is assumed.

Mix With Another Markup Language

To mix with another markup language, you have to use xmlns to specify the correct namespace.

 <window xmlns:h="http://www.w3.org/1999/xhtml">
     <h:div>
         <button/>
     </h:div>
 </window>

For the XHTML components, the onClick and onChange attributes are conflicts with ZK's attributes. To resolve, you have to use the reserved namespace, http://www.zkoss.org/2005/zk, as follows.

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:x="[http://www.potix.com/2005/zul http://www.zkoss.org/2005/zul]"
      xmlns:zk="http://www.zkoss.org/2005/zk">
	<head>
		<title>ZHTML Demo</title>
	</head>
	<body>
		<script type="text/javascript">
		function woo() { //running at the browser
		}
		</script>
		<zk:zscript>
		void addItem() { //running at the server
		}
		</zk:zscript>
		<x:window title="HTML App">
			<input type="button" value="Add Item"
			onClick="woo()" zk:onClick="addItem()"/>
		</x:window>
	</body>
</html>

xmlns="http://www.w3.org/1999/xhtml" specifies a namespace called http://www.w3.org/1999/xhtml, and use it as the default namespace.
<html> specifies an element called html from the default namespace, i.e., http://www.w3.org/1999/xhtml in this example.
xmlns:x="http://www.zkoss.org/2005/zul" specifies a namespace called http://www.zkoss.org/2005/zul, and use x to represent this namespace.
<x:window/> specifies an element called window from the name space called http://www.zkoss.org/2005/zul.

In this example, the onClick attribute is a ZHTML's attribute to specify JavaScript codes to run at the browser. On the other hand, the zk:onClick is a reserved attribute for specify a ZK event handler.

Notice that the namespace prefix, zk, is optional for the zscript element, because ZHTML has no such element and ZK has enough information to determine it.

Also notice that you have to specify the XML namespace for the window component, because it is from a different component set.

Auto-completion with Schema

Many IDEs, such Eclipse, supports auto-completion if XML schema is specified as follows.

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

In addition to downloading from http://www.zkoss.org/2005/zul/zul.xsd, you can find zul.xsd under the dist/xsd directory in the ZK binary distribution.

Quiz

When will we have to care about namespace and different component sets?
What namespaces are defined by ZKoss?
Which namespace is implied by xul and zul extensions?

Last Update : 2010/07/19

@@ Line 17: / Line 17: @@
 |-
-|  [http://www.potix.com/2005/zul http://www.zkoss.org/2005/zul]
+|  <tt><nowiki>http://www.potix.com/2005/zul</nowiki></tt>
 The namespace of the XUL component set.
 |-
-|  http://www.w3.org/1999/xhtml
+|  <tt><nowiki>http://www.w3.org/1999/xhtml</nowiki></tt>
 The namespace of the XHTML component set.
 |-
-|  http://www.zkoss.org/2005/zk
+|  <tt><nowiki>http://www.zkoss.org/2005/zk</nowiki></tt>
 The ZK namespace. It is the reserved namespace for specifying ZK specific elements and attributes.
 |-
-|  http://www.zkoss.org/2005/zk/native
+|  <tt><nowiki>http://www.zkoss.org/2005/zk/native</nowiki></tt>
 The Native namespace. It is the reserved namespace for specifying inline elements.
@@ Line 39: / Line 39: @@
 |-
-|  http://www.zkoss.org/2005/zk/annotation
+|  <tt>native:''URI-of-another-namespace''</tt>
-The Annotation namespace. It is the reserved namespace for specifying the annotations.
+Alternative way to specify the Native namespace. With the Native namespace, a XML element in a ZUML page denotes that it shall be sent to the browser directly rather than becoming a ZK component
+Refer to the [[Work_with_HTML_Tags | Work with HTML Tags]] section for details.
-Refer to the [[Annotations | Annotations]] section for details
 |-
-|  native:''URI-of-another-namespace''
+|  <tt><nowiki>http://www.zkoss.org/2005/zk/client</nowiki></tt>
-Alternative way to specify the Native namespace. With the Native namespace, a XML element in a ZUML page denotes that it shall be sent to the browser directly rather than becoming a ZK component
+ [since 5.0.0]
+The namespace for ZK client-side widgets. It is used to specify the properties and listeners of a widget (at the client).
+See also
+* [http://docs.zkoss.org/wiki/Client_Side_Programming Client Side Programming]
+* [http://docs.zkoss.org/wiki/ZK5:_Client_Computing_with_ZUML ZK5: Client Computing with ZUML]
+|-
+|  <tt><nowiki>http://www.zkoss.org/2005/zk/annotation</nowiki></tt>
-Refer to the [[Work_with_HTML_Tags | Work with HTML Tags]] section for details.
+The Annotation namespace. It is the reserved namespace for specifying the annotations.
+However,  you rarely need to use this namespace directly. Rather, use <tt>@{whatever_annotation}</tt> instead.
+Refer to the [[Annotations | Annotations]] section for details
 |}
 It is optional to specify namespaces in ZUML pages, until there are conflicts. ZK determined which namespace to use by examining the extension of a ZUML page. For the .<tt>zul</tt> and .<tt>xul</tt> extensions, the namespace of XUL is assumed. For <tt>html</tt>, <tt>xhtml</tt> and <tt>zhtml</tt>, the namespace of XHTML is assumed.

Anonymous

Component Sets and XML Namespaces"

Namespaces

More

Page actions