org.zkoss.zul
Class Include

java.lang.Object
  org.zkoss.zk.ui.AbstractComponent
      org.zkoss.zk.ui.HtmlBasedComponent
          org.zkoss.zul.impl.XulElement
              org.zkoss.zul.Include

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, HtmlBasedComponent, Component, DynamicPropertied, Scope, ComponentCtrl, Include, XulElement

public class Include
extends XulElement
implements DynamicPropertied, Include

Includes the result generated by any servlet, not limited to a ZUML page.

Non-XUL extension.

If the servlet is eventually another ZUML page, the page will be added to the current desktop in the rendering phase.

There are two ways to pass parameters to the included page. First, you can use the query string:

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

Second, since ZK 3.0.4, you can use setDynamicProperty(java.lang.String, java.lang.Object), or, in ZUL,

<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 Execution.getParameter(java.lang.String) 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 (setDynamicProperty(java.lang.String, java.lang.Object)) 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 Execution.getAttribute(java.lang.String) or javax.servlet.ServletRequest's getAttribute. Or, you can access with the requestScope variable in EL expressions.

Macro Component versus Include

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

In additions to macro and Include, you can use the fulfill attribute as follows: <div fulfill="=/my/foo.zul">...</div>

Author:

tomyeh

See Also:

Iframe, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.zkoss.zk.ui.HtmlBasedComponent

HtmlBasedComponent.ExtraCtrl

Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent

AbstractComponent.Children

Field Summary

Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent

_zclass, RS_NO_DISPLAY, RS_NO_HEIGHT, RS_NO_WIDTH

Fields inherited from class org.zkoss.zk.ui.AbstractComponent

_visible

Fields inherited from interface org.zkoss.zk.ui.Component

APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE

Constructor Summary

Include()

Include(java.lang.String src)

Method Summary

java.lang.Object	getDynamicProperty(java.lang.String name) Returns the parameter associated with the specified name, or null if not found.
boolean	getProgressing() Returns whether to show the MZul.PLEASE_WAIT message before a long operation.
java.lang.String	getSrc() Returns the src.
boolean	hasDynamicProperty(java.lang.String name) Returns whether a dynamic property is defined.
void	invalidate() Invalidates this component by setting the dirty flag such that it will be redraw the whole content later.
boolean	isChildable() Default: not childable.
boolean	isLocalized() Returns whether the source depends on the current Locale.
void	onEchoInclude() Internal use only.
void	redraw(java.io.Writer out) Redraws this component.
void	setDynamicProperty(java.lang.String name, java.lang.Object value) Adds a dynamic property that will be passed to the included page via the request's attribute.
void	setLocalized(boolean localized) Sets whether the source depends on the current Locale.
void	setProgressing(boolean progressing) Sets whether to show the MZul.PLEASE_WAIT message before a long operation.
void	setSrc(java.lang.String src) Sets the src.

Methods inherited from class org.zkoss.zul.impl.XulElement

getAction, getActionAttrs, getAllOnClickAttrs, getContext, getCtrlKeys, getInnerAttrs, getOuterAttrs, getPopup, getTooltip, setAction, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip

Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent

focus, getAllOnClickAttrs, getDraggable, getDroppable, getHeight, getLeft, getMoldSclass, getRealSclass, getRealStyle, getRealStyleFlags, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZclass, getZindex, getZIndex, newExtraCtrl, setClass, setDraggable, setDroppable, setFocus, setHeight, setLeft, setMoldSclass, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZclass, setZindex, setZIndex

Methods inherited from class org.zkoss.zk.ui.AbstractComponent

addAnnotation, addAnnotation, addEventHandler, addEventListener, addForward, addForward, addForward, addForward, addMoved, addSharedAnnotationMap, addSharedEventHandlerMap, appendAsapAttr, appendAsapAttr, appendChild, applyProperties, clone, containsVariable, detach, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getCommand, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getExtraCtrl, getFellow, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getMoldURI, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, hasFellow, insertBefore, isAsapRequired, isInvalidated, isListenerAvailable, isVisible, newChildren, onChildAdded, onChildRemoved, onDrawNewChild, onPageAttached, onPageDetached, onWrongValue, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, response, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setComponentDefinition, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, smartUpdate, smartUpdate, smartUpdate, smartUpdateDeferred, smartUpdateValues, toString, unsetVariable

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.zkoss.zul.impl.api.XulElement

getAction, getContext, getCtrlKeys, getPopup, getTooltip, setAction, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip

Methods inherited from interface org.zkoss.zk.ui.api.HtmlBasedComponent

