Potix Component Library

The iDOM representation of XML DOM tree.

Overview

It is Potix's DOM representation for XML. The concept is similar to JDOM -- using Java collections and concrete classes. However, we do have many enhancements (many of them are the reasons we don't extend JDOM, but writing a new one). Refer to Port from JDOM to iDOM for more details.

Although iDOM supports W3C/DOM, W3C/DOM's API is generated deprecated unless using them with third part utilities, like Xalan's XPath. The reason is that W3C/DOM API is another complete set of API that is easily confusing with iDOM API. The iDOM API is designed to avoid making any connection between their names. However, some cases are hardly avoided. For example, org.w3c.dom.Element.getAttribute returns an empty string if the attribute not found, while Element.getAttributeValue returns null if the attribute not found.

Usage

Generic Sample

Method 1: Let SAXBuilder create the SAX parser

import org.zkoss.idom.input.SAXBuilder;
import org.zkoss.idom.Document;

SAXBuilder builder = new SAXBuilder(true, false, true);
Document doc = builder.build("file.xml");

Advantages: simple. Caller needs no anything about a SAX parser.

Method 2: Create a parser explicitly

import javax.xml.parsers.SAXParser;
import javax.xml.parsers.SAXParserFactory;
import org.zkoss.idom.input.SAXBuilder;
import org.zkoss.idom.Document;

SAXParserFactory factory = SAXParserFactory.newInstance();
...//configure factory as you want
SAXParser parser = factory.newSAXParser();
SAXBuilder builder = new SAXBuilder(parser);
Document doc = builder.build("file.xml");

Advantages: a SAX parser could be used in different palces.

Parsing a XML

for (Iterator it = document.getElements("product").iterator();
it.hasNext();){
  String name = ((Element)it.next()).getElementValue("name", true);
  ...
}

The getElements and getElement methods of Group are powerful to drill down a iDOM tree sequentially.

To select beyond sequence searching (and regular expression), org.zkoss.xml.XPath could be used.

Extension to W3C DOM

• A new item/node is added, called Binary (Item.BINARY_NODE), to hold any kind of Object (not just String-type).

Notes

• Adding attributes with namespace might cause the tree to be illegal W3C/DOM. Examples, conflict prefix (same prefix but different URI). We will implement a method to check the consistency, which will be done before output.
• Every item has zero or one owning document. To be safe, only vertices without any owning document are allowed to be added to other tree. Otherwise, Item.detach or clone must be called explicitly.
• Some methods in Item look similar to those of Node, but behave differently as follows.

  Item	Node
  getText Returns the text content.	getNodeValue The same as getText, except Element whose getValue returns always null.

Histroy

Message for multi-language messages (locale-dependent).

MIL component set that are used for RMIL-based clients.

Table of Contents

• What is ZK Mobile?
• What is MIL?
• What is RMIL?
• Components of MIL in RMIL
  • frame
• Implicit Objects
  • How to browse components
• Events

What is ZK Mobile?

ZK Mobile is a JavaME program that runs as a thin client on mobile device. It interacts with the ZK server to display the RMIL page sent from ZK server and sent event triggered by the user back to server and so on.

What is MIL?

MIL is abbreviated from Mobile Interactive Language. It represents a set of components specifically for ZK Mobile thin client. A ZK Mobile to MIL is like a HTML browser to ZUL.

What is RMIL?

RMIL is abbreviated from Raw Mobile Interactive Language. It is a set of "low level" XML elements used to instruct ZK Mobile thin client how to "draw" a MIL page. A ZK Mobile to RMIL is like a HTML browser to HTML.

Components of MIL in RMIL

Introduction

Directive Elements

page

<?page [id="..."] [title="..."] [language="mil"]?>

• The language must be mil.
• The title is not used in MIL.
• The id is used for ID Space navigation.
• It must be at the same level as the root element.

Special Elements

zk

Due to XML's syntax limitation, we can only specify one document root. Thus, if you have multiple root components, you must use <zk> as the document root to group these root components. In other words, <zk> is not a component and it, if used, must be the document root.

zscript

<zscript>...</zscript>

<zscript src="/WEB-INF/xx/yy.bs">

• Specifies a script that shall be interpret when executing this page.
• If you want to pre-compile Java codes, you could do

  <zscript>
  import com.MyCompany.MyPackage.MyClass;
  MyClass.doThis();
  MyClass.doThat();
  .</zscript>

• Predefined variables:

  self

  The component itself

  self.parent

  The parent component, if any

  page

  The page (org.zkoss.zk.ui.Page)

  session

  The session (org.zkoss.zk.ui.Session)

  this

  The BeanShell namespace to interpret the script defined in this component. Advanced users only.

  super

  The BeanShell namespace to interpret the script defined in the parent component, if any. Advanced users only.

