Locating elements and widgets

ZK client-side architecture is based on HTML DOM nodes and JavaScript objects (ZK Widgets). The widget exists in the browser JavaScript context and is a client-side representation of a Server-side Java ZK component. Some client-side scenarios may require accessing the DOM node or the widget representing a specific UI entity. For example, when creating an automated test at the client-side, selecting the right DOM node is useful to check that the browser state is correct, and selecting a widget can be useful to read states or trigger workflows.

More technical information is available in the ZK client API.

jQuery selectors

The jQuery selectors can target one or multiple DOM elements using the selector syntax.

For example, the DOM element with the id="object1" attribute can be selected using the selector #object1. Using a similar syntax, a selector targeting every DOM holding the CSS class class1 is .class1.

These selectors are generally used in the jQuery shorthand selector function $("#object1") or $(".class1")

More information on default selection, check jQuery official documentation.

in an html file:

  <div id="div1"></div>
  <script>
    console.log("scroll position: " + $('#div1').scrollTop());
  </script>

ZK selectors and jQuery selection in a ZK page

The jq function

ZK client engine includes a customized version of jQuery, you can use it with window.jq() or jq() for short.

You can use jq() to select DOM elements in the same way as $() in standard jQuery.

For example, $("#object1") in standard jQuery is equivalent to jq("#object1") in a zul page. It will return a jQuery wrapper object matching the criteria id=”object1”

in a zul page:

    <div sclass="class1"><div>
    <script defer="true">
        console.log("scroll position: " + jq(".class1').scrollTop());
    </script>

The zk function

The zk function can be used with the same selector syntax as the jq function, but will select ZK widgets instead of selecting DOM nodes. ZK widgets are pure abstract JavaScript objects. Most of the time, they are tied to a DOM node, but an object can exist in memory while not attached to a page – for example, if they are set to render on-demand.

ZK widgets (client-side JavaScript objects) usually have an API closely resembling that of their matching ZK component (server-side Java objects). When accessing a ZK widget, getters and setters for most attributes are available, as well as triggers for some UI events (click, size, etc).

See the ZK client API for full API information.

The zk() function will return a zk selection object (which might refer to more than one target), but the most useful function is the zk.$(), which will return the first widget matching the selector criteria directly. This is especially useful when the criteria are expected to return only one result. For example, the zk.$('$object1') will return the widget associated with the server-side component declared with id=”object1”

In a zk page:

    <textbox id="tb"/>
    <script defer="true">
        console.log("client-side textbox value: " + zk.$("$tb").getValue());
    </script>

ZK specific selectors

In addition of the default selectors, ZK adds the following:

$ - ZK component Id selector

The $ selector will match ZK Server-side component IDs. This a custom selector provided by ZK. A component’s ID is not visible in a browser. Instead, a UUID (universal unique ID) is generated for each component’s DOM elements. These UUIDs are unique to among component instances and are visible in browsers as the id of the DOM nodes generated by a ZK component.

Using the $ selector, it is possible to retrieve a widget with the component id.

    <textbox id="tb"/>
    <script defer="true">
        console.log("client-side textbox value: "zk.$("$tb").getValue());
    </script>

@ - ZK component name selector

The @ selector will match ZK components names. For example, if a <textbox/> component is created in a zul page, js widgets matching this component can be selected using the @textbox selector.

    <textbox id="tb"/>
    <script defer="true">
    console.log("client-side textbox value: " + zk.$("@textbox").getValue());
    </script>

DOM node selector

The zk and jq functions can accept a DOM node as input. In this case, the zk() function will return the widget associated with the DOM node (if any), and the jq() function will return the jQuery object wrapping this DOM node.

In a zk page:

    <textbox id="tb"/>
    <script defer="true">
        var domNode = jq("$tb")[0];
        console.log("client-side textbox value: " + zk.$(domNode).getValue());
    </script>

Zk and jq interoperability

The zk() function can accept as parameter a jQuery object returned from the jq function, and will return the ZK widget associated with the jq selection.

The jq() function can accept a zk widget as parameter and will return the jQuery wrapper object for the main DOM node associated with the widget.

In a zk page:

    <textbox id="tb" sclass="class1"/>
    <script defer="true">
        var jqObject = jq("$tb");
        console.log("client-side textbox value: " + zk.$(jqObject).getValue());

        var zkWidget = zk.$("$tb");
        console.log(jq(zkWidget).hasClass("class1")? "class found" : "class not found");
    </script>

Zk widget DOM node selection

ZK widgets all possess a widget.$n(), which will return the main DOM node associated with the widget.

The widget.$n() can also accept a sub-node name as parameter. In this case, the function will return the sub-node holding the matching name if any. For example, listboxwidget.$n('body') will return the “body” subnode of the listbox widget. However, if called on a textbox widget (which doesn’t have a “body” subnode), the result would be empty.

In a zul page:

    <textbox id="tb" sclass="class1"/>
    <script defer="true">
        var zkWidget = zk.$("$tb");
        console.log("DOM node: " + zkWidget.$n());
    </script>