component"

From Documentation
(30 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{ZKDevelopersReferencePageHeader}}
+
{{ZKClient-sideReferencePageHeader}}
 +
 
 +
__TOC__
  
 
'''Syntax:'''
 
'''Syntax:'''
 +
<syntaxhighlight lang='xml'>
 
  <component>
 
  <component>
 
   <component-name>''a_name''</component-name>
 
   <component-name>''a_name''</component-name>
Line 34: Line 37:
 
   </custom-attribute>
 
   </custom-attribute>
 
  </component>
 
  </component>
 +
</syntaxhighlight>
 +
 +
It declares a component definition. You can use this to define your custom component which can extend the existing component or a completely-new component with it's own Java class or JavaScript widget.
 +
 +
 +
 +
= Usage Examples =
 +
 +
== Set Default Value for Button in Application-scope ==
 +
<source lang="xml">
 +
    <component>
 +
        <component-name>button</component-name>
 +
        <extends>button</extends>
 +
        <property>
 +
            <property-name>autodisable</property-name>
 +
            <property-value>self</property-value>
 +
        </property>
 +
    </component>
 +
</source>
 +
 +
=component-name=
 +
[Required]
 +
 +
The name of the component. It must be unique in the whole language.
 +
 +
=extends=
 +
[Optional]
 +
 +
It specifies whether this definition is extending from another definition. If omitted, it is considered a definition of a new component. If specified, it extends from the given component definition (which must be defined first).
 +
 +
Notice that the component's name could be the same as the definition it extends from. If the same, the existent definition is simply overridden (no new component definition is created). It is a useful technique to change a component definition, such as adding annotation, providing the initial properties and so on.
 +
 +
== depend required ==
 +
if your component extends a component, most likely you need to specify [[ZK_Client-side_Reference/Language_Definition/depends| <code><depends></code>]] to ensure parsing order.
 +
 +
=component-class=
 +
[Required if no extends]
 +
 +
It specifies the component's Java class at the server side. It is required if you define a new component.
  
It specifies a component definition.
+
=widget-class=
 +
[Required if no extends][EL expressions allowed]
  
Example,
+
It specifies the widget's class at the client side. For Ajax clients, it must be a JavaScript class. It is required if you define a new component.
  
 +
