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()
. BothafterCompose()
andrecreate()
depends oncompose()
.By default,
compose()
will wire members by use ofSelectors
. In other words, it will wire annotated members the same way asSelectorComposer
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 calledorg.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, AbstractComponent.ForwardInfo, AbstractComponent.TargetInfo
-
-
Field Summary
Fields Modifier and Type Field Description 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
AFTER_CHILD_ADDED, AFTER_CHILD_REMOVED, AFTER_PAGE_ATTACHED, AFTER_PAGE_DETACHED, AFTER_PARENT_CHANGED, CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE
-
-
Constructor Summary
Constructors Constructor Description HtmlMacroComponent()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
afterCompose()
Creates the child components after apply dynamic propertiessetDynamicProperty(java.lang.String, java.lang.Object)
.java.lang.Object
clone()
Clones the component.protected void
compose()
Composes the macro component.java.util.Map<java.lang.String,java.lang.Object>
getDynamicProperties()
Returns all available dynamic properties.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 ofcompose()
.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
addSclass, evalCSSFlex, focus, getAction, getClientAction, getDraggable, getDroppable, getExtraCtrl, getHeight, getHflex, getLeft, getPropertyAccess, getRenderdefer, getSclass, getStyle, getTabindex, getTabindexInteger, getTooltiptext, getTop, getVflex, getWidth, getZclass, getZindex, getZIndex, removeSclass, removeSclass, service, setAction, setClass, setClientAction, setDraggable, setDroppable, setFocus, setHeight, setHeight0, setHeightDirectly, setHflex, setHflex0, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTabindex, setTabindex, setTooltiptext, setTop, setTopDirectly, setVflex, setVflex0, setVflexDirectly, setWidth, setWidth0, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly
-
Methods inherited from class org.zkoss.zk.ui.AbstractComponent
addAnnotation, addCallback, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildAdded, beforeChildRemoved, beforeParentChanged, destroyIndexCacheMap, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableBindingAnnotation, disableClientUpdate, disableHostChanged, enableBindingAnnotation, enableHostChanged, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getCallback, getChildren, getClientAttribute, getClientDataAttribute, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getForwards, getId, getIndexCacheMap, getLastChild, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRedrawCallback, getRoot, getShadowFellowIfAny, getShadowRoots, getShadowVariable, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttributeNames, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, initIndexCacheMap, insertBefore, invalidate, isDisabledHostChanged, isInitialized, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageAttached, onPageDetached, onParentChanged, onWrongValue, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeCallback, removeChild, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, renderPropertiesOnly, replace, response, response, response, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setClientAttribute, setClientDataAttribute, setDefinition, setDefinition, setId, setMold, setPageBefore, setStubonly, setStubonly, setSubBindingAnnotationCount, setTemplate, setVisible, setVisibleDirectly, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, updateSubBindingAnnotationCount, willPassivate, willPassivate, willSerialize, willSerialize
-
Methods inherited from class java.lang.Object
equals, 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, hasAttribute, removeAttribute, removeScopeListener, setAttribute
-
-
-
-
Field Detail
-
_resolvers
protected final java.util.List<VariableResolver> _resolvers
A list of resolvers (never null). A variable resolver is added automatically ifVariableResolver
was annotated.
-
-
Method Detail
-
getWidgetClass
public java.lang.String getWidgetClass()
Returns the component class (a.k.a., widget type), "zk.Macro".- Specified by:
getWidgetClass
in interfaceComponent
- Overrides:
getWidgetClass
in classAbstractComponent
- 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: div (since 7.0.1)
- 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: div (since 7.0.1)
- Since:
- 5.0.3
-
afterCompose
public void afterCompose()
Creates the child components after apply dynamic propertiessetDynamicProperty(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 oncompose()
(rather thanafterCompose()
).- Specified by:
afterCompose
in interfaceAfterCompose
-
compose
protected void compose()
Composes the macro component. It is called byafterCompose()
and others to do the rendering based ongetMacroURI()
.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)
orsetPage(org.zkoss.zk.ui.Page)
calledBy 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 interfaceMacro
-
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 interfaceMacro
- 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 ofcompose()
.
-
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 ofComponentDefinition.newInstance(org.zkoss.zk.ui.Page, java.lang.String)
.
-
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 interfaceComponent
- Overrides:
setParent
in classAbstractComponent
-
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 onlyMacro.isInline()
is true.- Specified by:
setInlineParent
in interfaceMacro
- Parameters:
parent
- the parentbeforeSibling
- 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 interfaceComponent
- Overrides:
setPage
in classAbstractComponent
- 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 classAbstractComponent
-
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 interfaceComponent
- Overrides:
clone
in classHtmlBasedComponent
- 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 interfaceDynamicPropertied
-
getDynamicProperties
public java.util.Map<java.lang.String,java.lang.Object> getDynamicProperties()
Description copied from interface:DynamicPropertied
Returns all available dynamic properties.- Specified by:
getDynamicProperties
in interfaceDynamicPropertied
-
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 interfaceDynamicPropertied
-
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 interfaceDynamicPropertied
- 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.- Overrides:
renderProperties
in classHtmlBasedComponent
- Throws:
java.io.IOException
-
-