The Developer's Reference

<?component name="myName" macroURI="/mypath/my.zul" [prop1="value1"] [prop2="value2"]... ?>

You could define a new component based on a ZUML page. It is also called the macro component. In other words, once an instance of the new component is created, it creates child components based on the specified ZUML page (the macroURI attribute).

In addition, you could specify the initial properties (such as prop1 in the above example), such that they are always passed to the macro component (thru the arg variable).

The inline attribute specifies whether it is an inline macro (inlinie="true") or a regular macro (default).

An inline macro behaves like inline-expansion. ZK doesn't create a macro component if an inline macro is encountered. Rather, it inline-expands the components defined in the macro URI. In other words, it works as if you type the content of the inline macro directly to the target page.

On the other hand, ZK will create a real component (called a macro component) to represent the regular macro. That is, the macro component is created as the parent of the components that are defined in the macro.

<?component name="myName" [class="myPackage.myClass"] [extends="nameOfExistComponent"] [moldName="myMoldName"] [moldURI="/myMoldURI"] [prop1="value1"] [prop2="value2"]...?>

In addition to defining a component by a ZUML page (aka., a macro component), You could define a new component by implementing a class that implements the org.zkoss.zk.ui.Component interface. Then, use the by-class format to declare such kind of components for a page.

To define a new component, you have to specify at least the class attribute, which is used by ZK to instantiate a new instance of the component.

In addition to defining a new component, you can override properties of existent components by specifying the extends element with the component name that you want to extend from (extendee). In other words, if extends is specified, the previous definition of the extendee is loaded as the default value and then override only properties that are specified in this directive.

For example, assume you want to use MyWindow instead of the default window, org.zkoss.zul.html.Window, for all windows defined in this ZUML page. Then, you can declare it as follows.

<?component name="window" extends="window" class="MyWindow"?>
...
<window>
...
</window>

It is equivalent to the following codes.

<window use="MyWindow">
...
</window>

In addition, you could specify the properties to initialize. For example, you want to use the style class called blue for all buttons used in this page, then you could:

<?component name="button" extends="button" sclass="blue"?>

Similarly, you could use the following definition to use OK as the default label for all buttons specified in this page.

<?component name="button" extends="button" label="OK"?>

Notice that the properties won't be applied if a component is created manually (by zscript or by Java codes). If you still want them to be applied with the initialial properties, you could invoke the applyProperties method as follows.

<zscript>Button btn = new Button();btn.applyProperties(); //apply the initial properties</zscript>

[Optional]

Used to specify the class to instantiate an instance of such kind of components. Unlike other directives, the class can be defined with zscript.

[Optional]

Specifies the name of the component to extend from (extendee). If specified, the existent definition will be loaded to initialize the new component definition. In other words, it extends the existent definition instead of defining a brand-new one.

[Required if the by-macro format is used][EL is not allowed]

Used with the by-macro format to specify the URI of the ZUML page, which is used as the template to create components.

[Optional][Default: default]

Used with the by-class format to specify the mold name. If moldName is specified, moldURI must be specified, too.

[Optional][EL is allowed]

moldURI="~./zul/in-my-jar.dsp"moldURI="/WEB-INF/in-my-web.dsp"moldURI="/jsp-or-other-servlet"moldURI="class:com.mycompany.myrender"

Used with the by-class format to specify the mold URI. If moldURI is specified but moldName is not specified, the mold name is assumed as default.

In addition to DSP, JSP and any Servlet technologies, you can implement the org.zkoss.zk.util.ComponentRenderer interface, and then specify it in the moldURI attribute by starting with "class:". With this approach, the performance is the best.

[Required]

The component name. If an existent component is defined with the same name, the existent component is completely invisible in this page. If the by-class format is used, the attributes of the existent components are used to initialize the new components and then override with what are defined in this processing instruction.

[optional][Default: none][Case insensitive]

The name of the implementation used to evaluate the XEL expressions. There are two ways to specify the implementation. One is the name attribute. The other is the class attribute.

For example, if you want to use MVEL^[2], you can specify the name as follows.

<?evaluator name="mvel"?>
<window id="w" title="MVEL Demo">
    ${new org.zkoss.zul.Textbox().setParent(w)}    
</window>

