The component Directive

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

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

Defines a new component for a particular page. Components defined in this directive is visible only to the page with this directive. To define components that can be used in any page, use the language addon, which is a XML file defining components for all pages in a Web application[35].

There are two formats: by-macro and by-class.

The by-macro Format

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

Defines a new component based on a ZUML page. It is called a 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). For more details, refer to the Macro Components chapter.

The by-class Format

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

Defines a new component, if the extends attribute is not specified, based on a class. It is called a primitive component. The class must implement the org.zkoss.zk.ui.Component interface.

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 brand-new component, you can override properties of existent components by specifying extends="existentName". In other words, if extends is specified, the definition of the specified component is loaded as the default value and then override only properties that are specified in this directive.

For example, assume you want to define a new component called mywindow by use of MyWindow instead of the default window, org.zkoss.zul.Window in a ZUML page. Then, you can declare it as follows.

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

It is equivalent to the following codes.

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

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

<?component name="okbutton" extends="button" label="OK"
style="border:1px solid blue"?>

Notice the new component name can be the same as the existent one. In this case, all instances of the specified type of component will use the initial properties you assigned, as if it hides the existent definition. For example, the following codes make all buttons to have a blue border as default.

<?button name="button" extends="button" style="border:1px solid blue"?>
<button/> <!-- with blue border -->

For more information, refer to the Developer's Reference.



[35] Language addon is described in the Component Development Guide.