The native Namespace"

From Documentation
(Created page with '{{ZKDevelopersReferencePageHeader}} =Overview= With the native namespace, a XML element in a ZUML document will be interpreted as a nat…')
 
m (remove empty version history (via JWB))
 
(25 intermediate revisions by 5 users not shown)
Line 2: Line 2:
  
 
=Overview=
 
=Overview=
With the [[ZUML Reference/ZUML/Namespaces/Native|native namespace]], a XML element in a ZUML document will be interpreted as a native tag that shall be sent to the browser directly, rather than becoming a ZK component.
+
With the [[ZUML Reference/ZUML/Namespaces/Native|native namespace]], an XML element in a ZUML document will be interpreted as a native tag that will be sent to the browser directly, rather than becoming a ZK component.
  
 
For example,
 
For example,
 
   
 
   
 
<source lang="xml" >
 
<source lang="xml" >
  <n:ul xmlns:n="http://www.zkoss.org/2005/zk/native">
+
  <n:ul xmlns:n="native">
 
     <n:li>
 
     <n:li>
 
     <textbox/>
 
     <textbox/>
Line 27: Line 27:
 
     <input id="z_a3_5"/>
 
     <input id="z_a3_5"/>
 
     </li>
 
     </li>
  </ul
+
  </ul>
 
</source>
 
</source>
 
   
 
   
where <tt><input></tt> is the HTML tag(s) generated by the <tt>textbox</tt> component. Unlike <tt>textbox</tt> in the example above, ZK Loader doesn't really create a component for each of <tt>ul</tt> and <tt>li</tt>.<ref>ZK ZK actually creates a special component to represent as many XML elements with the native namespace as possible.</ref> Rather, they are sent to the client directly. Of course, they must be recognizable by the client. For a HTML browser, they must be the valid HTML tags.
+
where <code><input></code> is the HTML tag(s) generated by the <code>textbox</code> component. Unlike <code>textbox</code> in the example above, ZK Loader doesn't really create a component for each of <code>ul</code> and <code>li</code>.<ref>ZK actually creates a special component to represent as many XML elements with the native namespace as possible.</ref> Rather, they are sent to the client directly. Of course, they must be recognizable by the client. For an HTML browser, they must be valid HTML tags.
  
Since the elements associated with the Native namespace are sent directly to the client, they are not ZK components, and they don't have the counterpart at the client. The advantage is the better performance in term of both memory and processing time. On the other hand, the disadvantage is you cannot access or change them dynamically. For example, the following code snippet is incorrect, since there is no component called <tt>x</tt>.
+
<blockquote>
 +
----
 +
<references/>
 +
</blockquote>
 +
 
 +
=Dynamic Update=
 +
 
 +
The XML elements associated with the native namespace will be considered as tags that the client accepts, and they are sent directly to the client to display. They are not ZK components, and they don't have the counterpart (widget) at the client either. The advantage is the better performance in terms of both memory and processing time.
 +
 
 +
However, the disadvantage that is you cannot access or change them (neither component nor widget) dynamically. For example, the following code snippet is incorrect, since there is no component called <code>x</code>.
  
 
<source lang="xml" >
 
<source lang="xml" >
  <n:ul id="x" xmlns:n="http://www.zkoss.org/2005/zk/native"/>
+
  <n:ul id="x" xmlns:n="native"/>
  <button label="add" onClick="new Li().setParent(x)"/>
+
  <button label="add" onClick="new Li().setParent(x)"/> <!-- Failed since x is not available at the server -->
 
</source>
 
</source>
 
   
 
   
If you want to change them dynamically, you can specify the XHTML namespace as described in the following section.
+
If you want to change them dynamically, you could:
 +
 
 +
#Use [[ZK Developer's Reference/UI Composing/Client-side UI Composing|client-side code]] to modify the browser's DOM tree at the client. Notice that, since ZK doesn't create the widget at the client too, you have to manipulate the DOM tree directly.
 +
#Use the [[ZK Developer's Reference/UI Patterns/HTML Tags/The html Component|html component]] if you won't mix ZUL with HTML tags.
 +
#Use [[ZK Developer's Reference/UI Patterns/HTML Tags/The XHTML Component Set|XHTML component set]] as described in the following section.
 +
 
 +
For example, we can modify the DOM tree with jQuery as follows:
 +
 
 +
<source lang="xml">
 +
<zk xmlns:n="native" xmlns:w="client">
 +
<n:input id="inp"/>
 +
<button label="change" w:onClick="jq('#inp')[0].value = 'clicked'"/>
 +
</zk>
 +
</source>
 +
 
 +
The rule of thumb is to use [[ZK Developer's Reference/UI Patterns/HTML Tags/The native Namespace|the native namespace]] if possible. If you need to change the content dynamically, you might consider [[ZK Developer's Reference/UI Patterns/HTML Tags/The html Component|the html component]] first. If still not applicable, use [[ZUML Reference/ZUML/Languages/XHTML|the XHTML component set]].
 +
 
 +
=Relation with Other Components=
 +
 
 +