Here are a list of built-in implementations.

You can provide additional implementations by use of the class attribute, as described in the following section. The class must implement the org.zkoss.xel.ExpressionFactory interface. Or, you can specify the following content in metainfo/xel/config.xml.

<config>
    <xel-config>    
        <evaluator-name>Super</evaluator-name><!-- case insensitive -->        
        <evaluator-class>my.SuperEvaluator</evaluator-class>        
    </xel-config>    
</config>

[Optional][Default: dependind on how xel-config is specified]

The implementation used to evaluate the XEL expressions. In addition to the name attribute, you can specify the class directly. For example, you can use MVEL by specifying class as follows.

<?evaluator class="org.zkoss.zkmax.xel.mvel.MVELFactory"?>
<window id="w" title="MVEL Demo">
    ${new org.zkoss.zul.Textbox().setParent(w)}    
</window>

[Optiona][Default: what are defined in taglib]

Specifies a list of classes separated with comma to import for evaluating the expression in this page. For example, with MVEL:

<?evaluator class="org.zkoss.zkmax.xel.mvel.MVELFactory"
import="org.zkoss.zul.Datebox,org.zkoss.zul.Combobox"?>
<window id="w" title="MVEL Demo">
    ${new Datebox().setParent(w)}    

</window>

Notice that not all evaluators support the import of classes. For example, all EL-based the evaluators, including the system default one, don't support it. In other words, the import attribute is meaningless to them. Rather, you have to use the taglib directive to import functions.

[required][EL expressions allowed]

The URI of the page/servlet to forward to. It may be another ZUML page, a JSP page or any servlet.

If an EL expression is specified and it is evaluated to an empty string, it is considered as no forwarding at all.

[Optional][Default: true][EL expressions allowed]

The condition to forward to the specified URI. If both if and unless are omitted, this page won't be evaluated and ZK always forwards the request to the specified URI.

[Optional][Default: false][EL expressions allowed]

The condition not to forward to the specified URI. If both if and unless are omitted, this page won't be evaluated and ZK always forwards the request to the specified URI.

[Required]

The URI of a ZUML page which the component definitions will be imported from.

[Optional]

If the directives attribute is omitted, only the component and init directives are imported. If you want to import particular directives, you can specify a list of the names of the directives separated by comma. For example,

<?import uri="/template/taglibs.zul" directives="taglib, xel-method"?>

The directives that can be imported include component, init, meta, taglib, variable-resolver, and xel-method. If you want to import them all, specify * to the directives attribute. Notice that meta implies both the meta and link directives.

[Optional]

A class name that must implement the org.zkoss.zk.ui.util.Initator interface. Unlike the init directive, the class name cannot be the class that is defined in zscript codes.

An instance of the specified class is constructed and its doInit method is called in the Page Initial phase (i.e., before the page is evaluated). The doFinally method is called after the page has been evaluated. The doCatch method is called if an exception occurs during the evaluation.

Thus, you could also use it for cleanup and error handling.

[Optional]

A script file that will be evaluated in the Page Initial phase.

[Optional]

You could specify any number of arguments. It will be passed to the doInit method if the first format is used, or as the args variable if the second format is used. Note: the first argument is arg0, the second is arg1 and follows.

[Optional][Default: false if Ajax devices, true if XML and MIL devices]

It specifies whether the client can cache the output.

Note: Browsers, such as Firefox and IE, don't handle the cache of DHTML correctly, so it is not safe to specify cacheable with true for Ajax devices.

[Optional][Default: false]

It specifies that this page is a complete page. By complete we mean the page has everything that the client expects. For example, if the client is a HTML browser, then a complete page will generate all necessary HTML tags, such as <html>, <head> and <body>.

By default (false), a ZK page is assumed to be complete if and only if it is not included by other page. In other words, if a ZK page is included by other page, ZK will generate <div> (if the client is a HTML browser) to enclose the output of the (incomplete) ZK page.

If you have a ZK page that contains a complete HTML page and is included by other page, you have to specify true for this option. For example, the includer is nothing but including another page:

//includer.jsp
<jsp:include page="includee.zhtml"/>

And, the included page contains a complete HTML page:

