component"

From Documentation
 
(25 intermediate revisions by 5 users not shown)
Line 2: Line 2:
  
 
__TOC__
 
__TOC__
 +
 +
'''Syntax:'''
 +
<?component name="''myName''" templateURI="''/mypath/my.zul''" ?>
  
 
  <?component name="''myName''" macroURI="''/mypath/my.zul''" [inline="true|'''false'''"]
 
  <?component name="''myName''" macroURI="''/mypath/my.zul''" [inline="true|'''false'''"]
 
   [apply="''composer''"] [''prop1''="''value1''"] [''prop2''="''value2''"]... ?>
 
   [apply="''composer''"] [''prop1''="''value1''"] [''prop2''="''value2''"]... ?>
 +
 
  <?component name="''myName''" [class="''myPackage.myClass''"]
 
  <?component name="''myName''" [class="''myPackage.myClass''"]
 
   [extends="''nameOfExistComponent''"]
 
   [extends="''nameOfExistComponent''"]
Line 10: Line 14:
 
   [apply="''composer''"] [''prop1''="''value1''"] [''prop2''="''value2''"]... ?>
 
   [apply="''composer''"] [''prop1''="''value1''"] [''prop2''="''value2''"]... ?>
  
Defines a new component. There are two formats: by-macro and by-class.
+
Defines a new component in the page scope.
 
 
== The by-macro Format ==
 
  
 +
= The by-macro Format =
  
  <?component name="''myName''" macroURI="''/mypath/my.zul''" [compose="before|after"]
+
'''Syntax:'''
   [apply="''composer''"] [language="xul/html"] [prop1="value1"] [prop2="value2"]... ?>
+
  <?component name="''myName''" macroURI="''/mypath/my.zul''"
 +
   [apply="''composer''"] [language="xul/html"] [''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 <tt>macroURI</tt> attribute).
+
You can 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 <code>macroURI</code> attribute).
  
In addition, you could specify the initial properties (such as <tt>prop1</tt> in the above example), such that they are always passed to the macro component (thru the <tt>arg</tt> variable).
+
In addition, you could specify the initial properties (such as <code>prop1</code> in the above example), such that they are always passed to the macro component (through the <code>arg</code> variable).
  
The <tt>inline</tt> attribute specifies whether it is an inline macro (<tt>inlinie="true"</tt>) or a regular macro (default).
+
The <code>inline</code> attribute specifies whether it is an inline macro (<code>inlinie="true"</code>) 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.
 
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.
Line 28: Line 32:
 
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.
 
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 ==
+
= The by-template Format =
 +
{{versionSince| 8.0.0}}
 +
 
 +
'''Syntax:'''
 +
<?component name="''myName''" templateURI="''/mypath/my.zul''"
 +
  [language="xul/html"] [''prop1''="''value1''"] [''prop2''="''value2''"]... ?>
 +
 
 +