Though no component is associated with the element specified with the native namespace, you still could manipulate its parent, such as invalidate and move. For example, the following works correctly.
 +
 
 +
<source lang="xml">
 +
<window border="normal" title="Redraw">
 +
  <n:ul xmlns:n="native">
 +
    <n:li>ZK is simply best</n:li>
 +
  </n:ul>
 +
  <button label="Redraw" onClick="self.getParent().invalidate()"/><!-- OK to invalidate a component -->
 +
</window>
 +
</source>
 +
 
 +
As shown, it is OK to invalidate a component even if it has some native tags.
 +
 
 +
Also notice that, though the native HTML tags will be generated for the native namespace, ZK Loader actually creates a component to represent as many as these native HTML tags. Thus, if you invoke <javadoc method="getPreviousSibling()">org.zkoss.zk.ui.Component</javadoc> of the button above, it will return this component. However, don't access it since the real class/implementation of the component depends on the version you use and might be changed in the future.
 +
 
 +
=In Pure Java=
 +
 
 +
You could use the native namespace in Java too. For example, you could create a native table directly as follows.
 +
 
 +
<source lang="java">
 +
import org.zkoss.zk.ui.Component;
 +
import org.zkoss.zk.ui.HtmlNativeComponent;
 +
import org.zkoss.zul.Datebox;
 +
 
 +
public class TableCreator {
 +
    public void createTable(Component parent) {
 +
        HtmlNativeComponent n =
 +
            new HtmlNativeComponent("table", "<tr><td>When:</td><td>", "</td></tr>");
 +
        n.setDynamicProperty("border", "1");
 +
        n.setDynamicProperty("width", "100%");
 +
        n.appendChild(new Datebox());
 +
        parent.appendChild(n);
 +
    }
 +
}
 +
</source>
 +
 
 +
As shown, the first argument of <javadoc method="HtmlNativeComponent(java.lang.String, java.lang.String, java.lang.String)">org.zkoss.zk.ui.HtmlNativeComponent</javadoc> is the name of tag. The second argument specifies the content that will be generated right before the children, if any. The third specifies the content after the children, if any. In addition, the setDynamicProperty method could be used to set the attributes of the tag.
 +
 
 +
In summary, the above example is equivalent to the following ZUML document:
  
'''Notes'''
+
<source lang="xml">
<references/>
+
<table border="1" width="100%" xmlns="native" xmlns:u="zul">
 +
    <tr>
 +
        <td>When:</td>
 +
        <td><u:datebox/></td>
 +
    </tr>
 +
</table>
 +
</source>
  
 +
= Output Tags with Another Namespace=
  
= Output Another Namespace with the Native Namespace =
+
If the HTML tag you want to output requires an XML namespace (such as XAML), you can use the following format to specify the URI of the XML namespace you want to output:
If you want to generate another namespace to the output, you can use another format as the URI of the Native namespace:
 
  
 
<source lang="xml" >
 
<source lang="xml" >
native:''URI-of-another-namespace''
+
<element xmlns="native:URI-of-another-namespace">
 
</source>
 
</source>
 
   
 
   
For example, if you want to output the XAML tags directly to the client, you can specify <nowiki>native:http://schemas.microsoft.com/client/2007</nowiki> as follows.
+
For example, if you want to output the XAML tags directly to the client, you can specify XAML's XML namespace as follows.
  
 
<source lang="xml" >
 
<source lang="xml" >
<zk>
+
<div>
 
<Canvas xmlns="native:http://schemas.microsoft.com/client/2007">
 
<Canvas xmlns="native:http://schemas.microsoft.com/client/2007">
 
  <TextBlock>Hello World!</TextBlock>
 
  <TextBlock>Hello World!</TextBlock>
 
</Canvas>
 
</Canvas>
</zk>
+
</div>
 
</source>
 
</source>
 
   
 
   
Then, the client will receive the following<ref>The real HTML output of window depends on its implementation. Here is only a simplified version.</ref>:
+
Then, the result DOM structure will be similar to the following<ref>The real DOM structure of a component (div in this example) depends on its implementation. Here is only a simplified version.</ref>:
  
 
<source lang="xml" >
 
<source lang="xml" >
<div z.au="/ZKTester/zkau" z.zidsp="page" style="width: 100%; height: 100%;" z.dtid="gk68" id="z_k6_0" class="zk">
+
<div id="zk_uuid">
 
     <canvas xmlns="http://schemas.microsoft.com/client/2007">
 
     <canvas xmlns="http://schemas.microsoft.com/client/2007">
 
           <textblock>Hello World!</textblock>
 
           <textblock>Hello World!</textblock>
Line 72: Line 144:
 
</source>
 
</source>
  
'''Notes'''
+
<blockquote>
 +
----
 
<references/>
 
<references/>
 +
</blockquote>
 +
  
=Version History=
 
Last Update : {{REVISIONYEAR}}/{{REVISIONMONTH}}/{{REVISIONDAY}}
 
{| border='1px' | width="100%"
 
! Version !! Date !! Content
 
|-
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
|}
 
  
 