focus, getHeight, getLeft, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZclass, getZindex, getZIndex, setDraggable, setDroppable, setFocus, setHeight, setLeft, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZclass, setZindex, setZIndex

Methods inherited from interface org.zkoss.zk.ui.Component

addEventListener, addForward, addForward, addForward, addForward, appendChild, applyProperties, clone, containsVariable, detach, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getDefinition, getDesktop, getFellow, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, insertBefore, isInvalidated, isListenerAvailable, isVisible, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, setAttribute, setAttribute, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, unsetVariable

Constructor Detail

Include

public Include()

Include

public Include(java.lang.String src)

Method Detail

setProgressing

public void setProgressing(boolean progressing)

Sets whether to show the MZul.PLEASE_WAIT message before a long operation. This implementation will automatically use an echo event like Events.echoEvent(String, org.zkoss.zk.ui.Component, String) to suspend the including progress before using the Clients.showBusy(String, boolean) method to show the MZul.PLEASE_WAIT message at client side.

Default: false.

Specified by:

setProgressing in interface Include

Since:

3.0.4

getProgressing

public boolean getProgressing()

Returns whether to show the MZul.PLEASE_WAIT message before a long operation.

Default: false.

Specified by:

getProgressing in interface Include

Since:

3.0.4

onEchoInclude

public void onEchoInclude()

Internal use only.

Specified by:

onEchoInclude in interface Include

Since:

3.0.4

getSrc

public java.lang.String getSrc()

Returns the src.

Default: null.

Specified by:

getSrc in interface Include

setSrc

public void setSrc(java.lang.String src)
            throws WrongValueException

Sets the src.

If src is changed, the whole component is invalidate. Thus, you want to smart-update, you have to override this method.

Specified by:

setSrc in interface Include

Parameters:

src - the source URI. If null or empty, nothing is included. You can specify the source URI with the query string and they will become a parameter that can be accessed by use of Execution.getParameter(java.lang.String) or javax.servlet.ServletRequest's getParameter. For example, if "/a.zul?b=c" is specified, you can access the parameter with ${param.b} in a.zul.

Throws:

WrongValueException

See Also:

setDynamicProperty(java.lang.String, java.lang.Object)

isLocalized

public final boolean isLocalized()

Returns whether the source depends on the current Locale. If true, it will search xxx_en_US.yyy, xxx_en.yyy and xxx.yyy for the proper content, where src is assumed to be xxx.yyy.

Default: false;

setLocalized

public final void setLocalized(boolean localized)

Sets whether the source depends on the current Locale.

hasDynamicProperty

public boolean hasDynamicProperty(java.lang.String name)

Returns whether a dynamic property is defined.

Specified by:

hasDynamicProperty in interface DynamicPropertied

getDynamicProperty

public java.lang.Object getDynamicProperty(java.lang.String name)

Returns the parameter associated with the specified name, or null if not found.

Specified by:

getDynamicProperty in interface DynamicPropertied

Since:

3.0.4

See Also:

setDynamicProperty(java.lang.String, java.lang.Object)

setDynamicProperty

public void setDynamicProperty(java.lang.String name,
                               java.lang.Object value)

Adds a dynamic property that will be passed to the included page via the request's attribute.

For example, if setDynamicProperty("abc", new Integer(4)) is called, then the included page can retrived the abc property by use of ${reqestScope.abc}

Specified by:

setDynamicProperty in interface DynamicPropertied

Since:

3.0.4

invalidate

public void invalidate()

Description copied from interface: Component

Invalidates this component by setting the dirty flag such that it will be redraw the whole content later.

It can be called only in the request-processing and event-processing phases; excluding the redrawing phase.

Specified by:

invalidate in interface Component

Overrides:

invalidate in class AbstractComponent

isChildable

public boolean isChildable()

Default: not childable.

Specified by:

isChildable in interface Component

Overrides:

isChildable in class AbstractComponent

redraw

public void redraw(java.io.Writer out)
            throws java.io.IOException

Description copied from class: AbstractComponent

Redraws this component. This method implements the mold mechanism.

1. It first invokes AbstractComponent.getMoldURI() to retrieve the mold to redraw. The mold is either an URI (String) or a ComponentRenderer instance.
2. If URI, it invokes Execution.include(java.io.Writer, java.lang.String, java.util.Map, int) to generate the output.
3. If a ComponentRenderer instance, ComponentRenderer.render(org.zkoss.zk.ui.Component, java.io.Writer) is called to generate the output.

Specified by:

redraw in interface Component

Overrides:

redraw in class HtmlBasedComponent

Throws:

java.io.IOException