Package org.zkoss.zul

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

See: Description

Interface Summary

Interface	Description
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 handle the validation at the client.
ComboitemRenderer<T>	Identifies components that can be used as "rubber stamps" to paint the cells in a Combobox.
ComboitemRendererExt	Provides additional control to ComboitemRenderer.
Constraint	A constraint.
CustomConstraint	Additional interface implemented with Constraint to denote a constraint supports a custom way to display the error message.
GroupComparator<D>	A comparison function used to compare the group order of two objects, and the order of them in the group if they belongs to the same group.
GroupRendererExt	Provides additional control to RowRenderer for instantiating Group and Groupfoot.
GroupsModel<D,H,F>	The interface defines a suitable data model for grouping Listbox and Grid.
HiLoModel	A HiLo chart data model (date, open, close, high, low, volumn) usually used in stock market.
ItemRenderer<T>	Used to generated the HTML fragment for the data associated with a component, such as Selectbox.
ListgroupRendererExt	Provides additional control to ListitemRenderer for instantiating Listgroup and Listgroupfoot.
ListitemRenderer<T>	Identifies components that can be used as "rubber stamps" to paint the cells in a Listbox.
ListitemRendererExt	Provides additional control to ListitemRenderer.
ListModel<E>	This interface defines the methods that components like Listbox and Grid use to get the content of items.
ListSubModel<E>	An extra interface that can be implemented with ListModel to control the extract of the combobox.
PagingEventPublisher	Provide methods to manage PagingListeners
PieModel	A Pie chart data model.
RadioRenderer<T>	Identifies components that can be used as "rubber stamps" to paint the cells in a Radiogroup.
RendererCtrl	This interface defines the methods components like Listbox use to notify the renderer for several circumstance.
RowRenderer<T>	Identifies components that can be used as "rubber stamps" to paint the cells in a Grid.
RowRendererExt	Provides additional control to RowRenderer.
SingleValueCategoryModel	A Pie chart data model.
TabboxRenderer<T>	Identifies components that can be used as "rubber stamps" to paint the tab and tabpanel in a Tabbox.
TreeitemRenderer<T>	Identifies components that can be used as "rubber stamps" to paint the cells in a Tree.
TreeModel<E>	This interface defines the methods that component like Tree use to get the content of items.
TreeNode<E>	Defines the requirements for a tree node object that can change -- by adding or removing child nodes, or by changing the contents of an application-specific data (TreeNode.setData(E)) stored in the node.
XYModel	A XY chart data model.
XYZModel	A XYZ chart data model.

Class Summary

