Employment/Purpose

The include component embeds the output generated by another servlet into the current page. The included resource can be any servlet output including JSF, JSP, HTML, or another ZUML page. It enables developers to compose pages from reusable fragments and dynamically load content at runtime.

Common Use Cases

Splitting a large page into reusable fragments

Decompose a complex page into smaller, independently maintainable .zul files:

<vlayout>
    <include src="/WEB-INF/pages/header.zul"/>
    <include src="/WEB-INF/pages/main-content.zul"/>
    <include src="/WEB-INF/pages/footer.zul"/>
</vlayout>

Passing parameters to an included page

Append a query string to src, or set dynamic properties on the component:

<!-- via query string -->
<include src="/WEB-INF/pages/product.zul?id=42"/>

<!-- via dynamic property attributes -->
<include src="/WEB-INF/pages/product.zul" productId="42" readOnly="true"/>

Inside product.zul retrieve the value with ${requestScope.productId}.

Deferring a slow page with a busy indicator

Set progressing="true" on an include whose target page performs expensive server-side work. ZK shows a “Please Wait” message while the page loads:

<include src="/WEB-INF/pages/heavy-report.zul" progressing="true"/>

Dynamically swapping content

Change src at runtime to replace the included content without reloading the whole page:

<include id="contentArea" src="/WEB-INF/pages/home.zul"/>
<button label="Load Settings"
        onClick="contentArea.setSrc('/WEB-INF/pages/settings.zul')"/>

Example

<window title="include demo" border="normal" width="300px">
    Hello, World!
    <include src="/userguide/misc/includedHello.zul" />
    <include src="/html/frag.html?some=any" />
    <include src="mypage" productId="42" other="value" />
</window>

Modes

The include component supports two rendering modes: instant and defer. By default, the mode is auto, which automatically selects the appropriate mode based on the included resource. The included file should not contain an <html> tag.

Instant Mode

In instant mode, components from the included page are instantiated immediately during the current HTTP request and added as children of the include component. No separate Page object is created. This mode works well for lightweight .zul files included on the same page, but does not support query strings or locale-sensitive loading.

<window title="demo" border="normal">
    <include mode="instant" src="include.zul" />
</window>

The include component is an ID space owner, so ID conflicts are avoided. To retrieve child components, use org.zkoss.zk.ui.Path or other path-based techniques.

Defer Mode

In defer mode, the included page is loaded through the servlet container’s RequestDispatcher.include() method after the current page is rendered. A separate Page object is created to hold the included content. This mode supports any servlet output (JSP, HTML, JSF, etc.) and is compatible with query strings, locale-sensitive loading, and the progressing indicator.

<window title="demo" border="normal">
    <include mode="defer" src="include.zul" />
</window>

Defer mode components are only accessible after the page is rendered, typically in event listeners responding to user interactions.

Auto Mode (Default)

The auto mode automatically selects between instant and defer based on the included resource. For .zul, .zhtml, .html, and .xhtml files without a query string, instant mode is used. If a query string is present or for other file types, defer mode is used.

<include src="header.zul" />            <!-- instant mode (no query string) -->
<include src="header.zul?test=5" />     <!-- defer mode (query string present) -->

Backward Compatibility

Prior to ZK 5.0, defer was the default mode. To maintain compatibility, configure the default via a library property:

<library-property>
    <name>org.zkoss.zul.include.mode</name>
    <value>defer</value>
</library-property>

Refresh Included Pages

Change the src property at runtime to replace the included content or reload the same page. Setting a different src value swaps to a new page:

<include id="inner" src="hello.zul"/>
<button label="Bye!" onClick='inner.src = "byebye.zul"'/>

To reload the same page, set src to null first, then back to its original value (ZK optimizes repeated assignments):

<include id="inner" src="hello.zul"/>
<button id="reload" label="Reload" onClick="String tmp=inner.src; inner.src=null; inner.src=tmp;"/>

Alternatively, call invalidate() to force a reload:

<include id="inner" src="hello.zul"/>
<button id="reload" label="Reload" onClick="inner.invalidate();"/>

The invalidate() method works in both instant and defer modes.

Access Components Inside

Since include creates an ID space, access components inside it using org.zkoss.zk.ui.Path or refer to ID Space — Find Component Manually.

Custom Attributes

org.zkoss.zul.include.html.defer

[default: false]
[inherit: true]1

since 5.0.7

