org.zkoss.zk.ui
Class HtmlMacroComponent

java.lang.Object
  org.zkoss.zk.ui.AbstractComponent
      org.zkoss.zk.ui.HtmlBasedComponent
          org.zkoss.zk.ui.HtmlMacroComponent

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Component, AfterCompose, DynamicPropertied, Macro, Scope, IdSpace, ComponentCtrl

public class HtmlMacroComponent
extends HtmlBasedComponent
implements Macro

The implementation of a macro component for HTML-based clients.

Generally, a macro component is created automatically by ZK loader. If a developer wants to create it manually, it has to instantiate from the correct class, and then invoke afterCompose().

To do additional application-specific tasks, you could override compose(). Both afterCompose() and recreate() depends on compose().

By default, compose() will wire members by use of Selectors. In other words, it will wire annotated members the same way as SelectorComposer does.

If you prefer to wire the members based on the name convention as GenericForwardComposer does (i.e., backward compatible with ZK 5), you could specify a library property called org.zkoss.zk.ui.macro.autowire.convention to true in WEB-INF/zk.xml as follows.

        <library-property>
                <name>org.zkoss.zk.ui.macro.autowire.convention</name>
                <value>true</value>
        </library-property>
 

If you prefer not to wire at all (neither by-selector nor by-convention), you could specify a library property called org.zkoss.zk.ui.macro.autowire.disabled to true in WEB-INF/zk.xml as follows..

        <library-property>
                <name>org.zkoss.zk.ui.macro.autowire.disabled</name>
                <value>true</value>
        </library-property>
 

Author:

tomyeh

See Also:

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

protected java.util.List<VariableResolver>

_resolvers A list of resolvers (never null).

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

_zclass

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

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

Fields inherited from interface org.zkoss.zk.ui.sys.ComponentCtrl

CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE

Constructor Summary

HtmlMacroComponent()

Method Summary

void	afterCompose() Creates the child components after apply dynamic properties setDynamicProperty(java.lang.String, java.lang.Object).
java.lang.Object	clone() Clones the component.
protected void	compose() Composes the macro component.
java.lang.Object	getDynamicProperty(java.lang.String name) Returns the property value of the specified name.
java.lang.String	getEnclosingTag() Returns the name of the enclosing tag for this macro component.
java.lang.String	getMacroURI() Returns the macro URI.
java.lang.String	getWidgetClass() Returns the component class (a.k.a., widget type), "zk.Macro".
boolean	hasDynamicProperty(java.lang.String name) Returns whether a dynamic property is defined.
protected boolean	isChildable() Returns whether this component can have a child.
boolean	isInline() Returns whether this is an inline macro.
void	recreate() Detaches all child components and then recreate them by use of compose().
protected void	renderProperties(ContentRenderer renderer) Renders the content of this component, excluding the enclosing tags and children.
void	setDynamicProperty(java.lang.String name, java.lang.Object value) Sets a property with the specified name and value.
void	setEnclosingTag(java.lang.String tag) Sets the the name of the enclosing tag for this macro component.
boolean	setInlineParent(Component parent, Component beforeSibling) Sets the parent to the given one and insert the children of the inline macro right before the given sibling (beforeSibling).
void	setMacroURI(java.lang.String uri) Sets the macro URI.
void	setPage(Page page) Changes the page.
void	setParent(Component parent) Changes the parent.

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

focus, getAction, getDraggable, getDroppable, getExtraCtrl, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTooltiptext, getTop, getVflex, getWidth, getZclass, getZindex, getZIndex, service, setAction, setClass, setDraggable, setDroppable, setFocus, setHeight, setHeightDirectly, setHflex, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTooltiptext, setTop, setTopDirectly, setVflex, setWidth, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly

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

addAnnotation, addAnnotation, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addScopeListener, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildAdded, beforeChildRemoved, beforeParentChanged, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableClientUpdate, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getChildren, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getStubonly, getTemplate, getTemplateNames, getUuid, getWidgetAttribute, getWidgetAttributeNames, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasFellow, hasFellow, insertBefore, invalidate, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageAttached, onPageDetached, onWrongValue, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, removeScopeListener, render, render, render, replace, response, response, response, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setDefinition, setDefinition, setId, setMold, setPageBefore, setStubonly, setStubonly, setTemplate, setVisible, setVisibleDirectly, setWidgetAttribute, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, willPassivate, willPassivate, willSerialize, willSerialize

Methods inherited from class java.lang.Object

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

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

getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, hasFellow, hasFellow

Methods inherited from interface org.zkoss.zk.ui.ext.Scope

addScopeListener, getAttribute, getAttribute, getAttributes, hasAttribute, hasAttribute, removeAttribute, removeAttribute, removeScopeListener, setAttribute, setAttribute

Field Detail

_resolvers

protected final java.util.List<VariableResolver> _resolvers

A list of resolvers (never null). A variable resolver is added automatically if VariableResolver was annotated.

Constructor Detail

HtmlMacroComponent

public HtmlMacroComponent()

Method Detail

getWidgetClass

public java.lang.String getWidgetClass()

Returns the component class (a.k.a., widget type), "zk.Macro".

Specified by:

getWidgetClass in interface Component

Overrides:

getWidgetClass in class AbstractComponent

Since:

5.0.0

