The component Directive

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

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

Defines a new component. There are two formats: by-macro and by-class.

The by-macro Format

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

The by-class Format

<?component name="myName" [class="myPackage.myClass"] [extend="true"] [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 extend="true". In other words, if extend="true" is specified, the previous definition of the component (with the same name) 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" extend="true" 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" extend="true" 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" extend="true" 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>

class

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

extend

[Optional]

If specified with "true", 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.

macroURI

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

moldName

[Optional][Default: default]

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

moldURI

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

name

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