Languages"

From Documentation
(35 intermediate revisions by 2 users not shown)
Line 4: Line 4:
 
A language (<javadoc>org.zkoss.zk.ui.metainfo.LanguageDefinition</javadoc>) is a collection of component definitions. It is also known as a component set.
 
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>.
+
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>. It is a ZK variant of XUL (and 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.
+
Component designers are free to designate a component definition to any component set they prefer, as long as there is no name conflict<ref>For more information please refer to [[ZK Component Development Essentials]]</ref>.
 +
 
 +
For introduction of languages vs standard namespaces, please refer to [[ZK Developer's Reference/UI Composing/ZUML/XML Namespaces|ZK Developer's References]].
 +
 
 +
=Language Identification=
 +
 
 +
When parsing a ZUML document, ZK Loader has 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 if <code>window</code> belongs to the xul/html language, so its component definition can be retrieved correctly.
 +
 
 +
<source lang="xml">
 +
<window>
 +
</source>
 +
 
 +
ZK Loader takes the following steps to decide the language an XML element is associated with:
 +
 
 +
#It assumes a default language for a ZUML document. The default language is decided by the filename's extension (see below).
 +
#If an XML element has no namespace prefix, then
 +
##Handle it specially, if the element is a special ZK element, such as [[ZUML Reference/ZUML/Elements/zk|zk]] and [[ZUML Reference/ZUML/Elements/attribute|attribute]].
 +
##Look up the component definition belonging to the default language, otherwise.
 +
#If an XML element has a prefix, then the XML namespace is used to resolve:
 +
##Handle it specially, if the XML namespace is one of the standard namespaces, such as [[ZUML Reference/ZUML/Namespaces/Native|native]] and [[ZUML Reference/ZUML/Namespaces/Client|client]].
 +
##Look up the language with the given XML namespace, otherwise
 +
##Then, look up the component definition from the language found in the previous step
 +
 
 +
==Filename Extension==
 +
 
 +
The default language is decided based on the extension of the filename (<javadoc method="getByExtension(java.lang.String)">org.zkoss.zk.ui.metainfo.LanguageDefinition</javadoc>). In addition, a language is associated with one or multiple extensions (defined by the component developer). For example, the extensions associated with the [[ZUML Reference/ZUML/Languages/ZUL|xul/html language]] are <code>zul</code> and <code>xul</code>, while the [[ZUML Reference/ZUML/Languages/XHTML|xhtml language]] (aka., a component set) is associated with the extensions including <code>zhtml</code>, <code>html</code>, <code>html</code>, and <code>xhtml</code>.
 +
 
 +
Thus, if a file or URI whose extension is <code>zul</code> or <code>xul</code>, the default language will be assumed to be the <code>xul/html</code> language.
 +
 
 +
===Filename Extension vs URL Mapping===
 +
 
 +
The association of extensions with a language is defined in a language. However, to really have ZK Loader to process a particular file, you have to configure <code>WEB-INF/web.xml</code> correctly. For example, if you want to map all <code>*.xul</code> 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>
 +
 
 +
If the extension of the mapped URL does not match any language, the xul/html language is assumed.
 +
 
 +
==XML Namespace==
 +
 
 +
In addition to extension association, a language is also associated with a unique XML namespace. Thus, you can identify the language for a given XML element by the use of XML namespace.
 +
 
 +
With the XML namespace, you could:
 +
 
 +
#Map a default language for a unknown extension
 +
#Mix two or more languages in one ZUML document
 +
 
 +
===Map a default language for a unknown extension===
 +
For example, you map ZK Loader to <code>*.foo</code>, which is not associated with any language. Then, you have to specify the XML namespace as shown in the following example:
 +
 
 +
<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. Furthermore, <code>http://www.zkoss.org/2005/zul</code> is the unique XML namespace associated with the xul/html namespace.
 +
 
 +
 
 +
===Mix two or more languages in a ZUML document===
 +
 
 +
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 <nowiki>http://www.w3.org/1999/xhtml</nowiki>, and we could mix the use as follows.
 +
 
 +
<source lang="xml" high="1">
 +
<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, when using the xhtml language, <code>table</code>, <code>tr</code> and <code>td</code> are also components though they are very simple -- a simple wrapper of HTML tags. However, there is a better way to generate HTML tags: the native namespace. It generates HTML tags directly without maintaining the component<ref>For more information please refer to the [[ZUML Reference/ZUML/Namespaces/Native|Native Namespace]] section</ref>. The associated XML namespace of the native namespace is <nowiki>http://www.zkoss.org/2005/zk/native</nowiki>, so we can rewrite the previous example to be more efficient:
 +
 
 +
 
 +
<source lang="xml" high="1">
 +
<window xmlns:h="http://www.zkoss.org/2005/zk/native">
 +
    <h:table>
 +
        <h:tr>
 +
            <h:td>
 +
                <button/>
 +
            </h:td>
 +
        </h:tr>
 +
    </h:table>
 +
</window>
 +
</source>
 +
 
 +
<blockquote>
 +
----
 +
<references/>
 +
</blockquote>
 +
 
 +
== 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:table>
 +
        <h:tr>
 +
            <h:td>
 +
                <button/>
 +
            </h:td>
 +
        </h:tr>
 +
    </h:table>
 +
</window>
 +
</source>
 +
 
 +
=Standard Languages=
 +
 
 +
ZK provides three different languages (aka., component sets): xul/xhtml, xhtml and xml. The xul/xhtml and xhtml langauges can be used for any modern browser (Ajax assumed), while the zml language is used for generating XML document (non-Ajax). The developers are free to add their own language<ref>Notice that there are so-called [[ZUML Reference/ZUML/Namespaces|Standard Namespaces]] associated with XML namespaces (for a ZUML document) to provide special functionality (than specify components).
 +
</ref>.
 +
 
 +
<blockquote>
 +
----
 +
<references/>
 +
</blockquote>
 +
 
 +
{| border='1px' | width="100%"
 +
! Language !! Description
 +
|-
 +
| xul/html
 +
|
 +
Name: xul/html (aka., zul)
 +
File Extensions: zul, xul
 +
Namespace: http://www.zkoss.org/2005/zul
 +
Namespace shortcut: zul
 +
Device: Ajax
 +
 
 +
XUL-compliant component sets. We adopt [https://developer.mozilla.org/En/XUL XUL] for this language, if the specification is applicable. For more information, please refer to [[ZK Component Reference]].
 +
 
 +
|-
 +
| xhtml
 +
|
 +
Name: xhtml
 +
File Extensions: zhtml, xhtml, html, htm
 +
Namespace: http://www.w3.org/1999/xhtml
 +
Namespace shortcut: xhtml
 +
Device: Ajax
 +
 
 +
XHTML-compliant component sets. It is one-to-one mapping of XHTML tags to ZK components. Since they are components, you can add and remove them dynamically (and control it at the server). For more information please refer to the [[ZUML Reference/ZUML/Languages/XHTML|XHTML Namespace]] section or [[ZK Component Reference/XHTML Components|ZK Component Reference]].
 +
 
 +
'''Performance Tip:''' The XHTML language is designed to allow application to modify the client dynamically (at the server). If you don't need it (it is generally true), you should use the [[ZUML Reference/ZUML/Namespaces/Native|Native namespace]] instead. For more information, please refer to [[ZK Developer's Reference/Performance Tips/Use Native Namespace instead of XHTML Namespace|Performance Tips]].
 +
 
 +
|-
 +
| xml
 +
|
 +
Name: xml
 +
File Extensions: xml
 +
Namespace: http://www.zkoss.org/2007/xml
 +
Namespace shortcut: xml
 +
Device: XML
 +
Available only ZK EE
 +
 
 +
XML component sets. It is used to generate (static) XML document. For more information please refer to the [[ZUML Reference/ZUML/Languages/XML|XML]] section.
 +
|}
  
 
{{ZUMLReferenceHeadingToc}}
 