Class	Description
A	The same as HTML A tag.
Absolutechildren	A container component that can contain any other ZK component and can only be contained as direct child of Absolutelayout component.
Absolutelayout	An Absolutelayout component can contain absolute positioned multiple absolutechildren components.
AbstractChartModel	A skeletal implementation for ChartModel.
AbstractGroupsModel<D,H,F,E>	A skeletal implementation for GroupsModel.
AbstractGroupsModel.DefaultSelectionControl<E>	A default selection control implementation for AbstractGroupsModel, by default it assumes all elements are selectable.
AbstractListModel<E>	A skeletal implementation for ListModel and Selectable
AbstractListModel.DefaultSelectionControl<E>	A default selection control implementation for AbstractListModel, by default it assumes all elements are selectable.
AbstractTreeModel<E>	A skeletal implementation for TreeModel.
AbstractTreeModel.DefaultSelectionControl<E>	A default selection control implementation for AbstractTreeModel, by default it assumes all elements are selectable.
AbstractTreeModel.Path	Represents a tree path.
Anchorchildren	The children of Anchorlayout.
Anchorlayout	An anchorlayout lays out a container which can resize it's children base on its width and height Default Anchorlayout.getZclass(): z-anchorlayout.
Applet	A generic applet component.
Area	An area of a Imagemap.
ArrayComparator<E>	Compares the specified element of the array.
Attributes	Common attributes used for implementation.
Audio	An audio clip.
Auxhead	Used to define a collection of auxiliary headers (Auxheader).
Auxheader	An auxiliary header.
Bandbox	A band box.
Bandpopup	The popup that belongs to a Bandbox instance.
Borderlayout	A border layout is a layout container for arranging and resizing child components to fit in five regions: north, south, east, west, and center.
Box	A box.
Button	A button.
Calendar	A calendar.
Captcha	The generic captcha component.
Caption	A header for a Groupbox.
Cell	The generic cell component to be embedded into Row or Vbox or Hbox for fully control style and layout.
Center	A center region of a borderlayout.
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 combobox.
Combobutton	A combo button.
Comboitem	An item of a combo box.
Datebox	An edit box for holding a date.
Decimalbox	An edit box for holding BigDecimal.
DefaultTreeModel<E>	A simple tree data model that uses TreeNode to represent a tree.
DefaultTreeNode<E>	A general-purpose node in a tree data structure.
Detail	The detail component is used to display a detailed section where a master row and multiple detail rows are on the same row.
DialModel	A data model to be used with dial chart.
DialModelRange	Color range to be marked in DialModelScale.
DialModelScale	A set of information of a scale in a Dial chart.
Div	The same as HTML DIV tag.
Doublebox	An edit box for holding an float point value (double).
Doublespinner	An edit box for holding a constrained double.
East	An east region of a border layout.
FieldComparator	Based on the the given field names to compare the field value of the object that is passed in FieldComparator.compare(java.lang.Object, java.lang.Object) method.
Filedownload	File download utilities.
Fileupload	A fileupload dialog used to let user upload a file.
Flash	A generic flash component.
Foot	Defines a set of footers (Footer) for a grid (Grid).
Footer	A column of the footer of a grid (Grid).
Frozen	A frozen component to represent a frozen column or row in grid, like MS Excel.
GanttModel	A data model for Gantt chart.
GanttModel.GanttTask	A Task in an operation series; a helper class used in GanttModel.
Grid	A grid is an element that contains both rows and columns elements.
Group	Adds the ability for single level grouping to the Grid.
Groupbox	Groups a set of child elements to have a visual effect.
Groupfoot	Groupfoot serves as a summary row of group.
GroupsModelArray<D,H,F,E>	An array implementation of GroupsModel.
Hbox	A hbox.
Hlayout	A horizontal layout Default Hlayout.getZclass(): z-hlayout.
Html	A component used to embed the browser native content (i.e., HTML tags) into the output sent to the browser.
Idspace	Just like DIV tag but implements IdSpace.
Iframe	Includes an inline frame.
Image	An image.
Imagemap	An image map.
Include	Includes the result generated by any servlet, not limited to a ZUML page.
Intbox	An edit box for holding an integer.
Label	A label.
Layout	A layout.
LayoutRegion	A layout region in a border layout.
Listbox	A listbox.
Listcell	A list cell.
Listfoot	A row of Listfooter.
Listfooter	A column of the footer of a list box (Listbox).
Listgroup	Adds the ability for single level grouping to the Listbox.
Listgroupfoot	Listgroupfoot serves as a summary listitem of listgroup.
Listhead	A list headers used to define multi-columns and/or headers.
Listheader	The list header which defines the attributes and header of a column 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<E>	This is the ListModel as an Object array to be used with Listbox.
ListModelList<E>	This is the ListModel as a List to be used with Listbox.
ListModelMap<K,V>	This is the ListModel as a Map to be used with Listbox.
ListModels	A utility for handling ListModel.
ListModelSet<E>	This is the ListModel as a Set to be used with Listbox.
Longbox	An edit box for holding an integer.
Menu	An element, much like a button, that is placed on a menu bar.
Menubar	A container that usually contains menu elements.
Menuitem	A 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.
Messagebox.ClickEvent	The event that will be received by the listener when the user clicks a button.
North	A north region of a border layout.
Paging	Paging of long content.
Panel	Panel is a container that has specific functionality and structural components that make it the perfect building block for application-oriented user interfaces.
Panelchildren	Panelchildren is used for Panel component to manage each child who will be shown in the body of Panel.
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.
RowComparator	A comparator used to compare Row, if not live data, or the data themselves, if live data.
Rows	Defines the rows of a grid.
Script	A component to generate script codes that will be evaluated at the client.
Selectbox	A light weight dropdown list.
Separator	A separator.
SimpleCategoryModel	A Category data model implementation of CategoryModel.
SimpleConstraint	The default constraint supporting no empty, regular expressions and so on.
SimpleDateConstraint	A simple date constraint.
SimpleDoubleSpinnerConstraint	A simple double spinner constraint.
SimpleGroupsModel<D,H,F,E>	A simple implementation of GroupsModel.
SimpleHiLoModel	A HiLo data model implementation of HiLoModel.
SimpleListModel<E>	A simple implementation of ListModel.
SimplePieModel	A Pie chart data model implementation of PieModel.
SimpleSingleValueCategoryModel	A Pie chart data model implementation of SingleValueCategoryModel.
SimpleSpinnerConstraint	A simple spinner constraint.
SimpleXYModel	A XY data model implementation of XYModel.
SimpleXYModel.XYPair
SimpleXYZModel	A XYZ data model implementation of XYZModel.
Slider	A slider.
South	A south region of a border layout.
Space	Space is a Separator with the orient default to "vertical".
Span	The same as HTML SPAN tag.
Spinner	An edit box for holding a constrained integer.
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.
Timebox	An input box for holding a time (a java.util.Date Object , but only Hour & Minute are used.
Timer	Fires one or more Event after a specified delay.
Toolbar	A toolbar.
Toolbarbutton	A toolbar 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.
TreeitemComparator	A comparator used to compare Treeitem, if not live data, or the data themselves, if live data.
Treerow	A treerow.
Vbox	A vbox.
Version	The version of the ZK XUL component set.
Vlayout	A vertical layout Default Vlayout.getZclass(): z-vlayout.
WaferMapModel	A semiconductor wafer map data model to be used with wafermap chart.
WaferMapModel.IntPair
West	A west region of a border layout.
Window	A window.

Enum Summary

Enum	Description
Messagebox.Button	The button types.
Window.Mode	The window's mode used with Window.setMode(Mode).

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.