Since EL expressions are allowed, the widget class being associated with a component could be decided at runtime. Please refer to [http://blog.zkoss.org/index.php/2010/08/02/totally-different-look-per-user-without-modifying-application/ Blog: Totally Different Look per User Without Modifying Application] for an example.
 +
 +
= mold =
 +
Any number of molds are allowed.
 +
 +
== Custom Mold ==
 
<source lang="xml">
 
<source lang="xml">
 
<component>
 
<component>
Line 49: Line 98:
 
</mold>
 
</mold>
 
</component>
 
</component>
 +
</source>
 +
 +
==mold-uri==
 +
* a path relative to a widget js
 +
* [[ZK_Developer%27s_Reference/UI_Composing/ZUML/Include_a_Page#Classpath_Web_Resource_Path | classpath web resource path]]
 +
 +
=property=
 +
[Optional][EL expressions allowed in the property value]
 +
 +
It specifies an initial property. Once the property is specified, the corresponding setter will be called when ZK Loader instantiates from a ZUML document. Of course, if you instantiate it directly in Java, this setting has no effect.
 +
 +
Suppose we want to make all window's border default to <code>normal</code>, we could do as follows.
 +
 +
[[ZK_Developer's_Reference/Customization/Component_Properties|Customization Reference]]
 +
 +
 +
<source lang="xml">
 +
<property>
 +
    <property-name>border</property-name>
 +
    <property-value>normal</property-value>
 +
</property>
 +
</source>
 +
 +
Another example , to turn off combobox's autocomplete.
 +
<source lang="xml">
 
<component>
 
<component>
<component-name>bandbox</component-name>
+
    <component-name>combobox</component-name>                      <!-- required -->
<extends>bandbox</extends>
+
    <component-class>org.zkoss.zul.Combobox</component-class>     <!-- required -->
<annotation>
+
    <widget-class>zul.inp.Combobox</widget-class>                 <!-- required -->
<annotation-name>default-bind</annotation-name>
+
    <property>  
<property-name>value</property-name>
+
        <property-name>autocomplete</property-name>
<attribute>
+
        <property-value>false</property-value>
<attribute-name>access</attribute-name>
+
    </property>
<attribute-value>both</attribute-value>
 
</attribute>
 
</annotation>
 
 
</component>
 
</component>
 
</source>
 
</source>
=component-name=
 
[Required]
 
  
The name of the component. It must be unique in the whole language.
+
=text-as=
 +
[Optional]
 +
 
 +
It specifies the name of the property to assign the text enclosed by the XML element. If omitted (default), the text will be interpreted as a label and a label component defined in [[ZK Client-side Reference/Language Definition/label-template|label-template]] will be used.
 +
 
 +
For example, if you specify
 +
 
 +
<source lang="xml">
 +
<component>
 +
  <component-name>foo</component-name>
 +
  <text-as>content</text-as>
 +
</source>
 +
 
 +
then, the following ZUML document
 +
<source lang="xml">
 +
<foo>the content of foo</foo>
 +
</source>
 +
 
 +
will cause <code>foo.setContent("the content of foo")</code> to be called (assume foo is an instance of the component).
 +
 
 +
 
 +
=template-uri=
 +
[Optional]
 +
Specify a URI of a zul file as a template of this component. Support <code>~.</code>. When you use the custom tag in a zul, ZK will inject the specified zul file like you use <code><apply templateURI="/my/long/path/mytemplate.zul"/></code>. If you specify this element, it will override <code><extends></code>.
 +
 
 +
 
 +
== Required zuti ==
 +
This feature requires <code>zuti</code> module:
 +
<syntaxhighlight lang='xml' highlight='5'>
 +
<language-addon>
 +
<addon-name>my-addon</addon-name>
 +
<version>0.1</version>
 +
<language-name>xul/html</language-name>
 +
<depends>zuti</depends>
 +
</syntaxhighlight>
 +
 
 +
== Define a Custom Component ==
 +
<syntaxhighlight lang='xml'>
 +
<component>
 +
<component-name>megamenu</component-name>
 +
<template-uri>/uiComposing/megaMenuParameterized.zul</template-uri>
 +
</component>
 +
<component>
 +
<component-name>state-box</component-name>
 +
<template-uri>/WEB-INF/template/stateBox.zul</template-uri>
 +
</component>
 +
<component>
 +
<component-name>my-box</component-name>
 +
<template-uri>~./template/infoBox.zul</template-uri>
 +
</component>
 +
</syntaxhighlight>
 +
 
 +
Then those custom components are available in application scope, and you can use it in any zul like other components:
 +
<syntaxhighlight lang='xml'>
 +
<megamenu>
 +
</syntaxhighlight>
  
=extends=
+
This can improve readability and reusability.
=component-class=
 
[Required if no extends]
 
  
It specifies the component's Java class at the server side. It is required if you define a new component.
 
=Version History=
 
{{LastUpdated}}
 
{| border='1px' | width="100%"
 
! Version !! Date !! Content
 
|-
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
|}
 
  
{{ZKDevelopersReferencePageFooter}}
+
{{ZKClient-sideReferencePageFooter}}

Revision as of 02:08, 20 March 2023


Syntax:

 <component>
   <component-name>''a_name''</component-name>
   <extends>''a_name''</extends>
   <component-class>''a_class_name''</component-class>
   <widget-class>''a_class_name''</widget-class>
 
   <mold>
     <mold-name>''a_mold''</mold-name>
     <mold-uri>''a_uri''</mold-uri>
   </mold>
 
   <text-as>''a_property_name''</text-as>
 
   <property>
     <property-name>''a_name''</property-name>
     <property-value>''a_value''</property-value>
   </property>
 
   <annotation>
     <annotation-name>''an_annotation_name''</annotation-name>
     <property-name>''a_property_name''</property-name>
     <attribute>
       <attribute-name>''an_annotation_attr_name''</attribute-name>
       <attribute-value>''an_annotation_attr_value''</attribute-value>
     </attribute>
   </annotation>
 
    <custom-attribute>
     <attribute-name>''a_custom_attr_name''</attribute-name>
     <attribute-value>''a_custom_attr_value''</attribute-value>
   </custom-attribute>
 </component>

It declares a component definition. You can use this to define your custom component which can extend the existing component or a completely-new component with it's own Java class or JavaScript widget.


Usage Examples

Set Default Value for Button in Application-scope

    <component>
        <component-name>button</component-name>
        <extends>button</extends>
        <property>
            <property-name>autodisable</property-name>
            <property-value>self</property-value>
        </property>
    </component>

component-name

[Required]

The name of the component. It must be unique in the whole language.

extends

[Optional]

It specifies whether this definition is extending from another definition. If omitted, it is considered a definition of a new component. If specified, it extends from the given component definition (which must be defined first).

Notice that the component's name could be the same as the definition it extends from. If the same, the existent definition is simply overridden (no new component definition is created). It is a useful technique to change a component definition, such as adding annotation, providing the initial properties and so on.

depend required

if your component extends a component, most likely you need to specify <depends> to ensure parsing order.

component-class

[Required if no extends]

It specifies the component's Java class at the server side. It is required if you define a new component.

widget-class

[Required if no extends][EL expressions allowed]

It specifies the widget's class at the client side. For Ajax clients, it must be a JavaScript class. It is required if you define a new component.

Since EL expressions are allowed, the widget class being associated with a component could be decided at runtime. Please refer to Blog: Totally Different Look per User Without Modifying Application for an example.

mold

Any number of molds are allowed.

Custom Mold

<component>
	<component-name>area</component-name>
	<component-class>org.zkoss.zul.Area</component-class>
	<widget-class>zul.wgt.Area</widget-class>
	<mold>
		<mold-name>default</mold-name>
		<mold-uri>mold/area.js</mold-uri>
	</mold>
</component>

mold-uri

property

[Optional][EL expressions allowed in the property value]

It specifies an initial property. Once the property is specified, the corresponding setter will be called when ZK Loader instantiates from a ZUML document. Of course, if you instantiate it directly in Java, this setting has no effect.

Suppose we want to make all window's border default to normal, we could do as follows.

Customization Reference


<property>
    <property-name>border</property-name>
    <property-value>normal</property-value>
</property>

Another example , to turn off combobox's autocomplete.

<component>
    <component-name>combobox</component-name>                      <!-- required -->
    <component-class>org.zkoss.zul.Combobox</component-class>      <!-- required -->
    <widget-class>zul.inp.Combobox</widget-class>                  <!-- required -->
    <property> 
        <property-name>autocomplete</property-name>
        <property-value>false</property-value>
    </property>
</component>

text-as

[Optional]

It specifies the name of the property to assign the text enclosed by the XML element. If omitted (default), the text will be interpreted as a label and a label component defined in label-template will be used.

For example, if you specify

<component>
  <component-name>foo</component-name>
  <text-as>content</text-as>

then, the following ZUML document

<foo>the content of foo</foo>

will cause foo.setContent("the content of foo") to be called (assume foo is an instance of the component).


template-uri

[Optional]

Specify a URI of a zul file as a template of this component. Support ~.. When you use the custom tag in a zul, ZK will inject the specified zul file like you use <apply templateURI="/my/long/path/mytemplate.zul"/>. If you specify this element, it will override <extends>.


Required zuti

This feature requires zuti module:

<language-addon>
	<addon-name>my-addon</addon-name>
	<version>0.1</version>
	<language-name>xul/html</language-name>
	<depends>zuti</depends>

Define a Custom Component

	<component>
		<component-name>megamenu</component-name>
		<template-uri>/uiComposing/megaMenuParameterized.zul</template-uri>
	</component>
	<component>
		<component-name>state-box</component-name>
		<template-uri>/WEB-INF/template/stateBox.zul</template-uri>
	</component>
	<component>
		<component-name>my-box</component-name>
		<template-uri>~./template/infoBox.zul</template-uri>
	</component>

Then those custom components are available in application scope, and you can use it in any zul like other components:

<megamenu>

This can improve readability and reusability.



Last Update : 2023/03/20

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