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.

• PieModel : one series of data objects.

Non-XUL extension.

Non-XUL extension.

If you need better control, your renderer can also implement ComboitemRendererExt .

In addition, you could also implement RendererCtrl .

Default Datebox.getSclass : datebox.

The default format ( Datebox.getFormat ) depends on JVM's setting and the current user's locale.

An extension.

There are two ways to use Fileupload :

1.

Besides creating Row programmingly, you can assign a data model (a ListModel instance) to a grid via Grid.setModel and then the grid will retrieve data by calling ListModel.getElementAt when necessary.

Besides assign a list model, you could assign a renderer (a RowRenderer instance) to a grid, such that the grid will use this renderer to render the data returned by ListModel.getElementAt . If not assigned, the default renderer, which assumes a label per row, is used. In other words, the default renderer adds a label to a row by calling toString against the object returned by ListModel.getElementAt

There are two ways to handle long content: scrolling and paging. If Grid.getMold is "default", scrolling is used if Grid.setHeight is called and too much content to display. If Grid.getMold is "paging", paging is used if two or more pages are required.

Notice that Html generates HTML SPAN to enclose the embedded HTML tags.

Note: IE 5.5/6 (not 7) has a bug that failed to render PNG with alpha transparency.

There are two ways to use Imagemap:

1. Listen to the onClick event, which is an instance of org.zkoss.zk.ui.event.MouseEvent .

Event:

1. org.zkoss.zk.ui.event.SelectEvent is sent when user changes the selection.

See Specification.

Besides creating Listitem programmingly, you could assign a data model (a ListModel instance) to a listbox via Listbox.setModel and then the listbox will retrieve data via ListModel.getElementAt when necessary.

Besides assign a list model, you could assign a renderer (a ListitemRenderer instance) to a listbox, such that the listbox will use this renderer to render the data returned by ListModel.getElementAt . If not assigned, the default renderer, which assumes a label per list item, is used. In other words, the default renderer adds a label to a row by calling toString against the object returned by ListModel.getElementAt

There are two ways to handle long content: scrolling and paging. If Listbox.getMold is "default", scrolling is used if Listbox.setHeight is called and too much content to display. If Listbox.getMold is "paging", paging is used if two or more pages are required.

If you need better control, your renderer can also implement ListitemRendererExt .

In addition, you could also implement RendererCtrl .

This is the ListModel as an Object array to be used with Listbox .

This is the ListModel as a java.util.List to be used with Listbox .

This is the ListModel as a java.util.Map to be used with Listbox .

This is the ListModel as a java.util.Set to be used with Listbox .

You don't create Messagebox directly.

Radio buttons without a ancestor Radiogroup is considered as the same group. The nearest ancestor Radiogroup is the group that the radio belongs to.

Note: To support the versatile layout, a radio group accepts any kind of children, including Radio .

Though ListitemRenderer.render is called one item a timer, a request might have several items to render.

If you need better control, your renderer can also implement RowRendererExt .

In addition, you could also implement RendererCtrl .

Note: it is the scripting codes running at the client, not at the server.

Depending on the component (such as Intbox and Datebox , you could combine the flags, such as SimpleConstraint.NO_POSITIVE + SimpleConstraint.NO_ZERO to accept only negative number.

To customize the look, you can specify the style class with Slider.setSclass .

When the splitter is dragged, the sibling elements of the splitter are resized.

Default Timebox.getSclass : datebox.

timebox doens't support customized format.

The default CSS class is "button".

Non-xul extension: Toolbarbutton supports Toolbarbutton.getHref .

In XUL, treecell cannot have any child, but ZUL allows it. Thus, you could place any kind of children in it.

Unlike other elements, each Window is an independent ID space (by implementing IdSpace ). It means a window and all its descendants forms a ID space and the ID of each of them is unique in this space. You could retrieve any of them in this space by calling Window.getFellow .

If a window X is a descendant of another window Y, X's descendants are not visible in Y's space.