component"
Robertwenzel (talk | contribs) |
|||
| (9 intermediate revisions by 2 users not shown) | |||
| Line 14: | Line 14: | ||
[apply="''composer''"] [''prop1''="''value1''"] [''prop2''="''value2''"]... ?> | [apply="''composer''"] [''prop1''="''value1''"] [''prop2''="''value2''"]... ?> | ||
| − | Defines a new component | + | Defines a new component in the page scope. |
= The by-macro Format = | = The by-macro Format = | ||
| Line 22: | Line 22: | ||
[apply="''composer''"] [language="xul/html"] [''prop1''="''value1''"] [''prop2''="''value2''"]... ?> | [apply="''composer''"] [language="xul/html"] [''prop1''="''value1''"] [''prop2''="''value2''"]... ?> | ||
| − | You | + | 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 < | + | 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 < | + | 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 33: | Line 33: | ||
= The by-template Format = | = The by-template Format = | ||
| − | + | {{versionSince| 8.0.0}} | |
| + | |||
'''Syntax:''' | '''Syntax:''' | ||
<?component name="''myName''" templateURI="''/mypath/my.zul''" | <?component name="''myName''" templateURI="''/mypath/my.zul''" | ||
[language="xul/html"] [''prop1''="''value1''"] [''prop2''="''value2''"]... ?> | [language="xul/html"] [''prop1''="''value1''"] [''prop2''="''value2''"]... ?> | ||
| − | Defines a named [http://books.zkoss.org/zk-mvvm-book/8.0/syntax/apply.html <apply>] element with a predefined templateURI and default parameters. | + | 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 = | = The by-class Format = | ||
| Line 49: | Line 50: | ||
| − | 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 < | + | 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 one < | + | 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 < | + | =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 | + | 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 < | + | 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 87: | Line 89: | ||
<source lang="xml" > | <source lang="xml" > | ||
| − | + | <?component name="button" extends="button" label="OK"?> | |
</source> | </source> | ||
| − | Notice that the properties won't be applied if a component is created manually (by < | + | 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 119: | Line 121: | ||
[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 < | + | 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]]. | For implementing a macro component, please refer to [[ZK Developer's Reference/UI Composing/Macro Component/Implement Custom Java Class|ZK Developer's Reference]]. | ||
| Line 155: | Line 157: | ||
== moldName == | == moldName == | ||
| − | [Optional][Default: < | + | [Optional][Default: <code>default</code>] |
| − | Used with the by-class format to specify the mold name. If < | + | 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 == | == moldURI == | ||
| Line 168: | Line 170: | ||
moldURI="class:com.mycompany.myrender" | moldURI="class:com.mycompany.myrender" | ||
| − | Used with the by-class format to specify the mold URI. If < | + | 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 == | ||
| Line 183: | Line 185: | ||
| 8.0.0 | | 8.0.0 | ||
| 2015/10/06 | | 2015/10/06 | ||
| − | | [[# | + | | [[#The_by-template_Format]] |
|- | |- | ||
| | | | ||
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 |