{{ZUMLReferenceHeadingToc}}
 +
 +
<blockquote>
 +
----
 +
<references/>
 +
</blockquote>
  
 
=Version History=
 
=Version History=
Last Update : {{REVISIONYEAR}}/{{REVISIONMONTH}}/{{REVISIONDAY}}
+
{{LastUpdated}}
 
{| border='1px' | width="100%"
 
{| border='1px' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
| &nbsp;
+
| 5.0.4
| &nbsp;
+
| August, 2010
| &nbsp;
+
| 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.
 
|}
 
|}
  
 
{{ZUMLReferencePageFooter}}
 
{{ZUMLReferencePageFooter}}

Revision as of 02:47, 9 August 2011

Overview

A language (LanguageDefinition) is a collection of component definitions. It is also known as a component set.

For example, Window, Button and Combobox all belong to the same language called xul/html. It is a ZK variant of XUL (and also known as zul).

Component designers are free to designate a component definition to any component set they prefer, as long as there is no name conflict[1].

For introduction of languages vs standard namespaces, please refer to ZK Developer's References.

Language Identification

When parsing a ZUML document, ZK Loader has to decide the language that a XML element is associated, such that the correct component definition (ComponentDefinition) can be resolved. For example, in the following example, ZK needs to know if window belongs to the xul/html language, so its component definition can be retrieved correctly.

<window>