Defer rendering of included non-ZUML pages (HTML fragments) until all widgets are instantiated and rendered on the client. By default, non-ZUML content is evaluated immediately, which may cause embedded JavaScript to execute before widgets are ready.

To use, set the custom attribute on the <include> component:

<include src="included.html">
    <custom-attributes org.zkoss.zul.include.html.defer="true"/>
</include>

Properties

Src

Default Value: null

Sets the URI of the page or resource to include. If null or empty, nothing is included. You may append a query string to pass parameters to the included page; those parameters become accessible via ${param.name} or Execution#getParameter in the included file.

<include src="/WEB-INF/pages/sidebar.zul"/>

<!-- With query-string parameters -->
<include src="/WEB-INF/pages/detail.zul?id=42"/>

Note: A query string in src forces defer mode even when mode is set to auto, because instant-mode rendering does not support query strings.

Mode

Default Value: auto

since 3.6.2

Controls how the included page is rendered into the component tree. Accepted values:

Value Meaning
auto ZK selects instant for .zul/.xhtml sources without a query string, and defer otherwise.
instant The included page is composed as a child component in the same HTTP request. Not compatible with localized="true" or progressing="true".
defer The included page is rendered as a separate page object and loaded after the main page. Compatible with localized and progressing.

The behaviour prior to ZK 3.6.2 matches defer.

<include src="/WEB-INF/pages/content.zul" mode="instant"/>
<include src="/WEB-INF/pages/slow.zul"  mode="defer"/>

Progressing

Default Value: false

since 3.0.4

When true, ZK displays a “Please Wait” busy message on the client while the included page is loading. Internally, ZK uses an echo event to defer rendering and then calls Clients.showBusy to show the message.

Setting progressing="true" automatically switches mode from auto to defer if the current resolved mode is auto. It is not compatible with mode="instant".

<include src="/WEB-INF/pages/heavy-report.zul" progressing="true"/>

Localized

Default Value: false

When true, ZK resolves the included file in a locale-sensitive way. Given src="/pages/content.zul", ZK searches for /pages/content_en_US.zul, /pages/content_en.zul, and /pages/content.zul in order, selecting the first match for the current Locale.

Not compatible with mode="instant".

<include src="/WEB-INF/pages/content.zul" localized="true"/>

Comment

Default Value: false

since 5.0.0

When true, the included content is wrapped inside an HTML comment (<!-- … -->). This is useful when including non-HTML content (such as XML or plain text) that must not be interpreted by the browser’s HTML parser.

This attribute is ignored in instant mode.

<include src="/data/feed.xml" comment="true"/>

The above generates:

<div id="z_abc">
<!--
  (content of feed.xml)
-->
</div>

EnclosingTag

Default Value: div

since 7.0.4

Sets the HTML element name used as the wrapper element that ZK renders around the included content. The default is div. Change this to span or another inline element when the surrounding layout requires an inline context.

<include src="/WEB-INF/pages/badge.zul" enclosingTag="span"/>

DynamicProperty

since 3.0.4

Adds a named parameter that is passed to the included page as a request attribute. Inside the included page the value is accessible via EL as ${requestScope.name} or via Execution#getAttribute.

This attribute is set programmatically in Java or a composer rather than as a plain ZUL attribute literal:

<zscript>
    include.setDynamicProperty("orderId", 1001);
    include.setDynamicProperty("readOnly", Boolean.TRUE);
</zscript>
<include id="include" src="/WEB-INF/pages/order-detail.zul"/>

Alternatively, any unknown attribute written directly on the <include> tag in ZUL is treated as a dynamic property:

<include src="/WEB-INF/pages/order-detail.zul" orderId="1001" readOnly="true"/>

Use clearDynamicProperties() in Java to reset all previously set parameters.

ChildPage

Returns (or replaces) the Page object that holds the components rendered by the included source in defer mode. This property is managed by the ZK framework and is generally read-only in application code; you can use it to access or iterate components loaded inside the included page.

The value is null when the component is in instant mode (children live directly under this component) or when nothing has been included yet.

<zscript>
    // Access the child page programmatically after the include has rendered
    org.zkoss.zk.ui.Page pg = myInclude.getChildPage();
    if (pg != null) {
        // iterate or look up components inside the included page
    }
</zscript>
<include id="myInclude" src="/WEB-INF/pages/fragment.zul"/>

Supported Events

Supported Children

*NONE

  1. The custom attribute could be specified in this component, or any of its ancestor. In addition, it could be specified as a library property to enable or disable it for the whole application. ↩