Include a Page"
From Documentation
RebeccaLai (talk | contribs) m |
|||
| (14 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
{{ZKDevelopersReferencePageHeader}} | {{ZKDevelopersReferencePageHeader}} | ||
| − | = | + | = Apply (Recommended)= |
| − | + | {{versionSince| 8.0.0}} | |
| + | We suggest using [http://books.zkoss.org/zk-mvvm-book/8.0/shadow_elements/shadow_elements.html <code><apply></code>] instead of <code>Include</code>. Because comparing to <code>Include</code>, it has several advantages: | ||
# Doesn't consume extra memory. | # Doesn't consume extra memory. | ||
#: Because it's a shadow element, it doesn't create a corresponding component at the server side. | #: Because it's a shadow element, it doesn't create a corresponding component at the server side. | ||
| − | # Doesn't render an extra < | + | # Doesn't render an extra <code><div></code> surrounding its child components at the client-side. |
| − | #:< | + | #:<code>Include</code> renders a <code><div></code> to enclose its child components. Sometimes the outer <code><div></code> breaks the layout. |
# Doesn't create an ID space. | # Doesn't create an ID space. | ||
| − | #: < | + | #: <code>Include</code> itself is an ID space owner which affects you when locating a component with ZK selector syntax. |
# It can render its child components upon parameters dynamically. | # It can render its child components upon parameters dynamically. | ||
| − | #:You can pass a parameter with data binding and bind to the parameter. When the parameter's value changes, the content will | + | #: You can pass a parameter with data binding and bind to the parameter. When the parameter's value changes, the content will change accordingly. |
= Include = | = Include = | ||
| − | [[ZK Component Reference/Essential Components/Include|Include]] allows you to include a | + | [[ZK Component Reference/Essential Components/Include|Include]] allows you to include a zul page, an HTML, zhtml, JSP page, or a URL mapped to a servlet. For example, |
<source lang="xml"> | <source lang="xml"> | ||
| Line 20: | Line 21: | ||
</source> | </source> | ||
| − | |||
When including a ZUML page, the components specified in the ZUML page will become the child components of the <javadoc>org.zkoss.zul.Include</javadoc> component. | When including a ZUML page, the components specified in the ZUML page will become the child components of the <javadoc>org.zkoss.zul.Include</javadoc> component. | ||
| Line 42: | Line 42: | ||
Then, <code>listbox</code> in <code>second.zul</code> will become the child of <code>include</code> in <code>first.zul</code>. | Then, <code>listbox</code> in <code>second.zul</code> will become the child of <code>include</code> in <code>first.zul</code>. | ||
| − | If you prefer to create an independent page (<javadoc type="interface">org.zkoss.zk.ui.Page</javadoc>), or want to include a page rendered by < | + | |
| + | When including a non-ZUML page (such as JSP), the output of the page will be the content of the <javadoc>org.zkoss.zul.Include</javadoc> component. Thus, the output must be a valid HTML fragment without <code><html>, <head>, <body></code>. | ||
| + | |||
| + | |||
| + | If you prefer to create an independent page (<javadoc type="interface">org.zkoss.zk.ui.Page</javadoc>), or want to include a page rendered by <code>Richlet</code> while the value of src ends with <code>.zul</code> or <code>.zhtml</code>, you could specify the mode with <code>defer</code> (<javadoc method="setMode(java.lang.String)">org.zkoss.zul.Include</javadoc>). Then, <code>include</code> won't have any child. Rather, an instance of <javadoc type="interface">org.zkoss.zk.ui.Page</javadoc> will be created to hold the content of <code>second.zul</code> or the content generated by Richlet. For more information, please refer to [[ZK Component Reference/Essential Components/Include|ZK Component Reference: include]]. | ||
= Classpath Web Resource Path= | = Classpath Web Resource Path= | ||
| − | ZK provides a special path URL starting with '''< | + | ZK provides a special path URL starting with '''<code>~./</code>''', it looks for a file under a folder starting with '''<code>web</code>''' in a web application's classpath, e.g. |
| + | * <code>my-module.jar/web/</code>. | ||
| + | * WEB-INF/classes/web | ||
| + | So it will get a file under the path among all included jars. You can specify such URL in a component path-related attribute like: | ||
<source lang='xml'> | <source lang='xml'> | ||
| Line 63: | Line 70: | ||
</source> | </source> | ||
| − | It can be used as a default shared folder path for a jar. When you create a sub-module project, you can put some shared resources or reusable template zul files under this folder. Then, package the sub-module as a jar and include the sub-module jar in the main project. The main project can easily access those reusable resources by this special URL. Notice that the zul files under this special resource path are | + | == Modular Resource Sharing == |
| + | It can be used as a default shared folder path for a jar. When you create a sub-module project, you can put some shared resources or reusable template zul files under this folder. Then, package the sub-module as a jar and include the sub-module jar in the main project. The main project can easily access those reusable resources by this special URL. Notice that the zul files under this special resource path are publicly accessed with a URL in a browser, you should not put any sensitive data in it. | ||
<!-- | <!-- | ||
org.zkoss.web.util.resource.ClassWebResource | org.zkoss.web.util.resource.ClassWebResource | ||
--> | --> | ||
| + | |||
= Application-wide Named <Apply> = | = Application-wide Named <Apply> = | ||
| − | + | {{versionSince| 8.0.1}} | |
| − | If you prefer | + | If you prefer an application-wide named [http://books.zkoss.org/zk-mvvm-book/8.0/syntax/apply.html <apply>] element with a predefined templateURI and default parameters, you could specify it in [[ZK Client-side Reference/Language Definition|a language addon]]. For example, we could prepare a file called <code>WEB-INF/lang-addon.xml</code> with the following content: |
| − | <source lang=" | + | <source lang="XML" highlight='5'> |
<language-addon> | <language-addon> | ||
<addon-name>myapp</addon-name> | <addon-name>myapp</addon-name> | ||
| Line 77: | Line 86: | ||
<component> | <component> | ||
<component-name>mytemplatecomp</component-name> | <component-name>mytemplatecomp</component-name> | ||
| − | <template-uri>~./template/mytemplate.zul<template-uri> | + | <template-uri>~./template/mytemplate.zul</template-uri> |
</component> | </component> | ||
</language-addon> | </language-addon> | ||
</source> | </source> | ||
| − | + | Next, we could specify this file by adding the following content to <code>WEB-INF/zk.xml</code>: | |
<source lang="xml"> | <source lang="xml"> | ||
<language-config> | <language-config> | ||
| Line 88: | Line 97: | ||
</language-config> | </language-config> | ||
</source> | </source> | ||
| + | |||
| + | Then, we can use it with a custom tag name: | ||
| + | <source lang='xml'> | ||
| + | <mytemplatecomp> | ||
| + | </source> | ||
| + | |||
| + | |||
For more information, please refer to [[ZK Configuration Reference/zk.xml/The language-config Element|ZK Configuration Reference]]. | For more information, please refer to [[ZK Configuration Reference/zk.xml/The language-config Element|ZK Configuration Reference]]. | ||
| − | + | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
{{ZKDevelopersReferencePageFooter}} | {{ZKDevelopersReferencePageFooter}} | ||
Latest revision as of 10:22, 22 January 2024
Apply (Recommended)
Since 8.0.0
We suggest using <apply> instead of Include. Because comparing to Include, it has several advantages:
- Doesn't consume extra memory.
- Because it's a shadow element, it doesn't create a corresponding component at the server side.
- Doesn't render an extra
<div>surrounding its child components at the client-side.Includerenders a<div>to enclose its child components. Sometimes the outer<div>breaks the layout.
- Doesn't create an ID space.
Includeitself is an ID space owner which affects you when locating a component with ZK selector syntax.
- It can render its child components upon parameters dynamically.
- You can pass a parameter with data binding and bind to the parameter. When the parameter's value changes, the content will change accordingly.
Include
Include allows you to include a zul page, an HTML, zhtml, JSP page, or a URL mapped to a servlet. For example,
<include src="another.zul"/>
<include src="another.jsp"/>
When including a ZUML page, the components specified in the ZUML page will become the child components of the Include component.
For example, suppose we have two ZUL pages as follows:
<!-- first.zul -->
<include src="second.zul"/>
and
<!-- second.zul -->
<listbox>
<listitem label="foo"/>
</listbox>
Then, listbox in second.zul will become the child of include in first.zul.
When including a non-ZUML page (such as JSP), the output of the page will be the content of the Include component. Thus, the output must be a valid HTML fragment without <html>, <head>, <body>.
If you prefer to create an independent page (Page), or want to include a page rendered by Richlet while the value of src ends with .zul or .zhtml, you could specify the mode with defer (Include.setMode(String)). Then, include won't have any child. Rather, an instance of Page will be created to hold the content of second.zul or the content generated by Richlet. For more information, please refer to ZK Component Reference: include.
Classpath Web Resource Path
ZK provides a special path URL starting with ~./, it looks for a file under a folder starting with web in a web application's classpath, e.g.
my-module.jar/web/.- WEB-INF/classes/web
So it will get a file under the path among all included jars. You can specify such URL in a component path-related attribute like:
<?component name="another" templateURI="~./another.zul" ?>
<zk>
<vlayout>
apply templateURI:
<apply templateURI="~./another.zul" />
component directive:
<another/>
image src:
<image src="~./zklogo.png" />
</vlayout>
</zk>
Modular Resource Sharing
It can be used as a default shared folder path for a jar. When you create a sub-module project, you can put some shared resources or reusable template zul files under this folder. Then, package the sub-module as a jar and include the sub-module jar in the main project. The main project can easily access those reusable resources by this special URL. Notice that the zul files under this special resource path are publicly accessed with a URL in a browser, you should not put any sensitive data in it.
Application-wide Named <Apply>
Since 8.0.1
If you prefer an application-wide named <apply> element with a predefined templateURI and default parameters, you could specify it in a language addon. For example, we could prepare a file called WEB-INF/lang-addon.xml with the following content:
<language-addon>
<addon-name>myapp</addon-name>
<language-name>xul/html</language-name>
<component>
<component-name>mytemplatecomp</component-name>
<template-uri>~./template/mytemplate.zul</template-uri>
</component>
</language-addon>
Next, we could specify this file by adding the following content to WEB-INF/zk.xml:
<language-config>
<addon-uri>/WEB-INF/lang-addon.xml</addon-uri>
</language-config>
Then, we can use it with a custom tag name:
<mytemplatecomp>
For more information, please refer to ZK Configuration Reference.