ZK Loader takes the following steps to decide the language an XML element is associated with:

  1. It assumes a default language for a ZUML document. The default language is decided by the filename's extension (see below).
  2. If an XML element has no namespace prefix, then
    1. Handle it specially, if the element is a special ZK element, such as zk and attribute.
    2. Look up the component definition belonging to the default language, otherwise.
  3. If an XML element has a prefix, then the XML namespace is used to resolve:
    1. Handle it specially, if the XML namespace is one of the standard namespaces, such as native and client.
    2. Look up the language with the given XML namespace, otherwise
    3. Then, look up the component definition from the language found in the previous step

Filename Extension

The default language is decided based on the extension of the filename (LanguageDefinition.getByExtension(String)). In addition, a language is associated with one or multiple extensions (defined by the component developer). For example, the extensions associated with the xul/html language are zul and xul, while the xhtml language (aka., a component set) is associated with the extensions including zhtml, html, html, and xhtml.

Thus, if a file or URI whose extension is zul or xul, the default language will be assumed to be the xul/html language.

Filename Extension vs URL Mapping

The association of extensions with a language is defined in a language. However, to really have ZK Loader to process a particular file, you have to configure WEB-INF/web.xml correctly. For example, if you want to map all *.xul files to ZK Loader, you could add the following to WEB-INF/web.xml:

<servlet-mapping>
	<servlet-name>zkLoader</servlet-name>
	<url-pattern>*.xul</url-pattern>
</servlet-mapping>

If the extension of the mapped URL does not match any language, the xul/html language is assumed.

XML Namespace

In addition to extension association, a language is also associated with a unique XML namespace. Thus, you can identify the language for a given XML element by the use of XML namespace.

With the XML namespace, you could:

  1. Map a default language for a unknown extension
  2. Mix two or more languages in one ZUML document

Map a default language for a unknown extension

For example, you map ZK Loader to *.foo, which is not associated with any language. Then, you have to specify the XML namespace as shown in the following example:

<window xmlns="http://www.zkoss.org/2005/zul">
...

where the xmlns attribute declares a XML namespace to associate all element without explicit prefix, such as window in this case. Furthermore, http://www.zkoss.org/2005/zul is the unique XML namespace associated with the xul/html namespace.


Mix two or more languages in a ZUML document

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 http://www.w3.org/1999/xhtml, and we could mix the use as follows.

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

Notice that, when using the xhtml language, table, tr and td are also components though they are very simple -- a simple wrapper of HTML tags. However, there is a better way to generate HTML tags: the native namespace. It generates HTML tags directly without maintaining the component[2]. The associated XML namespace of the native namespace is http://www.zkoss.org/2005/zk/native, so we can rewrite the previous example to be more efficient:


<window xmlns:h="http://www.zkoss.org/2005/zk/native">
    <h:table>
        <h:tr>
            <h:td>
                <button/>
            </h:td>
        </h:tr>
    </h:table>
</window>

  1. For more information please refer to ZK Component Development Essentials
  2. For more information please refer to the Native Namespace section

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, zul for http://www.zkoss.org/2005/zul, and xhtml for http://www.w3.org/1999/xhtml. Thus, we can simply the previous example as follows.

<window xmlns:h="xhtml">
    <h:table>
        <h:tr>
            <h:td>
                <button/>
            </h:td>
        </h:tr>
    </h:table>
</window>

Standard Languages

ZK provides three different languages (aka., component sets): xul/xhtml, xhtml and xml. The xul/xhtml and xhtml langauges can be used for any modern browser (Ajax assumed), while the zml language is used for generating XML document (non-Ajax). The developers are free to add their own language[1].


  1. Notice that there are so-called Standard Namespaces associated with XML namespaces (for a ZUML document) to provide special functionality (than specify components).
Language Description
xul/html
Name: xul/html (aka., zul)
File Extensions: zul, xul
Namespace: http://www.zkoss.org/2005/zul
Namespace shortcut: zul
Device: Ajax

XUL-compliant component sets. We adopt XUL for this language, if the specification is applicable. For more information, please refer to ZK Component Reference.

xhtml
Name: xhtml
File Extensions: zhtml, xhtml, html, htm
Namespace: http://www.w3.org/1999/xhtml
Namespace shortcut: xhtml
Device: Ajax

XHTML-compliant component sets. It is one-to-one mapping of XHTML tags to ZK components. Since they are components, you can add and remove them dynamically (and control it at the server). For more information please refer to the XHTML Namespace section or ZK Component Reference.

Performance Tip: The XHTML language is designed to allow application to modify the client dynamically (at the server). If you don't need it (it is generally true), you should use the Native namespace instead. For more information, please refer to Performance Tips.

xml
Name: xml
File Extensions: xml
Namespace: http://www.zkoss.org/2007/xml
Namespace shortcut: xml
Device: XML
Available only ZK EE

XML component sets. It is used to generate (static) XML document. For more information please refer to the XML section.


Subsections:



Version History

Last Update : 2011/08/09


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.



Last Update : 2011/08/09

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.