<?page complete="true"?>
    <html xmlns="http://www.zkoss.org/2005/zk/native"><head>    
        <title>My Title</tile>        
    </head>    
    <body>    
        My Content        

</body>

</html>

[Optional][Default: depends on the device]

It specifies the content type. If not specified, it depends on the device. For Ajax devices, it is text/html;charset=UTF-8. For XML and MIL devices, it is text/xml;charset=UTF-8.

Application developers rarely need to change it, unless for XML devices.

[Optional][Default: depends on the device]

It specifies the DOCTYPE (the root tag and DTD) that will be generated to the output directly. This directive is mainly used by XML devices. You rarely need to specify the DOCTYPE directive for Ajax or MIL devices. For example,

<?DOCTYPE value="svg PUBLIC &quot;-//W3C//DTD SVG 1.1//EN&quot; &quot;http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd&quot;"?>

will cause the output to be generated with the following snippet

<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"">

Notice that the <!DOCTYPE...> specified in a ZUML page is processed by ZK Loader. It is not part of the output.

[Optional][Default: generated automatically][EL allowed]

Specifies the identifier of the page, such that we can retrieve it back. If an alphabetical identifier is assigned, it will be available to scripts (aka., zscript) and EL expressions embedded in ZUML pages.

<?page id="${param.id}"?>

[Optional][Default: depending on the extension][Allowed values: xul/html | xhtml]

Specifies the markup language for this page. The markup language determines the default component set. Currently, it supports xul/html and xhtml.

Note: You can place the page directive in any location of a XML document, but the language attribute is meaningful only if the directive is located at the topmost level.

[Optional][Default: width:100%][EL allowed]

Specifies the CSS style used to render the page. If not specified, it depends on the mold. The default mold uses width:100% as the default value.

<?page style="width:100%;height:100%"?>

[Optional][Default: none][EL allowed]

Specifies the page title that will be shown as the title of the browser.

It can be changed dynamically by calling the setTitle method in the org.zkoss.zk.ui.Page interface.

<?page title="${param.title}"?>

[Optional][Default: none]

Specifies the xml processing instruction (i.e., <?xml?>) that will be generated to the output. Currently only XML devices support this option.

For example,

<?page xml="version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;"?>

will generate the following as the first line of the output

<?xml version="1.0" encoding="UTF-8"?>

[Optional][Default: Java][Allowed values: Java | JavaScript | Ruby | Groovy]

Specifies the default scripting language, which is assumed if an zscript element doesn't specify any scripting language explicitly.

<?page zscriptLanguage="JavaScript"?>

<zscript>
    var m = round(box.value); //JavaScript is assumed.    
</zscript>

If this option is omitted, Java is assumed. Currently ZK supports four different languages: Java, JavaScript, Ruby and Groovy. This option is case insensitive.

Note: Deployers can extend the number of supported scripting languages. Refer to the How to Support More Scripting Language section in the Developer's Guide.

Any numbers of names and values are allowed. The value could contain EL expressions.

[Required][EL is not allowed]

A URL of the taglib file. Unlike other URL and URI, it doesn't interpret ~ or * specially. And, the page and the taglib files it references must be in the same Web application.

[Required]

A prefix used to identify functions defined in this taglib file. The prefix could be any non-empty string.

[Optional]

A class name that must implement the org.zkoss.xel.VariableResolver interface. Unlike the init directive, the class name cannot be the class that is defined in zscript codes.

[Optional]

You could specify any number of arguments. If specified, arg0 will be passed as the first argument of the constructor, arg1 as the second argument, and so on. Of course, the implementation must have a compatible constructor. If no argument is specified, the default constructor is assumed.

[Required]

Specifies the prefix used to identify this method.

[Required]

Specifies the name used to identify this method. The full name is "prefix:name".

[Required]

Specifies the class that the method is defined in.

[Required]

The signature of the method. Note: the method must be public static.

[Required]

Specifies the attribute name.

[Optional][Default: false]

Specifies whether to omit the leading and trailing whitespaces of the attribute value.

[Optional][Default: true]

Specifies the condition to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to false.

[Optional][Default: false]

Specifies the condition not to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to true.

[optional][Default: component]

Specifies the scope to which the custom attributes are associated. If not specified, the component enclosing this element is the default scope to use.

[Optional][Default: none]

