Examples of org.zkoss.zul.Include

• org.zkoss.zul.Include
  Includes the result generated by any servlet, not limited to a ZUML page.

  Non-XUL extension.

  If this component is the only child of its parent, the default width and height will become 100%.

  Since 3.6.2, there are three modes: auto (default), instant and defer. The behavior prior to 3.6.2 is the same as the defer mode. The default mode is auto since 5.0. However, you can change it to defer by specifying a library property named org.zkoss.zul.include.mode (for fully backward compatibility).

  The instant mode

  In the instant mode, the page to be included are loaded 'instantly' with {@link Execution#createComponents} when {@link #afterCompose}is called. Furthermore, the components are created as the child components of this include component (like a macro component).

  Notices:

  • The instant mode is supported automatically if the include component is created by a ZUML page. If you want to create it programmingly, you have to invoke {@link #afterCompose}after assigning the source ( {@link #setSrc}).
  • The isntance mode doesn't support {@link #setProgressing} nor{@link #setLocalized}
  • The directives of the included page won't be included. It means <?style?> won't be evaluated. Thus, if you want to embed JavaScript files or codes in a page that might be included, it is better to use the script component ( {@link Script}).

  The defer mode

  In the defer mode (the only mode supported by ZK prior to 3.6.2), the page is included by servlet container (the include method of javax.servlet.RequestDispatcher) in the render phase (i.e., after all components are created). The page can be any servlet; not limited to a ZUML page.

  If it is eventually another ZUML page, a ZK page ( {@link org.zkoss.zk.ui.Page}) is created and added to the current desktop. You can access them only via inter-page API (see {@link org.zkoss.zk.ui.Path}).

  The auto mode (default)

  In the auto mode, the include component decides the mode based on the name specified in the src property ( {@link #setSrc}). If src is ended with the extension named .zul or .zhtml, the instant mode is assumed. Otherwise, the defer mode is assumed. Notice that if a query string is specified, the defer mode is assumed, too.

  Notice that invoking {@link #setProgressing} or {@link #setLocalized}with true will imply the defer mode (if the mode is auto).

  Passing Parameters

  There are two ways to pass parameters to the included page:

  First, since ZK 3.0.4, you can use {@link #setDynamicProperty}, or, in ZUL,

  <include src="/WEB-INF/mypage" arg="something"/>

  Second, you can use the query string:

  <include src="/WEB-INF/mypage?arg=something"/>

  With the query string, you can pass only the String values. and the parameter can be accessed by {@link Execution#getParameter}or javax.servlet.ServletRequest's getParameter. Or, you can access it with the param variable in EL expressions.

  On the other hand, the dynamic properties ( {@link #setDynamicProperty}) are passed to the included page thru the request's attributes You can pass any type of objects you want. In the included page, you can access them by use of {@link Execution#getAttribute} or javax.servlet.ServletRequest'sgetAttribute. Or, you can access with the requestScope variable in EL expressions.

  Macro Component versus {@link Include}

  If the include component is in the instant mode, it is almost the same as a macro component. On the other hand, if in the pag mode, they are different:

  1. {@link Include} (in defer mode) could include anything include ZUML,JSP or any other servlet, while a macro component could embed only a ZUML page.
  2. If {@link Include} (in defer mode) includes a ZUML page, a{@link org.zkoss.zk.ui.Page} instance is created which is ownedby {@link Include}. On the other hand, a macro component makes the created components as the direct children -- i.e., you can browse them with {@link org.zkoss.zk.ui.Component#getChildren}.
  3. {@link Include} (in defer mode) creates components in the Rendering phase,while a macro component creates components in {@link org.zkoss.zk.ui.HtmlMacroComponent#afterCompose}.
  4. {@link Include#invalidate} (in defer mode) will cause it to re-includethe page (and then recreate the page if it includes a ZUML page). However, {@link org.zkoss.zk.ui.HtmlMacroComponent#invalidate} just causes it to redrawand update the content at the client -- like any other component does. To re-create, you have to invoke {@link org.zkoss.zk.ui.HtmlMacroComponent#recreate}.

  In additions to macro and {@link Include}, you can use the fulfill attribute as follows: <div fulfill="=/my/foo.zul">...</div> @author tomyeh @see Iframe