Apply (Recommended)

We suggest using [](http://books.zkoss.org/zk-mvvm-book/8.0/shadow_elements/shadow_elements.html) instead of `Include`. Because comparing to `Include`, it has several advantages:

  1. Doesn’t consume extra memory.

    Because it’s a shadow element, it doesn’t create a corresponding component at the server side.

  2. Doesn’t render an extra <div> surrounding its child components at the client-side.

    Include renders a <div> to enclose its child components. Sometimes the outer <div> breaks the layout.

  3. Doesn’t create an ID space.

    Include itself is an ID space owner which affects you when locating a component with ZK selector syntax.

  4. 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 org.zkoss.zul.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 org.zkoss.zul.Include component. Thus, the output must be a valid HTML fragment without <html>, <head>, <body>.

If you prefer to create an independent page (org.zkoss.zk.ui.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 (org.zkoss.zul.Include#setMode(java.lang.String)). Then, include won’t have any child. Rather, an instance of org.zkoss.zk.ui.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

The ~./ path simplifies sharing resources across projects. For example, when creating a sub-module project, you can store reusable assets such as CSS files, images, JavaScript, or ZUL templates in this path. By packaging the sub-module as a JAR and including it in your main project, the main project can easily access these resources using the ~./ path.

This approach makes it convenient to manage and reuse static resources without duplicating files across projects. However, since files under the ~./ path are publicly accessible, avoid placing sensitive or confidential data in these folders.

Application-wide Named

If you prefer an application-wide named [](http://books.zkoss.org/zk-mvvm-book/8.0/syntax/apply.html) element with a predefined templateURI and default parameters, you could specify it in [a language addon](/zk_client_side_ref/language_definition). 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.