See Also:

Component.setWidgetClass(java.lang.String)

getEnclosingTag

public java.lang.String getEnclosingTag()

Returns the name of the enclosing tag for this macro component.

Default: span

Since:

5.0.3

setEnclosingTag

public void setEnclosingTag(java.lang.String tag)

Sets the the name of the enclosing tag for this macro component.

Default: span

Since:

5.0.3

afterCompose

public void afterCompose()

Creates the child components after apply dynamic properties setDynamicProperty(java.lang.String, java.lang.Object).

If a macro component is created by ZK loader, this method is invoked automatically. Developers rarely need to invoke this method.

Default: it invokes compose() to compose the macro component.

Instead of overriding this method, it is suggested to override compose(), since all other methods depend on compose() (rather than afterCompose()).

Specified by:

afterCompose in interface AfterCompose

compose

protected void compose()

Composes the macro component. It is called by afterCompose() and others to do the rendering based on getMacroURI().

The second invocation is ignored. If you want to recreate child components, use recreate() instead.

If this is an line macro, this method is invoked automatically if setParent(org.zkoss.zk.ui.Component) or setPage(org.zkoss.zk.ui.Page) called

By default, supports auto forward events and wire accessible variables to this component.

Since:

5.0.5

getMacroURI

public java.lang.String getMacroURI()

Description copied from interface: Macro

Returns the macro URI.

If Macro.setMacroURI(java.lang.String) wasn't called, it returns the URI defined in the macro definition.

Specified by:

getMacroURI in interface Macro

setMacroURI

public void setMacroURI(java.lang.String uri)

Description copied from interface: Macro

Sets the macro URI. It affects only this component.

Note: this method calls Macro.recreate() automatically if uri is changed.

Specified by:

setMacroURI in interface Macro

Parameters:

uri - the URI of this macro. If null, the default is used.

recreate

public void recreate()

Detaches all child components and then recreate them by use of compose().

Specified by:

recreate in interface Macro

isInline

public boolean isInline()

Description copied from interface: Macro

Returns whether this is an inline macro. The only way to create an inline macro is by use of ComponentDefinition.newInstance(org.zkoss.zk.ui.Page, java.lang.String).

Specified by:

isInline in interface Macro

setParent

public void setParent(Component parent)

Changes the parent.

Note: if this is an inline macro (isInline()), this method actually changes the parent of all components created from the macro URI. In other word, an inline macro behaves like a controller of the components it created. It doesn't belong to any page or parent. Moreover, compose() is called automatically if it is not called (and this is an inline macro).

Specified by:

setParent in interface Component

Overrides:

setParent in class AbstractComponent

setInlineParent

public boolean setInlineParent(Component parent,
                               Component beforeSibling)

Description copied from interface: Macro

Sets the parent to the given one and insert the children of the inline macro right before the given sibling (beforeSibling).

This method is used only internally.

Notice that when AbstractComponent.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component) is called to insert an inline macro (Macro.isInline()), the invocation will be forwarded to this method. It is called only Macro.isInline() is true.

Specified by:

setInlineParent in interface Macro

Parameters:

parent - the parent

beforeSibling - a child of the parent that the macro component will be inserted before

Returns:

if it has been added successfully

setPage

public void setPage(Page page)

Changes the page.

Note: if this is an inline macro (isInline()), this method actually changes the page of all components created from the macro URI. In other word, an inline macro behaves like a controller of the components it created. It doesn't belong to any page or parent. Moreover, compose() is called automatically if it is not called (and this is an inline macro).

Specified by:

setPage in interface Component

Overrides:

setPage in class AbstractComponent

See Also:

ComponentCtrl.onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page), ComponentCtrl.onPageDetached(org.zkoss.zk.ui.Page)

isChildable

protected boolean isChildable()

Description copied from class: AbstractComponent

Returns whether this component can have a child.

Default: return true (means it can have children).

Overrides:

isChildable in class AbstractComponent

clone

public java.lang.Object clone()

Description copied from interface: Component

Clones the component. All of its children and descendants are cloned. Also, ID are preserved.

Specified by:

clone in interface Component

Overrides:

clone in class HtmlBasedComponent

Returns:

the new component. Notice that it doesn't belong to any page, nor desktop. It doesn't have a parent, either.

hasDynamicProperty

public boolean hasDynamicProperty(java.lang.String name)

Description copied from interface: DynamicPropertied

Returns whether a dynamic property is defined.

Specified by:

hasDynamicProperty in interface DynamicPropertied

getDynamicProperty

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

Description copied from interface: DynamicPropertied

Returns the property value of the specified name.

Specified by:

getDynamicProperty in interface DynamicPropertied

setDynamicProperty

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

Description copied from interface: DynamicPropertied

Sets a property with the specified name and value.

If a component supports only String-type values, it could use org.zkoss.lang.Objects.toString() to convert the value to a String instance.

Specified by:

setDynamicProperty in interface DynamicPropertied

Throws:

WrongValueException

renderProperties

protected void renderProperties(ContentRenderer renderer)
                         throws java.io.IOException

Description copied from class: HtmlBasedComponent

Renders the content of this component, excluding the enclosing tags and children.

See also ZK Client-side Reference: Property Rendering

Overrides:

renderProperties in class HtmlBasedComponent

Throws:

java.io.IOException