Client Attribute"

From Documentation
(24 intermediate revisions by 5 users not shown)
Line 10: Line 10:
 
<blockquote>
 
<blockquote>
 
----
 
----
Notice that if the widget's DOM output (<javadoc directory="jsdoc" method="redraw(_global_.Array)">zk.Widget</javadoc>) also has the same DOM attribute, both of them will be generated and it is technically not legal. Thus, you shall prevent the DOM attributes that widget might output.
+
Notice that if the widget's DOM output (<javadoc directory="jsdoc" method="redraw(_global_.Array)">zk.Widget</javadoc>) also has the same DOM attribute, both of them will be generated and it is technically not legal. Thus, you should prevent the DOM attributes that widget might output.
 
</blockquote>
 
</blockquote>
  
For example, suppose you want to listen to the <code>onload</code> event, and then you can do as follows<ref>For more information, please refer to [[ZK Component Reference/Essential Components/Iframe#onload|ZK Component Reference: iframe]].</ref>.
+
For example, suppose you want to listen to the <code>onload</code> event, you can do as follows<ref>For more information, please refer to [[ZK Component Reference/Essential Components/Iframe#onload|ZK Component Reference: iframe]].</ref>.
  
 
<source lang="xml">
 
<source lang="xml">
Line 32: Line 32:
 
</source>
 
</source>
  
'''data-swipeable'''
+
The other use of the client-attribute namespace is to specify attributes that are available only to certain browsers, such as accessibility and [http://www.section508.gov/index.cfm?FuseAction=Content&ID=12#Web Section 508].
  
  ZK EE only
 
Each layout region in borderlayout can support to close and open the region area by user's swipe on the edge of the region with client/attribute<ref>For more information, please refer to [[ZK Component Reference/Tablet Devices/UI Enhancements/Borderlayout#SwipeEvent_Support|ZK Component Reference Tablet Devices: Borderlayout]].</ref>.
 
  
<source lang="xml">
+
== Data-Attribute Handler ==
<borderlayout xmlns:ca="client/attribute" ca:data-swipeable="true">
+
Developer can define their own data-handler for the client attribute to have an extra functionality.
<!-- omitted -->
+
For example, (jQuery's mask)
</borderlayout>
 
</source>
 
  
 
+
'''Zul File:'''
Tabbox support to switch the tab by user swipe on the edge of content with client attribute<ref>For more information, please refer to [[ZK Component Reference/Tablet Devices/UI Enhancements/Tabbox#SwipeEvent_Support|ZK Component Reference Tablet Devices: Tabbox]].</ref>.
 
 
<source lang="xml">
 
<source lang="xml">
<tabbox xmlns:ca="client/attribute" ca:data-swipeable="true">
+
<textbox xmlns:ca="client/attribute" ca:data-mask="00:00:00" onChange='Clients.log(self.value)'/>
    <!-- omitted -->
 
</tabbox>
 
 
</source>
 
</source>
  
 
+
'''zk.xml:'''
Within Tree, Grid, and Listbox, Paging can support to navigate previous page or next page by user swipe on the edge of content with client attribute<ref>For more information, please refer to [[ZK Component Reference/Tablet Devices/UI Enhancements/Paging#SwipeEvent_Support|ZK Component Reference Tablet Devices: Paging]].</ref>.
 
 
<source lang="xml">
 
<source lang="xml">
<listbox mold="paging" pageSize="5" xmlns:ca="client/attribute" ca:data-swipeable="true"></listbox>
+
<client-config>
</source>
+
<data-handler>
 +
<name>mask</name><!-- the attribute name, i.e. data-mask -->
 +
<script src="http://igorescobar.github.io/jQuery-Mask-Plugin/js/jquery.mask.min.js" />
 +
<script>
 +
function (wgt, dataValue) {
 +
jq(wgt.$n()).mask(dataValue);
  
 
+
// unformat after onChange event.
Calendar can support to switch the view by user swipe on the content with client/attribute<ref>For more information, please refer to [[ZK Component Reference/Tablet Devices/UI Enhancements/Calendar#Friendly_Scrolling_Support|ZK Component Reference Tablet Devices: Calendar]].</ref>.
+
wgt.listen({onChange: function (event) {
<source lang="xml">
+
event.data.value = jq(this.$n()).cleanVal();
<calendar xmlns:ca="client/attribute" ca:data-swipeable="true" />
+
}});
 +
}
 +
</script>
 +
</data-handler>
 +
</client-config>
 
</source>
 
</source>
  
'''data-scrollable'''
+
=== Syntax Definition ===
 +
* '''&lt;data-handler>''': a group of a data-attribute handler <ref name="required">Required</ref> <ref name="multiple">One or Many</ref>
 +
** '''&lt;name>''': the attribute name. (i.e. data-name) <ref name="required"/>
 +
** '''&lt;override>''': true means the handler is used to override another existing one. <ref name="optional">Optional</ref>
 +
** '''&lt;link>''': the url for extra CSS files <ref name="multiple"/><ref name="optional"/>
 +
** '''&lt;script>''' the script content <ref name="required">Required</ref> <ref name="multiple">One or Many</ref>
 +
*** '''&lt;script src="foo.js">''' the src attribute for the script (Javascript library or data-handler script), it can be a url of a JS script from context-path or a url from class-path. For example, <pre><script-uri>~./myscript</script-uri></pre>
 +
*** Notice that the last <tt><script></tt> tag should be your data-handler script.
  
if user scroll container widget which applys the data-scrollable attribute, the errorbox should scroll with container widget<ref>
+
To see more examples, please refer to [http://blog.zkoss.org/index.php/2015/08/25/zk8-simple-but-powerful-using-data-handler-api-to-work-with-front-end-technologies/ ZK8: Simple but Powerful; Using Data-handler API to Work with Front-End Technologies] and [https://github.com/zkoss/zk8-datahandler Github] (you can design your own data-attribute handler and contribute this project).
For more information, please refer to http://www.zkoss.org/javadoc/7.0.1/jsdoc/zul/ContainerWidget.html</ref>.
 
<source lang="xml">
 
<window height="100px" contentStyle="overflow:auto" ca:data-scrollable="true">
 
</window>
 
</source>
 
  
When user swipe on the content of Listbox, Grid, Tree in tablet device, the friendly scrollbar will appear. To disable the friendly scrollbar, please use the following setting<ref>For more information, please refer to [[ZK Component Reference/Tablet Devices/UI Enhancements/Listbox#Friendly_Scrolling_Support|ZK Component Reference Tablet Devices: Listbox]], [[ZK Component Reference/Tablet Devices/UI Enhancements/Grid#Friendly_Scrolling_Support|ZK Component Reference Tablet Devices: Grid]], [[ZK Component Reference/Tablet Devices/UI Enhancements/Tree#Friendly_Scrolling_Support|ZK Component Reference Tablet Devices: Tree]].</ref>.
 
<source lang="xml">
 
<listbox xmlns:a="client/attribute" a:data-scrollable="false"/>
 
</source>
 
 
'''data-fixscrollposition'''
 
 
To prevent conflict with 'next' and 'previous' button on virtual keyboard on iPad.
 
Only make the modal window slide back by appling data-fixScrollPosition attribute on input element.
 
<source lang="xml">
 
<textbox xmlns:ca="client/attribute" ca:data-fixScrollPosition="true"></textbox>
 
</source>
 
 
The other use of the client-attribute namespace is to specify attributes that are available only to certain browsers, such as accessibility and [http://www.section508.gov/index.cfm?FuseAction=Content&ID=12#Web Section 508].
 
  
 
<blockquote>
 
<blockquote>
Line 91: Line 80:
 
<references/>
 
<references/>
 
</blockquote>
 
</blockquote>
 +
{{ZUMLReferenceHeadingToc}}
  
 
=Version History=
 
=Version History=
Line 100: Line 90:
 
| July 2010
 
| July 2010
 
| The client-attribute namespace was introduced.
 
| The client-attribute namespace was introduced.
 +
|-
 +
| 8.0.0
 +
| May 2015
 +
| [http://tracker.zkoss.org/browse/ZK-2730 Support client data attributes handler]
 
|}
 
|}
  
 
{{ZUMLReferencePageFooter}}
 
{{ZUMLReferencePageFooter}}

Revision as of 04:37, 18 February 2016


Client Attribute


Name: client attribute
Namespace: http://www.zkoss.org/2005/zk/client/attribute
Namespace shortcut: client/attribute
Java: LanguageDefinition.CLIENT_ATTRIBUTE_NAMESPACE

It is the reserved namespace for specifying client-side DOM attributes. Unlike the client namespace, which assigns something to widgets, the client/attribute namespace assigns additional DOM attributes to the DOM tree directly at the client.


Notice that if the widget's DOM output (Widget.redraw(Array)) also has the same DOM attribute, both of them will be generated and it is technically not legal. Thus, you should prevent the DOM attributes that widget might output.

For example, suppose you want to listen to the onload event, you can do as follows[1].

<iframe src="http://www.google.com" width="100%" height="300px"
  xmlns:ca="client/attribute"
  ca:onload="do_whater_you_want()"/>


If the attribute contains colon or other special characters, you can use the attribute element as follows.

<div xmlns:ca="client/attribute">
  <attribute ca:name="ns:whatever">
  whatever_value_you_want
  </attribute>
</div>

The other use of the client-attribute namespace is to specify attributes that are available only to certain browsers, such as accessibility and Section 508.


Data-Attribute Handler

Developer can define their own data-handler for the client attribute to have an extra functionality. For example, (jQuery's mask)

Zul File:

<textbox xmlns:ca="client/attribute" ca:data-mask="00:00:00" onChange='Clients.log(self.value)'/>

zk.xml:

<client-config>	
	<data-handler>
		<name>mask</name><!-- the attribute name, i.e. data-mask -->
		<script src="http://igorescobar.github.io/jQuery-Mask-Plugin/js/jquery.mask.min.js" />
		<script>
		function (wgt, dataValue) {
			jq(wgt.$n()).mask(dataValue);

			// unformat after onChange event.
			wgt.listen({onChange: function (event) {
				event.data.value = jq(this.$n()).cleanVal();
			}});
		}
		</script>
	</data-handler>
</client-config>

Syntax Definition

  • <data-handler>: a group of a data-attribute handler [2] [3]
    • <name>: the attribute name. (i.e. data-name) [2]
    • <override>: true means the handler is used to override another existing one. [4]
    • <link>: the url for extra CSS files [3][4]
    • <script> the script content [2] [3]
      • <script src="foo.js"> the src attribute for the script (Javascript library or data-handler script), it can be a url of a JS script from context-path or a url from class-path. For example,
        <script-uri>~./myscript</script-uri>
      • Notice that the last <script> tag should be your data-handler script.

To see more examples, please refer to ZK8: Simple but Powerful; Using Data-handler API to Work with Front-End Technologies and Github (you can design your own data-attribute handler and contribute this project).



  1. For more information, please refer to ZK Component Reference: iframe.
  2. 2.0 2.1 2.2 Required
  3. 3.0 3.1 3.2 One or Many
  4. 4.0 4.1 Optional


Version History

Last Update : 2016/02/18


Version Date Content
5.0.3 July 2010 The client-attribute namespace was introduced.
8.0.0 May 2015 Support client data attributes handler



Last Update : 2016/02/18

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