Defines a named [http://books.zkoss.org/zk-mvvm-book/8.0/syntax/apply.html <apply>] element on that page with a predefined templateURI and default optional parameters. ([[ZK_Developer%27s_Reference/UI_Composing/ZUML/Include_a_Page#Application-wide_Named_.3CApply.3E|Application wide configuration]])
 +
 
 +
= The by-class Format =
  
 +
'''Syntax:'''
 
  <?component name="''myName''" [class="''myPackage.myClass''"]
 
  <?component name="''myName''" [class="''myPackage.myClass''"]
 
   [extends="''nameOfExistComponent''"]
 
   [extends="''nameOfExistComponent''"]
 
   [moldName="''myMoldName''"] [moldURI="/''myMoldURI''"]
 
   [moldName="''myMoldName''"] [moldURI="/''myMoldURI''"]
   [apply="''composer''"] [language="xul/html"] [prop1="value1"] [prop2="value2"]...?>
+
   [apply="''composer''"] [language="xul/html"] [''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 <javadoc type="interface">org.zkoss.zk.ui.Component</javadoc> interface. Then, use the <tt>by-class</tt> format to declare such kind of components for a page.
+
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 <javadoc type="interface">org.zkoss.zk.ui.Component</javadoc> interface. Then, use the <code>by-class</code> format to declare such kind of components for a page.
  
To define a new component, you have to specify at least the <tt>class</tt> attribute, which is used by ZK to instantiate a new instance of the component.
+
To define a new component, you have to specify at least one <code>class</code> 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 <tt>extends</tt> element with the component's name to extend from (aka., extendee). In other words, if <tt>extends</tt> is specified, the definition of the extendee is loaded as the default value and then override only properties that are specified in this directive.
+
=Define Initial Attribute Value=
 +
In addition to defining a new component, you can override properties of existent components by specifying the <code>extends</code> element with the component's name to extend from (aka., extendee). In other words, if <code>extends</code> is specified, the definition of the extendee is loaded as the default value and then override only properties that are specified in this directive.
  
If the name of extendee and extender are the same, it means the extender will override the definition of extendee.
+
If the name of extendee and extender is the same, it means the extender will override the definition of extendee.
  
For example, assume you want to use <tt>MyWindow</tt> instead of the default window, <javadoc>org.zkoss.zul.Window</javadoc> for all windows defined in this ZUML page. Then, you can declare it as follows.
+
For example, assume you want to use <code>MyWindow</code> instead of the default window, <javadoc>org.zkoss.zul.Window</javadoc> for all windows defined in this ZUML page. Then, you can declare it as follows.
  
 
<source lang="xml" >
 
<source lang="xml" >
  <?component name="window" extends="window" class="MyWindow"?>
+
  <?component name="window" extends="window" class="foo.MyWindow"?>
 
  ...
 
  ...
 
  <window>
 
  <window>
Line 74: Line 89:
  
 
<source lang="xml" >
 
<source lang="xml" >
<?component name="button" extends="button" label="OK"?>
+
<?component name="button" extends="button" label="OK"?>
 
</source>
 
</source>
  
  
Notice that the properties won't be applied if a component is created manually (by <tt>zscript</tt> or by Java codes). If you still want them to be applied with the initialial properties, you could invoke the <tt>applyProperties</tt> method as follows.
+
Notice that the properties won't be applied if a component is created manually (by <code>zscript</code> or by Java codes). If you still want them to be applied with the initialial properties, you could invoke the <code>applyProperties</code> method as follows.
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 87: Line 102:
 
</source>
 
</source>
  
== Attributes ==
+
= Attributes =
=== apply ===
+
== apply ==
 
  [Optional]
 
  [Optional]
 
  [Since 3.6.0]
 
  [Since 3.6.0]
Line 102: Line 117:
 
</source>
 
</source>
  
=== class ===
+
== class ==
  
 
  [Optional]
 
  [Optional]
  
Used to specify the class to instantiate an instance of such kind of components. Unlike other directives, the class can be defined with <tt>zscript</tt>.
+
Used to specify the class to instantiate an instance of such kind of components. Unlike other directives, the class can be defined with <code>zscript</code>.
 +
 
 +
For implementing a macro component, please refer to [[ZK Developer's Reference/UI Composing/Macro Component/Implement Custom Java Class|ZK Developer's Reference]].
  
=== extends ===
+
== extends ==
  
 
  [Optional]
 
  [Optional]
Line 114: Line 131:
 
Specifies the component name to extend from. The existent definition of the specified name will be loaded to initialize the new component definition. In other words, it ''extends'' the existent definition instead of defining a brand-new one.
 
Specifies the component name to extend from. The existent definition of the specified name will be loaded to initialize the new component definition. In other words, it ''extends'' the existent definition instead of defining a brand-new one.
  
=== language ===
+
== language ==
  
[Optional][Since ZK 5.0.0]
+
[Optional][Since ZK 5.0.0]
  
 
Specifies which language to look for the component definition to extends from. If omitted, the page's language is assumed.
 
Specifies which language to look for the component definition to extends from. If omitted, the page's language is assumed.
Line 126: Line 143:
 
</source>
 
</source>
  
=== macroURI ===
+
== macroURI ==
  
 
  [Required if the by-macro format is used][EL is ''not'' allowed]
 
  [Required if the by-macro format is used][EL is ''not'' allowed]
Line 132: Line 149:
 
Used with the by-macro format to specify the URI of the ZUML page, which is used as the template to create components.
 
Used with the by-macro format to specify the URI of the ZUML page, which is used as the template to create components.
  
=== compose ===
+
== templateURI ==
[Optional][Default: after][Allowed: before|after]
 
[Since 5.0.5]
 
 
 
Used with the by-macro format to specify when to compose the macro component.
 
 
 
By default, the macro component is composed (i.e., create child components from the macro URI) after all properties are set. More precisely, it is composed when <javadoc method="afterCompose()">org.zkoss.zk.ui.HtmlMacroComponent</javadoc> is called.
 
 
 
If you implements your own macro class (extending from <javadoc>org.zkoss.zk.ui.HtmlMacroComponent</javadoc>), it is bit tedious to implement a setter since the child component is not ready when it is called. In this case, you could specify <code>compose="before"</code> and then the macro component is composed before setting the properties (but still after the parent is assigned). Therefore, you could access the child components directly since they are created when a setter is called.
 
 
 
For example, if we declare the compose condition to be <code>before</code> as follows.
 
 
 
<source lang="xml" high="2">
 
<?component name="username" macroURI="macro.zul" class="Username"
 
  compose="before"?>
 
</source>
 
 
 
Then, we can access them directly in a setter.
 
 
 
<source lang="java">
 
public class Foo extends HtmlMacroComponent {
 
    private Textbox input; //assume there is a textbox whose ID is input
 
    public void setValue(String value) {
 
        input.setValue(value);
 
    }
 
}
 
</source>
 
  
Notice that <code>input</code> is wired automatically when the macro component is composed. Furthermore, since it is composed before calling <code>setValue</code>, it is safe to access <code>input</code> in <code>setValue</code>.
+
[Required if the by-template format is used][EL is ''not'' allowed]
  
=== moldName ===
+
Used with the by-template format to specify the URI of the ZUML page, which is used as the template to create components.
  
[Optional][Default: <tt>default</tt>]
+
== moldName ==
  
Used with the by-class format to specify the mold name. If <tt>moldName</tt> is specified, <tt>moldURI</tt> must be specified, too.
+
[Optional][Default: <code>default</code>]
  
=== moldURI ===
+
Used with the by-class format to specify the mold name. If <code>moldName</code> is specified, <code>moldURI</code> must be specified, too.
  
 +
== moldURI ==
 +
[REMOVED, only for ZK < 5.0.0]
 
  [Optional][EL is allowed]
 
  [Optional][EL is allowed]
  
Line 177: Line 170:
 
  moldURI="class:com.mycompany.myrender"
 
  moldURI="class:com.mycompany.myrender"
  
Used with the by-class format to specify the mold URI. If <tt>moldURI</tt> is specified but <tt>moldName</tt> is not specified, the mold name is assumed as <tt>default</tt>.
+
Used with the by-class format to specify the mold URI. If <code>moldURI</code> is specified but <code>moldName</code> is not specified, the mold name is assumed as <code>default</code>.
  
=== name ===
+
== name ==
  
 
  [Required]
 
  [Required]
Line 185: Line 178:
 
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.
 
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.
  
==Version History==
+
=Version History=
  
 
{| border='1px' | width="100%"
 
{| border='1px' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 +
|-
 +
| 8.0.0
 +
| 2015/10/06
 +
| [[#The_by-template_Format]]
 
|-
 
|-
 
| &nbsp;
 
| &nbsp;

Latest revision as of 10:35, 19 June 2023

Syntax:

<?component name="myName" templateURI="/mypath/my.zul" ?>
<?component name="myName" macroURI="/mypath/my.zul" [inline="true|false"]
  [apply="composer"] [prop1="value1"] [prop2="value2"]... ?>
<?component name="myName" [class="myPackage.myClass"]
  [extends="nameOfExistComponent"]
  [moldName="myMoldName"] [moldURI="/myMoldURI"]
  [apply="composer"] [prop1="value1"] [prop2="value2"]... ?>

Defines a new component in the page scope.

The by-macro Format

Syntax:

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

You can 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 (through 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-template Format

Since 8.0.0

Syntax:

<?component name="myName" templateURI="/mypath/my.zul"
  [language="xul/html"] [prop1="value1"] [prop2="value2"]... ?>

Defines a named <apply> element on that page with a predefined templateURI and default optional parameters. (Application wide configuration)

The by-class Format

Syntax:

<?component name="myName" [class="myPackage.myClass"]
  [extends="nameOfExistComponent"]
  [moldName="myMoldName"] [moldURI="/myMoldURI"]
  [apply="composer"] [language="xul/html"] [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 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 one class attribute, which is used by ZK to instantiate a new instance of the component.

Define Initial Attribute Value

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

If the name of extendee and extender is the same, it means the extender will override the definition of extendee.

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

 <?component name="window" extends="window" class="foo.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>

Attributes

apply

[Optional]
[Since 3.6.0]

The apply condition, which is a list of composer's class names or EL expressions. If an EL expression is specified, it must return either a class instance, a class name, a composer instance or null.

Notice that the list of composers specified here is always applied even if the component has its own apply condition. For example, both BaseComposer and FooComposer are applied in the following example,

<?component name="window" extends="window" apply="BaseComposer"?>
<window apply="FooComposer">
</window>

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.

For implementing a macro component, please refer to ZK Developer's Reference.

extends

[Optional]

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

language

[Optional][Since ZK 5.0.0]

Specifies which language to look for the component definition to extends from. If omitted, the page's language is assumed.

Notice that the new defined component is visible only to the associate page. The language attribute is used for locating the component definition specified in the extends attribute. For example, the following statement works even if it is used in a ZHTML file.

<?component name="foo" extends="button" language="xul/html"?>

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.

templateURI

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

Used with the by-template 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

[REMOVED, only for ZK < 5.0.0]
[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.

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.

Version History

Version Date Content
8.0.0 2015/10/06 #The_by-template_Format
     



Last Update : 2023/06/19

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.