• If you specify the id attribute for a component, a variable the same as the specified ID is created automatically.
• If you want to resolve the EL's variables, such as a parameter, use page.resolveVariable(). Example: page.getELVariable('param').get('some')

Simple Elements

Common Attributes

<xxx [id="..."] [use="..."]/>

• If id is not specified, it is generated automatically. If specified, it must be unique in the whole page.
• The class attribute defines the CSS class that this component shall refer.
• The use attribute defines the Java class to use instead of the Java class defined in zk-xul-*.xml

textbox

<textbox [id="..."] [use="..."]
[onChange="script"] [onChanging="script"] [value="value"] [type="|password"]
[maxlength="0|num"] [readonly="false|true"] />

• The onChange attribute is called after the value is really set.
  • Note: the script of the onChange attribute is called only if user input a different value. On the other hand, the setValue method is called either by a program or by user's input (if by a program, the value might not be changed).
• The onChanging attribute is called when a user is chaning its content. onChanging won't cause the content being set. It is simply used to notify server for implementing auto-completion and other features.

frame

<frame [id="..."] [use="..."] [title="..."] [border="normal|none"]/>

• The title attribute defines the frame title.

Implicit Objects

Depending on invoking from a script or from an EL expression, different implicit objects might be used.

Name	Description	From Script	From EL
self	The current component that script/EL is interpreted upon. It is the same as this in Java.	Yes	Yes
spaceOwner	The owner of the ID space that the current component belongs to (See What is an ID space"). It is null, if the current component doesn't belong to any space. It is the same as self.getSpaceOwner() in script, self.root in EL and this.getSpaceOwner() in Java.	Yes	Yes
desktopScope	The attributes defined in the current desktop. It is the same as this.getPage().getAttributes(name,DESKTOP_SCOPE) in Java.	Yes	Yes
pageScope	The attributes defined in the current page. It is the same as this.getPage().getAttributes() in Java.	Yes	Yes
spaceScope	The attributes defined in the ID space that the current component belongs to (See What is an ID space"). It is the same as this.getAttributes() with SPACE_SCOPE in Java.	Yes	Yes
componentScope	The attributes defined in the current component. It is the same as this.getAttributes() with COMPONENT_SCOPE in Java.	Yes	Yes
arg	A map of parameters that are passed to Execution.createComponents(...). It is the same as desktop.getExecution().getArg() in Java.	Yes	Yes

How to browse components

In Java

Each frame forms an independent ID space. To get a component from an ID space, use Component.getFellow against any component in the same ID space. If a frame, say C, is a child of another frame, say P, then C belongs the ID space of P, but descendants of C don't. Rather, descendants of C belong to the ID space of C. Notice: C belongs to the ID spaces of both C and P.

A page is also an independent ID space, Page.getFellow is used to retrieve a fellow in it.

• To get the current page, use Component.getPage().
• To get another page (in the same desktop), use Component.getPage(String).
• To get a component of a page, use Page.getFellow(String) -- assuming the component is not a descendant of any frame..
• To get a child component of frame, use Window.getFellow(String).
• To get a fellow component, use Componnet.getFellow(String). All components belongs (aka., child or descendant of) to the same frame are called fellows. If a frame, say X, belongs to another frame, say Y, then X, like other type of components, is a fellow of Y. However, children and descendants of X are NOT fellow of Y because they belong to X's space. Only X belongs to both X's and Y's spaces.

In Script and EL

Components that are specified with the id attribute (i.e., you have assign an ID) can be accessed directly by the value of the id attribute.

For example,

<label id="label" value="Not good enough?"/>
<button label="Change label" onClick="label.value = label.value + 'A'"/>

Events

MIL Device

XEL Utilities that depends on Servlets.

XEL - Extensible Expression Language to encapsulate different implementations, such as EL, MVEL and OGNL.

This implementation is based on zcommons-EL. It includes ELFactory.

A collections of functions used in XEL expressions (for TLD only). They are accessible by declaring them in TLD files.

Utilities to access taglibs, aka., the TLD files.

Utilties of XEL expressions.

ZHTML component set.

Implementation Consideration

Currently, zhtml depends on zul, but it is not necessary. If we implement Fileupload and Messagebox in different way, such dependence could be removed. This might be important when we support XAML and user might want to minimize the foot print.

ZK core library.

Requests and responsed used to communicate between client and server, called asynchronous updates. Application developers rarely need to know them. Rather, use org.zkoss.zk.ui.util.Clients instead.

The commands of the requests of asynchronous updates (sent from client to server).

Note: commands in this package is not what an application developer handles. Rather, use the org.zkoss.zk.event package.

The responses of asynchronous updates (sent from server to client).

Note: they are the responses sent from the server to the client.

Device (such as Ajax browsers and mobile devices) relevant classes.

A collections of functions used in EL expressions (implementation only).

Scripting intepreter relevant classes, including interpreter, namespace and so on.

BeanShell - Java Interpreter.

Utilities for implementing interpters and namespaces.

Interfaces of the common user-interfaces, such as Page and Component.

Application developers usually need only classes defined in this package. For advance control, they might see also the org.zkoss.zk.ui.event and org.zkoss.zk.ui.util

Component developers might need also the org.zkoss.zk.ui.ext package.

All other packages are mostly used internally.

See Page for an overview.

For application developers they usually need only the org.zkoss.zk.ui package.

Additional Interfaces that might be implemented by the returned object of getExtraCtrl(). ZK Update Engine uses them to update the content of a component caused by user's activity at the client. In other words, it means a component's content is controlled by the client.

See getExtraCtrl for details

Application developers need NOT to access any of them.

Additional Interfaces that might be implemented by the returned object of getExtraCtrl(). ZK uses them to decide how to render a component specially.

See also getExtraCtrl

Application developers need NOT to access any of them.

HTTP relevant utilities and servlets for implementing user interfaces (implementation only).

Implementation of user interfaces and factories (implementation only).

Metainfo representing pages and languages (implementation only).

LanguageDefinition

ComponentDefinition

PageDefinition

PageDefinition represents a ZUML page. The XML nodes in the ZUML page are represented by ComponentInfo, AttributesInfo, VariablesInfo, InitiatorInfo

The implementation class of the metainfos.

The component render is a way to render a component in addition to the use of JSP, DSP, and other Servlet technologies.

Internal interfaces of user interfaces and factories (behind the scene). Most user interface, such as Component, has an internal interface, such as ComponentCtrl, used only by ZK internals. Application developers shall never use them.

Utilities to handle user interfaces.

ZK XEL utilities.

XEL utilities for implementation only.

The extension to ZK core and additional ZUL components. The extension includes the client-pooling-based server push. Additional components include layouts, JFreeChart-based chart engine, and others.

ZK UI related implementation, such as server push.

Zul Extension library.

Zul Extension library.

Versatile plugins such as Ruby, Groovy, JavaScript, MVEL, OGNL, and other plugins.

In addition, it provides the performance enhancement version of ZUL.

Groovy Interpreter

JRuby interpreter

Rhino - JavaScript Interpreter

org.zkoss.scripting.bsf.rhino.RhinoInterpreter

An implementation based on Rhino

org.zkoss.scripting.bsf.rhino.RhinoInterpreter

An implementation based on Rhino but went through BSF.

This implementation is based on Apache Commons EL, ApacheELFactory.

This implementation is based on JSP 2.1 EL. It includes ApacheELFactory.

A XEL implemetation based on MVEL.

A XEL implemetation based on OGNL.

Utilities to implement XEL factories.

Component renderers for rendering ZUL components.

The implementation of ZK Mobile JavaMe component factories (implementation only).

The ZK plus utilities, including data binding and integration of hibernate, acegi and so on.

Utilities to support Acegi Security System

The DataBinder used for binding ZK UI component and the backend data bean.

Utilities to support Hibernate.

Utilities to support JNDI

Utilities to support JPA

Utilities to support Seasar Framework.

Utilities to support Spring Application Framework.

Utilities that can be applied to several situations.

The ZK XML Component Set.

XML Device

ZUL component set that are used for HTML-based clients.

Table of Contents

• Components of XUL in HTML
  • window
• Implicit Objects
  • How to browse components
• Events

Components of XUL in HTML

Introduction

Directive Elements

page

<?page [id="..."] [title="..."] [language="xul/html"]?>

• The language must be xul/html.
• The title is used as the HTML page title. Used only if it is rendered as a standalone page (rather than included).
• The id, if specified, must be unique in the same request. Note: a request might contain multiple pages (such as a portal page).
• It must be at the same level as the root element.

Special Elements

zk

Due to XML's syntax limitation, we can only specify one document root. Thus, if you have multiple root components, you must use <zk> as the document root to group these root components. In other words, <zk> is not a component and it, if used, must be the document root.

zscript

<zscript>...</zscript>

<zscript src="/WEB-INF/xx/yy.bs">

• Specifies a script that shall be interpret when executing this page.
• If you want to pre-compile Java codes, you could do

  <zscript>
  import com.MyCompany.MyPackage.MyClass;
  MyClass.doThis();
  MyClass.doThat();
  .</zscript>

• Predefined variables:

  self

  The component itself

  self.parent

  The parent component, if any

  page

  The page (org.zkoss.zk.ui.Page)

  session

  The session (org.zkoss.zk.ui.Session)

  this

  The BeanShell namespace to interpret the script defined in this component. Advanced users only.

  super

  The BeanShell namespace to interpret the script defined in the parent component, if any. Advanced users only.

• If you specify the id attribute for a component, a variable the same as the specified ID is created automatically.
• If you want to resolve the EL's variables, such as a parameter, use page.resolveVariable(). Example: page.getELVariable('param').get('some')

Simple Elements

Common Attributes

<xxx [id="..."] [class="..."] [style="...] [use="..."]/>

• If id is not specified, it is generated automatically. If specified, it must be unique in the whole page.
• The class attribute defines the CSS class that this component shall refer.
• The use attribute defines the Java class to use instead of the Java class defined in zk-xul-*.xml

textbox

<textbox [id="..."] [class="..."] [style="...] [use="..."]
[onChange="script"] [onChanging="script"] [value="value"] [type="|password"]
[maxlength="0|num"] [rows="3|num"] [cols="0|num"]
[disabled="false|true"] [readonly="false|true"] [multiline="false|true"] />

• The onChange attribute is called after the value is really set.
  • Note: the script of the onChange attribute is called only if user input a different value. On the other hand, the setValue method is called either by a program or by user's input (if by a program, the value might not be changed).
• The onChanging attribute is called when a user is chaning its content. onChanging won't cause the content being set. It is simply used to notify server for implementing auto-completion and other features.

window

<window [id="..."] [class="..."] [style="...] [use="..."] [title="..."] [border="normal|none"]/>

• The title attribute defines the window title.

Implicit Objects

Depending on invoking from a script or from an EL expression, different implicit objects might be used.

Name	Description	From Script	From EL
self	The current component that script/EL is interpreted upon. It is the same as this in Java.	Yes	Yes
spaceOwner	The owner of the ID space that the current component belongs to (See What is an ID space"). It is null, if the current component doesn't belong to any space. It is the same as self.getSpaceOwner() in script, self.root in EL and this.getSpaceOwner() in Java.	Yes	Yes
desktopScope	The attributes defined in the current desktop. It is the same as this.getPage().getAttributes(name,DESKTOP_SCOPE) in Java.	Yes	Yes
pageScope	The attributes defined in the current page. It is the same as this.getPage().getAttributes() in Java.	Yes	Yes
spaceScope	The attributes defined in the ID space that the current component belongs to (See What is an ID space"). It is the same as this.getAttributes() with SPACE_SCOPE in Java.	Yes	Yes
componentScope	The attributes defined in the current component. It is the same as this.getAttributes() with COMPONENT_SCOPE in Java.	Yes	Yes
arg	A map of parameters that are passed to Execution.createComponents(...). It is the same as desktop.getExecution().getArg() in Java.	Yes	Yes

How to browse components

In Java

Each window forms an independent ID space. To get a component from an ID space, use Component.getFellow against any component in the same ID space. If a window, say C, is a child of another window, say P, then C belongs the ID space of P, but descendants of C don't. Rather, descendants of C belong to the ID space of C. Notice: C belongs to the ID spaces of both C and P.

A page is also an independent ID space, Page.getFellow is used to retrieve a fellow in it.

• To get the current page, use Component.getPage().
• To get another page (in the same desktop), use Component.getPage(String).
• To get a component of a page, use Page.getFellow(String) -- assuming the component is not a descendant of any window..
• To get a child component of window, use Window.getFellow(String).
• To get a fellow component, use Componnet.getFellow(String). All components belongs (aka., child or descendant of) to the same window are called fellows. If a window, say X, belongs to another window, say Y, then X, like other type of components, is a fellow of Y. However, children and descendants of X are NOT fellow of Y because they belong to X's space. Only X belongs to both X's and Y's spaces.

In Script and EL

Components that are specified with the id attribute (i.e., you have assign an ID) can be accessed directly by the value of the id attribute.

For example,

<label id="label" value="Not good enough?"/>
<button label="Change label" onClick="label.value = label.value + 'A'"/>

Events

onOK and onCancel

When window intercepts whether ENTER or ESC is pressed, the onOK or onCancel event is sent, resprectively.

onCtrlKey

Window intercepts whether control or function keys is pressed if you specify what to intercept by use of the ctrlKeys attribute. For example, If ctrlKeys="GW2" is specified, it means Ctrl+G, Ctrl+W and F2 are all intercepted. Once user press one of them, the onCtrlKey event is sent.

ZUL specific requests and commands of asynchronous updates.

ZUL specific responses of asynchornous updates.

Events of ZUL Component Set.

Interfaces that might be implemented by ZUL components.

A collections of functions used in EL expressions (implementation only).