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

The implementation of XUL components for ZK.

## 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'"/>

The scope of visibility, same as in Java, is controlled by the ID space. In other words, each window has an independent ID space. When you specified an ID, only the current ID space is searched.

# 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.