Specifies the format of the value. It could be none, list or map.

By default, the value is assigned to the attribute directly after evaluating EL expressions, if any. For example, "apple, ${more}" is evaluated to "apple, orange", if more is "orange", and assigned to the attribute.

If you want to specify a list of values, you can specify the composite attribute with list as follows.

<custom-attributes simple="apple, ${more}" composite="list"/>

Then, it is converted to a list with two elements. The first element is "apple" and the second "orange".

If you want to specify a map of values, you can specify the composite attribute with map as follows.

<custom-attributes simple="juice=apple, flavor=${more}" composite="map"/>

Then, it is converted to a map with two entries. The first entry is ("juice", "apple") and the second ("flavor", "orange").

[Optional][Default: true]

Specifies the condition to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to false.

[Optional][Default: false]

Specifies the condition not to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to true.

[optional][Default: false]

Specifies whether to store the variable always at the current ID space. By default, it is false. It means ZK will check the existence of any variable with the same name by looking up the current ID space, the parent ID space, and parent's parent, and so on. If found, the variable's value is replaced with the value specified here. If not, a local variable is created. If true is specified, it doesn't look up any parent ID space.

[Optional][Default: none]

Specifies the format of the value. It could be none, list or map.

By default, the value is assigned to the variable directly after evaluating EL expressions, if any. For example, "apple, ${more}" is evaluated to "apple, orange", if more is "orange", and assigned to the variable.

If you want to specify a list of values, you can specify the composite attribute with list as follows.

<variables simple="apple, ${more}" composite="list"/>

Then, it is converted to a list with two elements. The first element is "apple" and the second "orange".

If you want to specify a map of values, you can specify the composite attribute with map as follows.

<variables simple="juice=apple, flavor=${more}" composite="map"/>

Then, it is converted to a map with two entries. The first entry is ("juice", "apple") and the second ("flavor", "orange").

[Optional][Default: true]

Specifies the condition to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to false.

[Optional][Default: false]

Specifies the condition not to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to true.

[Optional][Default: true]

Specifies the condition to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to false.

[Optional][Default: false]

Specifies the condition not to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to true.

[Optional][Default: ignored]

It specifies a collection of objects, such that the zk element will be evaluated repeatedly against each object in the collection. If not specified or empty, this attribute is ignored. If non-collection object is specified, it is evaluated only once as if a single-element collection is specified.

[Optional][Default: 0]

It is used with the forEach attribute to specify the starting offset when iterating a collection of objects. If not specified, it iterates from the first element, i.e., 0 is assumed.

[Optional][Default: 0]

It is used with the forEach attribute to specify the index (starting from 0) that the iteration shall begin at. If not specified, the iteration begins at the first element, i.e., 0 is assumed.

If forEachBegin is greater than or equals to the number of elements, no iteration is performed.

[Optional][Default: the last element]

It is used with the forEach attribute to specify the index (starting from 0) the iteration shall ends at (inclusive). If not specified, the iterations ends at the last element.

If forEachEnd is greater than or equals to the number of elements, the iteration ends at the last element.

[Optional][Default: none]

Specifies the URI of the file containing the scripting codes. If specified, the scripting codes will be loaded as if they are embedded directly.

Note: the file shall contain the source codes in the selected scripting language. The encoding must be UTF-8. Don't specify a class file (aka. byte codes).

Like other URL and URI, it has several characteristics as follows.

The algorithm to resolve "*" is as follows.

[Optional][Default: the page's default scripting language][Allowed Values: Java | JavaScript | Ruby | Groovy]

It specifies the scripting language which the scripting codes are written in.

[Optional][Default: false]

Specifies whether to defer the evaluation of this element until the first non-deferred zscript codes of the same language has to be evaluated. It is used to defer the loading of the interpreter and then speed up the loading of a ZUML page. For example, if all zscript elements are deferred, they are evaluated only when the first event listened by a handler implemented in zscript is received.

Refer to the How to Defer the Evaluation section in the Developer's Guide.

[Optional][Default: true]

Specifies the condition to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to false.

[Optional][Default: false]

Specifies the condition not to evaluate this element. This element is ignored if the value specified to this attribute is evaluated to true.

org.zkoss.zk.ui.AbstractComponent