{{ZKDevelopersReferencePageFooter}}
 
{{ZKDevelopersReferencePageFooter}}

Latest revision as of 05:54, 6 February 2024


The native Namespace


Overview

With the native namespace, an XML element in a ZUML document will be interpreted as a native tag that will be sent to the browser directly, rather than becoming a ZK component.

For example,

 <n:ul xmlns:n="native">
     <n:li>
     <textbox/>
     </n:li>
     <n:li>
     <textbox/>
     </n:li>
 </n:ul>

will attach the following HTML tags to the browser's DOM tree:

 <ul>
     <li>
     <input id="z_a3_2"/>
     </li>
     <li>
     <input id="z_a3_5"/>
     </li>
 </ul>

where <input> is the HTML tag(s) generated by the textbox component. Unlike textbox in the example above, ZK Loader doesn't really create a component for each of ul and li.[1] Rather, they are sent to the client directly. Of course, they must be recognizable by the client. For an HTML browser, they must be valid HTML tags.


  1. ZK actually creates a special component to represent as many XML elements with the native namespace as possible.

Dynamic Update

The XML elements associated with the native namespace will be considered as tags that the client accepts, and they are sent directly to the client to display. They are not ZK components, and they don't have the counterpart (widget) at the client either. The advantage is the better performance in terms of both memory and processing time.

However, the disadvantage that is you cannot access or change them (neither component nor widget) dynamically. For example, the following code snippet is incorrect, since there is no component called x.

 <n:ul id="x" xmlns:n="native"/>
 <button label="add" onClick="new Li().setParent(x)"/> <!-- Failed since x is not available at the server -->

If you want to change them dynamically, you could:

  1. Use client-side code to modify the browser's DOM tree at the client. Notice that, since ZK doesn't create the widget at the client too, you have to manipulate the DOM tree directly.
  2. Use the html component if you won't mix ZUL with HTML tags.
  3. Use XHTML component set as described in the following section.

For example, we can modify the DOM tree with jQuery as follows:

<zk xmlns:n="native" xmlns:w="client">
	<n:input id="inp"/>
	<button label="change" w:onClick="jq('#inp')[0].value = 'clicked'"/>
</zk>

The rule of thumb is to use the native namespace if possible. If you need to change the content dynamically, you might consider the html component first. If still not applicable, use the XHTML component set.

Relation with Other Components

Though no component is associated with the element specified with the native namespace, you still could manipulate its parent, such as invalidate and move. For example, the following works correctly.

<window border="normal" title="Redraw">
  <n:ul xmlns:n="native">
     <n:li>ZK is simply best</n:li>
  </n:ul>
  <button label="Redraw" onClick="self.getParent().invalidate()"/><!-- OK to invalidate a component -->
</window>

As shown, it is OK to invalidate a component even if it has some native tags.

Also notice that, though the native HTML tags will be generated for the native namespace, ZK Loader actually creates a component to represent as many as these native HTML tags. Thus, if you invoke Component.getPreviousSibling() of the button above, it will return this component. However, don't access it since the real class/implementation of the component depends on the version you use and might be changed in the future.

In Pure Java

You could use the native namespace in Java too. For example, you could create a native table directly as follows.

import org.zkoss.zk.ui.Component;
import org.zkoss.zk.ui.HtmlNativeComponent;
import org.zkoss.zul.Datebox;

public class TableCreator {
    public void createTable(Component parent) {
        HtmlNativeComponent n =
            new HtmlNativeComponent("table", "<tr><td>When:</td><td>", "</td></tr>");
        n.setDynamicProperty("border", "1");
        n.setDynamicProperty("width", "100%");
        n.appendChild(new Datebox());
        parent.appendChild(n);
    }
}

As shown, the first argument of HtmlNativeComponent.HtmlNativeComponent(String, String, String) is the name of tag. The second argument specifies the content that will be generated right before the children, if any. The third specifies the content after the children, if any. In addition, the setDynamicProperty method could be used to set the attributes of the tag.

In summary, the above example is equivalent to the following ZUML document:

<table border="1" width="100%" xmlns="native" xmlns:u="zul">
    <tr>
        <td>When:</td>
        <td><u:datebox/></td>
    </tr>
</table>

Output Tags with Another Namespace

If the HTML tag you want to output requires an XML namespace (such as XAML), you can use the following format to specify the URI of the XML namespace you want to output:

<element xmlns="native:URI-of-another-namespace">

For example, if you want to output the XAML tags directly to the client, you can specify XAML's XML namespace as follows.

<div>
	<Canvas xmlns="native:http://schemas.microsoft.com/client/2007">
	  <TextBlock>Hello World!</TextBlock>
	</Canvas>
</div>

Then, the result DOM structure will be similar to the following[1]:

<div id="zk_uuid">
     <canvas xmlns="http://schemas.microsoft.com/client/2007">
          <textblock>Hello World!</textblock>
     </canvas>
</div>

  1. The real DOM structure of a component (div in this example) depends on its implementation. Here is only a simplified version.




Last Update : 2024/02/06

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