When you need to customize the client-side behavior, apply a js patch, or include a 3rd-party js library, you have to include the js file in your application. This section describes how you can include the js file for different scopes.

It is recommended to take a look at the Object-Oriented Programming in JavaScript , if you are not familiar with how ZK extends JavaScript to support the concept of packages and classes.

Page-Scope

To include a JavaScript file for a single page, you can use either the script directive or the script component. This is useful for page-specific logic.

Embed JavaScript Code Directly

Use the script directive to embed the code directly.

<!-- foo.zul -->
<?script type="text/javascript" content="jq.IE6_ALPHAFIX='.png';"?>

Alternatively, you could use the script component to embed the code.

Reference a Separate JavaScript File

If there are a lot of JavaScript code, it is better to package them in a separate file, and then use the script directive to reference the file in every ZUML page.

<!-- foo.zul -->
<?script type="text/javascript" src="/myjs/foo.js"?>

The script component can also be used to reference an external file.

Application-Scope

If you need to include a JavaScript file on every ZUL page in your application, there are several ways.

By Language Addon

You can create a lang-addon.xml to include the JavaScript file. ZK will load this addon for the whole application.

First, create a lang-addon.xml file, for example in WEB-INF/lang-addon.xml:

<language-addon>
    <addon-name>my-patch-addon</addon-name><!-- give a meaningful name -->
    <language-name>xul/html</language-name>
    <depends>zul</depends>
    <javascript src="~./mypatch.js" />
    <javascript src="/zkpatch/mypatch2.js"/>
</language-addon>
  • A path starting with ~./ is a classpath web resource path which is a special path supported by ZK to load resources from classpath.
  • You can also link a file under your web application context root e.g. /zkpatch/mypatch2.js.

Then, you must register this language addon in WEB-INF/zk.xml:

<language-config>
    <addon-uri>/WEB-INF/lang-addon.xml</addon-uri>
</language-config>

Dependent Addon

If you override a component’s widget or extend an existing component, it’s crucial to specify <depends> correctly, so that your lang addon will take effect. According to which component you override, you need to specify the corresponding addon name. For example:

  • If you override a component in zul language e.g. <button>, you specify 
    <depends>zul</depends>
  • If you override a component provided by zkmax e.g. <nav>, you specify 
    <depends>zkmax</depends>
  • If you override something about accessibility, e.g. override aria attribute, you specify 
    <depends>za11y</depends>

By zk.xml

A simpler way for application-scope is to use the <embed> element in zk.xml. This will embed a specified content inside the head element of every ZK page.

<zk>
    <embed><![CDATA[
        <script type="text/javascript" src="/js/my-global.js"></script>
    ]]></embed>
</zk>

Make It a WPD File for More Control

Technically, you could do whatever you want with a JavaScript file. However, if you prefer to make it a JavaScript package, such that they will be loaded automatically when required, you could package them as a WPD file. This gives you more control over packaging and on-demand loading.

For example, you could have a WPD file and make it loaded with the zk package (so it speeds up the loading).

<language-addon>
    <addon-name>my.extension</addon-name><!-- any name you like -->
    <javascript package="my.foo" merge="true"/> <!-- assume you call it my.foo -->
</language-addon>

This requires you to create a zk.wpd file for your my.foo package.