Package org.zkoss.zul

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

See:
Description

Interface Summary

CategoryModel	A catetory chart data model.
ChartModel	Chart Model is used to hold the data model for the chart.
ClientConstraint	Addition interface implemented with Constraint to denote how to validate at the client.
Constraint	A constraint.
CustomConstraint	Additional interface implemented with Constraint to denote a constraint supports a custom way to display the error message.
HiLoModel	A HiLo chart data model (date, open, close, high, low, volumn) usually used in stock market.
ListitemRenderer	Identifies components that can be used as "rubber stamps" to paint the cells in a Listbox.
ListitemRendererExt	Provides additional control to ListitemRenderer.
ListModel	This interface defines the methods that components like Listbox and Grid use to get the content of items.
ListModelExt	An extra interface that can be implemented with ListModel to control the sorting of the listbox.
PieModel	A Pie chart data model.
RendererCtrl	This interface defines the methods components like Listbox use to notify the renderer for several circumstance.
RowRenderer	Identifies components that can be used as "rubber stamps" to paint the cells in a Grid.
RowRendererExt	Provides additional control to RowRenderer.
XYModel	A XY chart data model.

Class Summary

AbstractChartModel	A skeletal implementation for ChartModel.
AbstractListModel	A skeletal implementation for ListModel.
Area	An area of a Imagemap.
Audio	An audio clip.
Bandbox	A band box.
Bandpopup	The popup that belongs to a Bandbox instance.
Box	A box.
Button	A button.
Calendar	A calendar.
Captcha	The generic captcha component.
Caption	A header for a Groupbox.
Chart	The generic chart component.
Checkbox	A checkbox.
Column	A single column in a Columns element.
Columns	Defines the columns of a grid.
Combobox	A combo box.
Comboitem	An item of a combo box.
Datebox	An edit box for holding a date.
Decimalbox	An edit box for holding BigDecimal.
Div	The same as HTML DIV tag.
Doublebox	An edit box for holding an float point value (double).
Filedownload	File download utilities.
Fileupload	A fileupload dialog used to let user upload a file.
Foot	Defines a set of footers (Footer) for a grid (Grid).
Footer	A column of the footer of a grid (Grid).
Grid	A grid is an element that contains both rows and columns elements.
Groupbox	Groups a set of child elements to have a visual effect.
Hbox	A hbox.
Html	A HTML embedder that embeds any HTML tags, even including JavaScript.
Iframe	Includes an inline frame.
Image	An image.
Imagemap	An image map.
Include	Includes the result generated by any servlet.
Intbox	An edit box for holding an integer.
Label	A label.
Listbox	A listbox.
Listcell	A list cell.
Listfoot	A row of Listfooter.
Listfooter	A column of the footer of a list box (Listbox).
Listhead	A list headers used to define multi-columns and/or headers.
Listheader	The list header which defines the attributes and header of a columen of a list box.
Listitem	A list item.
ListitemComparator	A comparator used to compare Listitem, if not live data, or the data themselves, if live data.
ListModelArray	This is the ListModel as an Object array to be used with Listbox.
ListModelList	This is the ListModel as a List to be used with Listbox.
ListModelMap	This is the ListModel as a Map to be used with Listbox.
ListModelSet	This is the ListModel as a Set to be used with Listbox.
Menu	An element, much like a button, that is placed on a menu bar.
Menubar	A container that usually contains menu elements.
Menuitem	sA single choice in a Menupopup element.
Menupopup	A container used to display menus.
Menuseparator	Used to create a separator between menu items.
Messagebox	Represents the message box.
Paging	Paging of long content.
Popup	A container that is displayed as a popup.
Progressmeter	A progress meter is a bar that indicates how much of a task has been completed.
Radio	A radio button.
Radiogroup	A radio group.
Row	A single row in a Rows element.
Rows	Defines the rows of a grid.
Script	A component to represent script codes running at the client.
Separator	A separator.
SimpleCategoryModel	A Category data model implementation of CategoryModel.
SimpleConstraint	A simple constraint that you could build based the predefined constants.
SimpleHiLoModel	A HiLo data model implementation of HiLoModel.
SimpleListModel	A simple implementation of ListModel.
SimplePieModel	A Pie chart data model implementation of PieModel.
SimpleXYModel	A XY data model implementation of XYModel.
Slider	A slider.
Space	Space is a Separator with the orient default to "horizontal".
Splitter	An element which should appear before or after an element inside a box (Box, Vbox and Hbox).
Style	The style component used to specify CSS styles for the owner desktop.
Tab	A tab.
Tabbox	A tabbox.
Tabpanel	A tab panel.
Tabpanels	A collection of tab panels.
Tabs	A collection of tabs (Tab).
Textbox	A textbox.
Timer	Fires one or more Event after a specified delay.
Toolbar	A toolbar.
Toolbarbutton	A tool button.
Tree	A container which can be used to hold a tabular or hierarchical set of rows of elements.
Treecell	A treecell.
Treechildren	A treechildren.
Treecol	A treecol.
Treecols	A treecols.
Treefoot	A row of Treefooter.
Treefooter	A column of the footer of a tree (Tree).
Treeitem	A treeitem.
Treerow	A treerow.
Vbox	A vbox.
Version	Specified this in lang.xml, such that ZK knows what lang.xml is associated with ZUL.
Window	A generic window.

Package org.zkoss.zul Description

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.