ZK Processing Instructions"
Tmillsclare (talk | contribs) |
m (correct highlight (via JWB)) |
||
(4 intermediate revisions by one other user not shown) | |||
Line 9: | Line 9: | ||
! <center>Description</center> | ! <center>Description</center> | ||
|- | |- | ||
− | | [http://books.zkoss.org/wiki/ZK_Developer%27s_Guide/Fundamental_ZK/ZK_User_Interface_Markup_Language/ZK_Processing_Instructions#The_page_Directive < | + | | [http://books.zkoss.org/wiki/ZK_Developer%27s_Guide/Fundamental_ZK/ZK_User_Interface_Markup_Language/ZK_Processing_Instructions#The_page_Directive <code>page</code>] |
| Describes attributes of a page | | Describes attributes of a page | ||
|- | |- | ||
− | | [http://books.zkoss.org/wiki/ZK_Developer%27s_Guide/Fundamental_ZK/ZK_User_Interface_Markup_Language/ZK_Processing_Instructions#The_component_Directive < | + | | [http://books.zkoss.org/wiki/ZK_Developer%27s_Guide/Fundamental_ZK/ZK_User_Interface_Markup_Language/ZK_Processing_Instructions#The_component_Directive <code>component</code>] |
| Defines a new component for a particular page | | Defines a new component for a particular page | ||
|} | |} | ||
Line 20: | Line 20: | ||
The XML processing instructions describe how to process the ZUML page. Here we list the most used directives. For the complete list of all directives, please refer to the [http://books.zkoss.org/wiki/ZK_Component_Reference Developer's Reference]. | The XML processing instructions describe how to process the ZUML page. Here we list the most used directives. For the complete list of all directives, please refer to the [http://books.zkoss.org/wiki/ZK_Component_Reference Developer's Reference]. | ||
− | == The < | + | == The <code>page</code> Directive == |
<source lang="xml" > | <source lang="xml" > | ||
Line 28: | Line 28: | ||
It describes attributes of a page. | It describes attributes of a page. | ||
− | '''Note''': You can place the < | + | '''Note''': You can place the <code>page</code> directive in any location of a XML document, but the <code>language</code> attribute is meaningful only if the directive is located at the topmost level, i.e., at the the same level as the root element. |
− | Remember to use the < | + | Remember to use the <code>page</code> directive if you want to use java code to access component by absolute path, like |
<source lang="java" > | <source lang="java" > | ||
Line 38: | Line 38: | ||
For more available options and descriptions, refer to [[ZK_Component_Reference | '''the Component Reference''']]. | For more available options and descriptions, refer to [[ZK_Component_Reference | '''the Component Reference''']]. | ||
− | == The < | + | == The <code>component</code> Directive == |
<source lang="xml" > | <source lang="xml" > | ||
Line 48: | Line 48: | ||
</source> | </source> | ||
− | Defines a new component for a particular page. It can be a < | + | Defines a new component for a particular page. It can be a <code>macro</code> from a separate zul file or a extending class from existing component. Components defined in this directive is visible only to the page with this directive. |
---- | ---- | ||
There are two formats: by-macro and by-class. | There are two formats: by-macro and by-class. | ||
− | === The < | + | === The <code>by-macro</code> Format === |
<source lang="xml" > | <source lang="xml" > | ||
Line 59: | Line 59: | ||
</source> | </source> | ||
− | 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 < | + | 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 <code>macroURI</code> attribute). It's useful to divide a big zul file to separate single function little zul files. It's easier to maintain and test. |
For example: | For example: | ||
Line 77: | Line 77: | ||
</source> | </source> | ||
− | For more details, refer to the [ | + | For more details, refer to the [[ZK_Developer's_Guide/ZK_in_Depth/Macro_Component | '''Macro Components''']] chapter. |
− | === The < | + | === The <code>by-class</code> Format === |
<source lang="xml" > | <source lang="xml" > | ||
Line 87: | Line 87: | ||
</source> | </source> | ||
− | Defines a new component. If the < | + | Defines a new component. If the <code>extends</code> attribute is not specified, it is called a ''primitive component''. The class must implement the <javadoc type="interface">org.zkoss.zk.ui.Component</javadoc> interface. |
− | To define a new component, you have to specify at least the < | + | To define a new component, you have to specify at least the <code>class</code> 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 < | + | In addition to defining a brand-new component, you can override properties of existent components by specifying <code>extends="existentName"</code>. In other words, if <code>extends</code> 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 < | + | For example, assume you want to define a new component called <code>mywindow</code> by use of <code>MyWindow</code> instead of the default window, <javadoc>org.zkoss.zul.Window</javadoc> in a ZUML page. Then, you can declare it as follows. |
<source lang="xml" > | <source lang="xml" > | ||
Line 125: | Line 125: | ||
</source> | </source> | ||
− | For more information, refer to the [ | + | For more information, refer to the [[ZK_Component_Reference | Component Reference]]. |
== Quiz == | == Quiz == | ||
− | 1.Please visit [ | + | 1.Please visit the [[ZK_Component_Reference | Component Reference]] and look up what value is accepted by <code>zscriptLanguage</code> |
2.Assume following macro zul, write a zul to use it. | 2.Assume following macro zul, write a zul to use it. |
Latest revision as of 10:38, 19 January 2022
This documentation is for an older version of ZK. For the latest one, please click here.
Directives to control whole page behavior
page
|
Describes attributes of a page |
component
|
Defines a new component for a particular page |
Overview
The XML processing instructions describe how to process the ZUML page. Here we list the most used directives. For the complete list of all directives, please refer to the Developer's Reference.
The page
Directive
<?page [id="..."] [title="..."] [style="..."][language="xul/html"]?>
It describes attributes of a page.
Note: You can place the page
directive in any location of a XML document, but the language
attribute is meaningful only if the directive is located at the topmost level, i.e., at the the same level as the root element.
Remember to use the page
directive if you want to use java code to access component by absolute path, like
Path.getComponent("//P/A/C/E");//for page, you have to use // as prefix
For more available options and descriptions, refer to the Component Reference.
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. It can be a macro
from a separate zul file or a extending class from existing component. Components defined in this directive is visible only to the page with this directive.
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). It's useful to divide a big zul file to separate single function little zul files. It's easier to maintain and test.
For example: A zul file name as: /WEB-INF/macros/username.zul
<hbox>
Username: <textbox/>
</hbox>
Then we can use it as a macro component as following example shows:
<?component name="username" macroURI="/WEB-INF/macros/username.zul"?>
<window>
<username/>
</window>
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, it is called a primitive component. The class must implement the 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, 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.
<?component name="button" extends="button" style="border:1px solid blue"?>
<button/> <!-- with blue border -->
For more information, refer to the Component Reference.
Quiz
1.Please visit the Component Reference and look up what value is accepted by zscriptLanguage
2.Assume following macro zul, write a zul to use it.
username.zul
<row>
Username
<textbox/>
</row>