ZK Developer's Guide/Fundamental ZK/ZK User Interface Markup Language/Component Sets and XML Namespaces

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.

Standard 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 Client namespace. It is used to specify the properties and listeners of a widget (at the client). <button w:onClick="do_at_client_in_JavaScript()" xmlns:w="http://www.zkoss.org/2005/zk/client"/> See also Client Side Programming ZK5: Client Computing with ZUML

http://www.zkoss.org/2005/zk/client/attribute [since 5.0.0] The Client-Attribute namespace. It is used to specify custom DOM attributes that will be generated directly to be part of the DOM tree. You can use it to listen DOM events such as onload, and to specify browser-specific attributes (such as accessibility-related attributes). <iframe ca:onload="do_something()" xmlns:ca="http://www.zkoss.org/2005/zk/client/attribute"/>

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.

Namespace Shortcuts

[since 5.0.4]

Each standard namespace has a shortcut to simplify the use in a ZUML file. For example, the shortcut of the Native namespace (http://www.zkoss.org/2005/zk/native) is native, and you can use as follows.

<n:html xmlns:n="native">
   <n:head>

Namespace Shortcuts

Namespace	Shortcut
http://www.potix.com/2005/zul	zul
http://www.w3.org/1999/xhtml	xhtml
http://www.zkoss.org/2005/zk	zk
http://www.zkoss.org/2005/zk/native	native
http://www.zkoss.org/2005/zk/client	client
http://www.zkoss.org/2005/zk/client/attribute	client/attribute
http://www.zkoss.org/2005/zk/annotation	annotation

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

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