Scripts in ZUML"

From Documentation
m ((via JWB))
(48 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{ZKDevelopersReferencePageHeader}}
 
{{ZKDevelopersReferencePageHeader}}
  
= Write Java Code in ZUML =
+
=Embed Server-side Script Code=
For fast prototyping, you can embed codes in ZUML page. By default, it's Java and you could choose other languages, such as Groovy. Keep in mind, it's ''interpreted'' at run time (by [http://beanshell.org Beanshell]). Therefore you could define variables, methods, classes with it.
+
To make it easier to create a dynamic web page, the ZUML document allows you to embed the script code. Notice that there are two types of script code: server-side and client-side. How the client-side code can be embedded  is discussed at the [[ZK Developer's Reference/UI Composing/Client-side UI Composing|Client-side UI Composing]] and [[ZK Developer's Reference/Event Handling/Client-side Event Listening|Client-side Event Listening]] sections. Here we will discuss how to embed the server-side script code in a ZUML document.
 +
 
 +
Depending on the requirement, there are two ways to embed the server-side script code in a ZUML document: the <code>zscript</code> element and the event handler. The <code>zscript</code> element is used to embed the code that will execute when the page is loaded, while the event handler will execute when the event is received.
 +
 
 +
Notice that the performance of BeanShell is not good and, like any interpreter, typos can be found only when it is evaluated<ref>For more information, please refer to [[ZK Developer's Reference/Performance Tips/Use Compiled Java Codes|the Performance Tips section]]</ref>. However, embedding Java code in a ZUML page is a powerful tool for fast prototyping. For example, business analysis could discuss the ''real UI'' with UI designers, modify it directly and get back the feeling immediately without going through drawings and even recompiling.
  
 
<blockquote>
 
<blockquote>
 
----
 
----
Notice that the performance of BeanShell is not good and, like any interpreter, typos can be found only when it is evaluated. Thus, [[ZK Developer's Reference/Performance Tips/Use Compiled Java Codes|it is suggest to limit the use of zscript in prototyping and quick-fix]].
+
<references/>
 
</blockquote>
 
</blockquote>
  
There are two ways to write <tt>zscript</tt>. First, you could the zscript code inside the [[ZUML Reference/ZUML/Elements/zscript|zscript element]]:
+
==zscript==
 +
First, you could embed the code inside the [[ZUML Reference/ZUML/Elements/zscript|zscript element]], such that they will be evaluated when the page is rendered<ref>The zscript element has an attribute called [[ZUML Reference/ZUML/Elements/zscript#deferred|deferred]] that could make the evaluation as late as possible</ref>. For example,
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 27: Line 32:
 
</source>
 
</source>
  
Second, you could put the zscript code inside event handler such that it will execute when the event is received.
+
Notice that, by default, the code inside the <code>zscript</code> element is Java but you could also use other languages, such as Groovy. Keep in mind that it is ''interpreted'' at run time (by [http://beanshell.org Beanshell]), so typo or syntax error will be found only when it is interpreted. In addition, it runs at the server, so it could access any Java libraries. You could even define variables, methods, classes with it, and they are visible to EL expressions of the same page.
 +
 
 +
===CDATA===
 +
 
 +
The code embedded in the zscript element must be a valid XML text. In other words, you must encode the special characters well, such as  < must be replaced with &amp;lt;, & with &amp;amp; and so on. In additions to encode individual characters, you could also encode the whole code with XML CDATA as follows.
 +
 
 +
<source lang="xml">
 +
<script><![CDATA[
 +
if (some < another && another < last) //OK since CDATA is used
 +
  doSomething();
 +
]]></script>
 +
</source>
 +
 
 +
As depicted CDATA is represented with <code><![CDATA[</code> and <code>]]></code>.
 +
 
 +
<blockquote>
 +
----
 +
<references/>
 +
</blockquote>
 +
 
 +
===Class Declaration===
 +
 
 +
You could define a class declared in a ZUML document, and the class is accessible only in the page it was defined. For example,
 +
 
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<zk>
 +
<zscript><![CDATA[
 +
public class FooModel extends AbstractTreeModel {
 +
    public FooModel() {
 +
        super("Root");
 +
    }
 +
    public boolean isLeaf(Object node) {
 +
        return getLevel((String)node) >= 4; //at most 4 levels
 +
    }
 +
    public Object getChild(Object parent, int index) {
 +
        return parent + "." + index;
 +
    }
 +
    public int getChildCount(Object parent) {
 +
        return 5; //each node has 5 children
 +
    }
 +
    public int getIndexOfChild(Object parent, Object child) {
 +
        String data = (String)child;
 +
        int i = data.lastIndexOf('.');
 +
        return Integer.parseInt(data.substring(i + 1));
 +
    }
 +
    private int getLevel(String data) {
 +
        for (int i = -1, level = 0;; ++level)
 +
            if ((i = data.indexOf('.', i + 1)) < 0)
 +
                return level;
 +
    }
 +
};
 +
FooModel model = new FooModel();
 +
]]></zscript>
 +
<tree model="${model}">
 +
    <treecols>
 +
        <treecol label="Names"/>
 +
    </treecols>
 +
</tree>
 +
</zk>
 +
</source>
 +
 
 +
==Event Handlers==
 +
Second, you could put the code inside an event handler, such that it will execute when the event is received, as depicted below.
 
<source lang="xml" >
 
<source lang="xml" >
 
<button onClick='alert("event handler for onXXX inside ZUML is also zscript")'/>
 
<button onClick='alert("event handler for onXXX inside ZUML is also zscript")'/>
 
</source>
 
</source>
  
Notice that it is Java, interpreted at run time and running at the server. For client-side listening, please refer to the [[ZK Developer's Reference/Event Handling/Client-side Event Listening|Client-side Event Listening]] section.
+
Notice that the the name of the event must starts with <code>on</code>, and the third letter must be a '''upper''' case. Otherwise, it will be considered as a property.
 +
 
 +
Again, the code is Java interpreted at run time and running on the server. For client-side listening, please refer to the [[ZK Developer's Reference/Event Handling/Client-side Event Listening|Client-side Event Listening]] section.
 +
 
 +
For the sake of discussion, we call it zscript no matter the code is embedded in the <code>zscript</code> element or in an event handler.
 +
 
 +
===Attribute===
 +
 
 +
If the code is too complicate, you could specify the event handle in the [[ZUML Reference/ZUML/Elements/attribute|attribute element]]. For example,
 +
 
 +
<source lang="xml">
 +
<button label="hi">
 +
    <attribute name="onClick"><![DATA[
 +
    if (anything > best)
 +
        best = anything;
 +
    ]]></attribute>
 +
</button>
 +
</source>
  
=Distinguish <tt>zscript</tt> from EL=
+
=Distinguish <code>zscript</code> from EL=
Keep in mind, EL is enclosed by ${}.  
+
Keep in mind, [[ZK Developer's Reference/UI Composing/ZUML/EL Expressions|an EL expression]] is enclosed by ${ }.  
  
For example, <tt>${self.label}</tt> is EL:
+
For example, <code>${self.label}</code> and <code>${ok.label}</code> are both EL expressions in the following example:
 
<source lang="xml" >
 
<source lang="xml" >
 
<window>
 
<window>
Line 45: Line 130:
 
</source>
 
</source>
  
While <tt>alert(self.label)</tt> is not EL, it's a zscript code:
+
On the other hand, in the following example, <code>alert(self.label)</code> is not an EL expression. Rather, it's the zscript code:
 
<source lang="xml" >
 
<source lang="xml" >
 
<window>
 
<window>
Line 52: Line 137:
 
</source>
 
</source>
  
You cannot mix the use of EL with zscript:
+
You cannot mix the use of EL expressions with zscript:
 
<source lang="xml" >
 
<source lang="xml" >
 
<window>
 
<window>
Line 60: Line 145:
 
</source>
 
</source>
  
Also notice that the evaluation of EL expressions are very fast, while the execution of zscript code is slow. EL can be used in a production system, while [[ZK Developer's Reference/Performance Tips/Use Compiled Java Codes|zscript is suggested to use only in prototyping or quick-fix]].
+
Also notice that the evaluation of EL expressions is very fast, so EL can be used in a production system. On the other hand, [[ZK Developer's Reference/Performance Tips/Use Compiled Java Codes|zscript is suggested to use only in prototyping or quick-fix]].
 +
 
 +
==Variables Defined in zscript Visible to EL==
 +
 
 +
A variable defined in zscript is visible to EL expression, unless it is a local variable, which will be discussed later.
 +
 
 +
<source lang="xml">
 +
<script>
 +
Date now = new Date();
 +
</script>
 +
${now}
 +
</source>
  
 
= Java Interpreter =
 
= Java Interpreter =
 +
The default interpreter is based on [http://www.beanshell.org BeanShell]. It is a Java Interpreter.
 +
 
== Scope for Each ID Space ==
 
== Scope for Each ID Space ==
Java interpreter (BeanShell) is a ''multi-scope'' interpreter. It creates a scope for each ID space. Since ID space is hierarchical, so is the scopes. If a variable can't be found in current ID space, it will go further to parent's ID space try to resolve the variable.
+
The Java interpreter is a ''multi-scope'' interpreter. It creates a scope for each [[ZK Developer's Reference/UI Composing/Component-based UI#ID_Space|ID space]]. Since ID space is hierarchical, so is the scopes. If a variable cannot be found in the current ID space, it will go further to parent's ID space try to resolve the variable.
  
For example, in the following example, two logical scopes are created for window<ref>Built in id space owner includes <javadoc>org.zkoss.zul.Window</javadoc>, <javadoc type="interface">org.zkoss.zk.ui.Page</javadoc> and [[ZK Developer's Reference/UI Composing/Macro Component|macro components.</ref> <tt>A</tt> and <tt>B</tt>, respectively. Therefore, <tt>var2</tt> is visible only to window <tt>B</tt>, while <tt>var1</tt> is visible to both window <tt>A</tt> and <tt>B</tt>.
+
For example, in the following example, two logical scopes are created for window<ref>Built in id space owner includes <javadoc>org.zkoss.zul.Window</javadoc>, <javadoc type="interface">org.zkoss.zk.ui.Page</javadoc> and [[ZK Developer's Reference/UI Composing/Macro Component|macro components.</ref> <code>A</code> and <code>B</code> respectively. Therefore, <code>var2</code> is visible only to window <code>B</code>, while <code>var1</code> is visible to both window <code>A</code> and <code>B</code>.
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 82: Line 180:
 
</blockquote>
 
</blockquote>
  
== Declare Local Variable ==
+
== Declare a Local Variable ==
If a variable is declared inside a pair of the curly braces, it is visible to the scope defined by the curly braces. It is called a local variable. For example,
+
If a variable is declared inside a pair of the curly braces, it is visible only to the scope defined by the curly braces. It is called a local variable. For example,
  
 
<source lang="xml">
 
<source lang="xml">
Line 98: Line 196:
 
<window>
 
<window>
 
<zscript>
 
<zscript>
String first = "first";
 
 
{
 
{
    Date now = new Date();
+
    Date now = new Date(); //local variable
    abc ="def";
+
    abc ="def"; //global variable since not defined before and not Class specified
 
}
 
}
 +
String first = "first"; //global variable
 
</zscript>
 
</zscript>
 
0: ${first}
 
0: ${first}
Line 110: Line 208:
 
</source>
 
</source>
  
The result shows: <tt>0:first 1:def 2: </tt> . It is because <tt>now</tt> is local variable and invisible to EL expressions. On the other hand, <tt>first</tt> and <tt>abc</tt> are both global variables that are visible to EL expressions. Also notice that <tt>abc</tt> is not declared but assigned directly, and it causes a global variable to be created.
+
The result shows: <code>0:first 1:def 2:</code> . It is because <code>now</code> is the local variable and it is invisible to EL expressions. On the other hand, <code>first</code> and <code>abc</code> are both global variables that are visible to EL expressions. Notice that <code>abc</code> is not declared but assigned directly, and it causes a global variable to be created.
 +
 
 +
Please refer to the [http://beanshell.org/docs.html Beanshell Documentation] and search "scoping" and "local" for more information.
  
Please refer to [http://www.beanshell.org/manual/bshmanual.pdf Beanshell's manual] and search "scoping"、"local" for more information.
+
= Use Other Languages =
 +
Currently, zscript supports Java, Groovy, Ruby, JavaScript and Python. For example,
  
= zscript other than Java =
+
<source lang="xml">
Currently, zscript already support java, javascript, ruby, groovy. You can add other language to support zscript as you like. Please refer to section [[Zscript_other_than_java | Zscript other than java]] for more information.
+
<?page zscriptLanguage="Groovy"?>
 +
<window border="normal">
 +
<vbox id="vb">
 +
<label id="l" value="Hi"/>
 +
<button label="change label" onClick="l.value='Hi, Groovy';"/>
 +
<button label="add label" onClick="new Label('New').setParent(vb);"/>
 +
</vbox>
 +
<button label="alert" onClick="alert('Hi, Groovy')"/>
 +
</window>
 +
</source>
 +
 
 +
In addition, you could add your own interpreter by implementing <javadoc type="interface">org.zkoss.zk.scripting.Interpreter</javadoc>. For more information, please refer to [[ZUML Reference/Extensions/zscript|ZUML Reference]].
  
 
=Version History=
 
=Version History=
{{LastUpdated}}
+
 
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-

Revision as of 07:37, 8 July 2022

Embed Server-side Script Code

To make it easier to create a dynamic web page, the ZUML document allows you to embed the script code. Notice that there are two types of script code: server-side and client-side. How the client-side code can be embedded is discussed at the Client-side UI Composing and Client-side Event Listening sections. Here we will discuss how to embed the server-side script code in a ZUML document.

Depending on the requirement, there are two ways to embed the server-side script code in a ZUML document: the zscript element and the event handler. The zscript element is used to embed the code that will execute when the page is loaded, while the event handler will execute when the event is received.

Notice that the performance of BeanShell is not good and, like any interpreter, typos can be found only when it is evaluated[1]. However, embedding Java code in a ZUML page is a powerful tool for fast prototyping. For example, business analysis could discuss the real UI with UI designers, modify it directly and get back the feeling immediately without going through drawings and even recompiling.


  1. For more information, please refer to the Performance Tips section

zscript

First, you could embed the code inside the zscript element, such that they will be evaluated when the page is rendered[1]. For example,

<zscript>
//inside is zscript
//you can declare variable, function, and even Java class here.
void foo(String msg) {
    //...
}
comp.addEventListener("onClick",
    new EventListener() {
        public void onEvent(Event event) {
            //...
        }
    });
</zscript>

Notice that, by default, the code inside the zscript element is Java but you could also use other languages, such as Groovy. Keep in mind that it is interpreted at run time (by Beanshell), so typo or syntax error will be found only when it is interpreted. In addition, it runs at the server, so it could access any Java libraries. You could even define variables, methods, classes with it, and they are visible to EL expressions of the same page.

CDATA

The code embedded in the zscript element must be a valid XML text. In other words, you must encode the special characters well, such as < must be replaced with &lt;, & with &amp; and so on. In additions to encode individual characters, you could also encode the whole code with XML CDATA as follows.

<script><![CDATA[
if (some < another && another < last) //OK since CDATA is used
   doSomething();
]]></script>

As depicted CDATA is represented with <![CDATA[ and ]]>.


  1. The zscript element has an attribute called deferred that could make the evaluation as late as possible

Class Declaration

You could define a class declared in a ZUML document, and the class is accessible only in the page it was defined. For example,

<?xml version="1.0" encoding="UTF-8"?>
<zk>
<zscript><![CDATA[
public class FooModel extends AbstractTreeModel {
    public FooModel() {
        super("Root");
    }
    public boolean isLeaf(Object node) {
        return getLevel((String)node) >= 4; //at most 4 levels
    }
    public Object getChild(Object parent, int index) {
        return parent + "." + index;
    }
    public int getChildCount(Object parent) {
        return 5; //each node has 5 children
    }
    public int getIndexOfChild(Object parent, Object child) {
        String data = (String)child;
        int i = data.lastIndexOf('.');
        return Integer.parseInt(data.substring(i + 1));
    }
    private int getLevel(String data) {
        for (int i = -1, level = 0;; ++level)
            if ((i = data.indexOf('.', i + 1)) < 0)
                return level;
    }
};
FooModel model = new FooModel();
]]></zscript>
<tree model="${model}">
    <treecols>
        <treecol label="Names"/>
    </treecols>
</tree>
</zk>

Event Handlers

Second, you could put the code inside an event handler, such that it will execute when the event is received, as depicted below.

<button onClick='alert("event handler for onXXX inside ZUML is also zscript")'/>

Notice that the the name of the event must starts with on, and the third letter must be a upper case. Otherwise, it will be considered as a property.

Again, the code is Java interpreted at run time and running on the server. For client-side listening, please refer to the Client-side Event Listening section.

For the sake of discussion, we call it zscript no matter the code is embedded in the zscript element or in an event handler.

Attribute

If the code is too complicate, you could specify the event handle in the attribute element. For example,

<button label="hi">
    <attribute name="onClick"><![DATA[
    if (anything > best)
        best = anything;
    ]]></attribute>
</button>

Distinguish zscript from EL

Keep in mind, an EL expression is enclosed by ${ }.

For example, ${self.label} and ${ok.label} are both EL expressions in the following example:

<window>	
	<button label="ok" id="${self.label}"/>
	${ok.label}		
</window>

On the other hand, in the following example, alert(self.label) is not an EL expression. Rather, it's the zscript code:

<window>	
	<button label="ok" onClick='alert(self.label)'/>		
</window>

You cannot mix the use of EL expressions with zscript:

<window>	
	<!-- It's wrong, for java don't accept syntax as ${}-->
	<button label="ok" onClick='alert(${self.label})'/>		
</window>

Also notice that the evaluation of EL expressions is very fast, so EL can be used in a production system. On the other hand, zscript is suggested to use only in prototyping or quick-fix.

Variables Defined in zscript Visible to EL

A variable defined in zscript is visible to EL expression, unless it is a local variable, which will be discussed later.

<script>
Date now = new Date();
</script>
${now}

Java Interpreter

The default interpreter is based on BeanShell. It is a Java Interpreter.

Scope for Each ID Space

The Java interpreter is a multi-scope interpreter. It creates a scope for each ID space. Since ID space is hierarchical, so is the scopes. If a variable cannot be found in the current ID space, it will go further to parent's ID space try to resolve the variable.

For example, in the following example, two logical scopes are created for window[1] A and B respectively. Therefore, var2 is visible only to window B, while var1 is visible to both window A and B.

<window id="A">
    <zscript>var1 = "abc";</zscript>
    <window id="B">
        <zscript>var2 = "def";</zscript>
    </window>
</window>

  1. Built in id space owner includes Window, Page and [[ZK Developer's Reference/UI Composing/Macro Component|macro components.

Declare a Local Variable

If a variable is declared inside a pair of the curly braces, it is visible only to the scope defined by the curly braces. It is called a local variable. For example,

<zscript>
void echo() {
   String a_local_variable;
}
</script>

Here is another example,

<window>
	<zscript>
	{
	    Date now = new Date(); //local variable
	    abc ="def"; //global variable since not defined before and not Class specified
	}
	String first = "first"; //global variable
	</zscript>
	0: ${first}
	1:${abc}
	2:${now}
</window>

The result shows: 0:first 1:def 2: . It is because now is the local variable and it is invisible to EL expressions. On the other hand, first and abc are both global variables that are visible to EL expressions. Notice that abc is not declared but assigned directly, and it causes a global variable to be created.

Please refer to the Beanshell Documentation and search "scoping" and "local" for more information.

Use Other Languages

Currently, zscript supports Java, Groovy, Ruby, JavaScript and Python. For example,

<?page zscriptLanguage="Groovy"?>
<window border="normal">
	<vbox id="vb">
		<label id="l" value="Hi"/>
		<button label="change label" onClick="l.value='Hi, Groovy';"/>
		<button label="add label" onClick="new Label('New').setParent(vb);"/>
	</vbox>
	<button label="alert" onClick="alert('Hi, Groovy')"/>
</window>

In addition, you could add your own interpreter by implementing Interpreter. For more information, please refer to ZUML Reference.

Version History

Version Date Content
     



Last Update : 2022/07/08

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