The zscript Element

<zscript [language="Java"]>Scripting codes</zscript><zscript src="uri" [language="Java"]/>

It defines a piece of the scripting codes, say the Java codes, that will be interpreted when the page is evaluated. The language of the scripting codes is, by default, Java (see below). You can select a different language by use the language attribute.

The zscript element has two formats as shown above. The first format is used to embed the scripting codes directly in the page. The second format is used to reference an external file that contains the scripting codes.

Attribute Name

Description

src

[Optional][Default: none]

Specifies the URI of the file containing the scripting codes. If specified, the scripting codes will be loaded as if they are embedded directly.

The src attribute supports browser and locale dependent URI. In other words, you can specify ~ or * to denote different context path, browser and locale-dependent information. Refer to the Internationalization chapter for details.

Note: the file shall contain the source codes of the selected language that can be interpreted directly. The encoding must be UTF-8. Don't specify a class file (aka. byte codes).

language

[Optional][Default: Java or as specified in the page directive][Allowed Values: Java | JavaScript | Ruby | Groovy]

It specifies the scripting language in which the scripting codes are written.

deferred

[Optional][Default: false]

Whether to defer the evaluation of this element until the first non-deferred zscript codes of the same language need to be evaluated. Refer to the How to Defer the Evaluation section below.

if

[Optional][Default: true]

Specifies the condition to evaluate this element.

unless

[Optional][Default: false]

Specifies the condition not to evaluate this element.

How to Defer the Evaluation

ZK loads the interpreter before it is going to evaluate the first zscript codes. For example, the Java interpreter is loaded when the user clicks the button in the following example.

<button onClick="alert(&quot;Hi&quot;)"/>

On the other hand, the interpreter is loaded when loading the following ZUML page, since the zscript element needs to be evaluated when loading the page.

<window>
    <zscript>    
    void add() {    
    }    
    </zscript>    
    <button onClick="add()"/>    
</window>

If you prefer to defer the loading of the interpreter, you can specify the deferred option with true. Then, the interpreter won't be loaded, until the user clicks the button.

<window>
    <zscript deferred="true">    
    void add() {    
    }    
    </zscript>    
    <button onClick="add()"/>    
</window>

Note: The evaluation of EL expressions specified in the if, unless and src attributes are also deferred.

Note: If the component is detached from the page by the time the interpreter is loaded, the zscript codes are ignored. For example, if the window in the previous example no longer belongs to the page, the deferred zscript won't be interpreted.

How to Select a Different Scripting Language

A page could have scripts in multiple different scripting language.

<button onClick="javascript:do_something_in_js()"/>
<zscript language="groovy">
do_something_in_Groovy();
</zscript>

If the scripting language is omitted, Java is assumed. If you'd like to change the default scripting language, use the page directive as follows.

<?page zscriptLanguage="Groovy"?>

<zscript>
def name = "Hello World!";
</zscript>

How to Support More Scripting Languages

Currently ZK supports Java, JavaScript, Ruby and Groovy. However, it is easy to extend:

  1. Provides a class that implements the org.zkoss.zk.scripting.Interpreter interface. Instead of implementing it directly, you can derive from the org.zkoss.zk.scripting.util.GenericInterpreter class, if you'd like to handle namespaces directly. Or, you can derive from the org.zkoss.scripting.bsh.BSFInterpreter class, if the interpreter supports BSF (Bean Scripting Framework).

  2. Declares the scripting language in either WEB-INF/zk.xml, or zk/config.xml.

<zscript-config>
        <language-name>SuperJava</language-name><!-- case insensitive -->        

<interpreter-class>my.MySuperJavaInterpreter</interpreter-class>

</zscript-config>

Refer to the Developer's Reference for the details about WEB-INF/zk.xml. Refer to the Component Development Guide for the details about zk/config.xml.