ZUML Reference/ZUML/Namespaces/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.

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

Binding to client attribute from MVVM view model

Client-attributes are added to the rendering information of components, and must be follow the same rules as the special attributes.

The client attribute must be initialized using the `${value}` syntax, and doesn't support `@init`, `@load` or `@bind`.

<!-- "forEach" versus children binding  -->
<div xmlns:ca="client/attribute">
    <!-- correct use for non-dynamic attribute values -->
    <checkbox ca:attribute="${vm.value}" />
    <!-- binding a referenced value or dynamic value by recreating content after triggering a binding using shadow element apply -->
    <apply refvalue="@load(vm.value)">
        <!-- apply content is recreated when the binding expression "vm.value" is notified -->
        <!-- using ${value} is correct, since expression is re-evaluated once the apply content is recreated -->
        <checkbox ca:attribute="${refvalue}" />
    </apply>
</div>

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
  • <name>: the attribute name. (i.e. data-name)
  • <override>: true means the handler is used to override another existing one.
  • <link>: the url for extra CSS files
  • <script> the script content
    • <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).

---

Version History

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