org.zkoss.zk.ui.metainfo
Interface ComponentDefinition

All Superinterfaces:

java.lang.Cloneable

All Known Implementing Classes:

ComponentDefinitionImpl, MacroDefinition

public interface ComponentDefinition
extends java.lang.Cloneable

A component definition. Like class in Java, a ComponentDefinition defines the behavior of a component.

The implementation need NOT to be thread safe, since the caller has to clone(org.zkoss.zk.ui.metainfo.LanguageDefinition, java.lang.String) first if accessed concurrently.

Author:

tomyeh

Field Summary

static ComponentDefinition

ZK Deprecated. As of release 3.5.0, replaced by ZkInfo.

Method Summary

void	addMold(java.lang.String name, ComponentRenderer renderer) Deprecated. As of release 3.5.1, replaced with addMold(String, ComponentRenderer, String).
void	addMold(java.lang.String name, ComponentRenderer renderer, java.lang.String z2cURI) Adds a mold based on ComponentRenderer.
void	addMold(java.lang.String name, java.lang.String moldURI) Deprecated. As of release 3.5.1, replaced with addMold(String, String, String).
void	addMold(java.lang.String name, java.lang.String moldURI, java.lang.String z2cURI) Adds a mold based on an URI.
void	addProperty(java.lang.String name, java.lang.String value) Adds a property initializer.
void	applyProperties(Component comp) Applies the properties and custom attributes defined in this definition to the specified component.
java.lang.Object	clone() Clones this component definition.
ComponentDefinition	clone(LanguageDefinition langdef, java.lang.String name) Clones this definition and assins with the specified language definition and name.
java.util.Map	evalProperties(java.util.Map propmap, Page owner, Component parent) Evaluates and retrieves properties to the specified map.
AnnotationMap	getAnnotationMap() Returns the annotation map defined in this definition, or null if no annotation is ever defined.
java.lang.String	getApply() Returns the apply attribute that is a list of Composer class names or EL expressions returning classes, class names or composer instances, or null if no apply attribute.
java.net.URL	getDeclarationURL() Returns the URL where this component definition is declared, or null if not available.
java.lang.Object	getImplementationClass() Returns the class (Class) or the class name (String) that implements the component.
LanguageDefinition	getLanguageDefinition() Returns the language definition, or null if it is a temporty definition belonging to a page.
java.lang.String	getMacroURI() Returns the macro URI, or null if not a macro.
java.util.Collection	getMoldNames() Returns a readonly collection of mold names supported by this definition.
java.lang.Object	getMoldURI(Component comp, java.lang.String name) Returns the URI (String) or an instance of ComponentRenderer of the mold, or null if no such mold available.
java.lang.String	getName() Returns name of this component definition (never null).
ExValue[]	getParsedApply() Return the parsed expressions of the apply attribute.
java.lang.String	getTextAs() Returns the property name to which the text enclosed within the element (associated with this component definition) is assigned to.
java.lang.String	getZ2CURI(Component comp, java.lang.String name) Returns the URI of the ZCS-to-CSS converter for the specified mold.
boolean	hasMold(java.lang.String name) Returns whether the specified mold exists.
boolean	isBlankPreserved() Returns whether to preserve the blank text.
boolean	isInlineMacro() Returns whether this is an inline macro.
boolean	isInstance(Component comp) Returns whether a component belongs to this definition.
boolean	isMacro() Returns whether this is a macro component.
boolean	isNative() Returns whether this is used for the native namespace.
Component	newInstance(java.lang.Class cls) Creates an component of this definition.
Component	newInstance(Page page, java.lang.String clsnm) Creates an component of this definition.
java.lang.Class	resolveImplementationClass(Page page, java.lang.String clsnm) Resolves and returns the class that implements the component.
void	setApply(java.lang.String apply) Sets the apply attribute that is is a list of Composer class or EL expressions returning classes, class names or composer instances.
void	setImplementationClass(java.lang.Class cls) Sets the class to implements the component.
void	setImplementationClass(java.lang.String clsnm) Sets the class name to implements the component.

Field Detail

ZK

static final ComponentDefinition ZK

Deprecated. As of release 3.5.0, replaced by ZkInfo.

Method Detail

getLanguageDefinition

LanguageDefinition getLanguageDefinition()

Returns the language definition, or null if it is a temporty definition belonging to a page.

getName

java.lang.String getName()

Returns name of this component definition (never null). It is unique in the same language, LanguageDefinition, if it belongs to a language, i.e., getLanguageDefinition() is not null.

getTextAs

java.lang.String getTextAs()

Returns the property name to which the text enclosed within the element (associated with this component definition) is assigned to.

Default: null (means to create a Label component as the child)

For example, if getTextAs() returns null, then a Label component is created as a child of comp with the "Hi Text" value in the following example:

<comp>
  Hi Text
</comp>

In other words, it is equivalent to

<comp>
  <label value="Hi Text"/>
</comp>

On the other hand, if getTextAs() returns a non-empty string, say, "content", then "Hi Text" is assigned to the content property of comp. In other words, it is equivalent to

<comp content="Hi Text"/>
</comp>

It is also the same as

<comp>
  <attribute name="content"/>
  Hi Text
  </attribute>
</comp>

To enable it, you can declare text-as in the component definition in lang.xml or lang-addon.xml:

<component>
  <component-name>html</component-name>
  <text-as>content</text-as>
...

Since:

3.0.0

isBlankPreserved

boolean isBlankPreserved()

Returns whether to preserve the blank text. If false, the blank text (a non-empty string consisting of whitespaces) are ignored. If true, they are converted to a label child.

Default: false.

Since:

3.5.0

isMacro

boolean isMacro()

Returns whether this is a macro component.

See Also:

getMacroURI()

getMacroURI

java.lang.String getMacroURI()

Returns the macro URI, or null if not a macro.

isInlineMacro

boolean isInlineMacro()

Returns whether this is an inline macro. If false, you have to examine isMacro() to see whether it is a regular macro.

isNative

boolean isNative()

Returns whether this is used for the native namespace.

Since:

3.0.0

See Also:

LanguageDefinition.getNativeDefinition()

getImplementationClass

java.lang.Object getImplementationClass()

Returns the class (Class) or the class name (String) that implements the component.

If a string is returned, the real class may depend on which page a component will be created to. Reason: the zscript interpreter is associated with a page and it may define classes upon evaluating a page.

setImplementationClass

void setImplementationClass(java.lang.Class cls)

Sets the class to implements the component.

Note: currently, classes specified in lang.xml or lang-addon.xml must be resolved when loading the files. However, classes specified in a page (by use of class or use attributes) might be resolved later because it might be defined by zscript.

setImplementationClass

void setImplementationClass(java.lang.String clsnm)

Sets the class name to implements the component. Unlike setImplementationClass(Class), the class won't be resolved until ComponentInfo.newInstance(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Component) or getImplementationClass() is used. In other words, the class can be provided later (thru, usually, zscript).

resolveImplementationClass

java.lang.Class resolveImplementationClass(Page page,
                                           java.lang.String clsnm)
                                           throws java.lang.ClassNotFoundException

Resolves and returns the class that implements the component.

Unlike getImplementationClass(), this method will resolve a class name (String) to a class (Class), if necessary. In addition, if the clsnm argument is specified, it is used instead of getImplementationClass(). In other words, it overrides the default class.

Parameters:

clsnm - [optional] If specified, clsnm is used instead of getImplementationClass(). In other words, it overrides the default class.

page - the page to check whether the class is defined in its interpreters. Ignored if null. This method will search the class loader of the current thread. If not found, it will search the interpreters of the specifed page (Page.getLoadedInterpreters()). Note: this method won't attach the component to the specified page.

Throws:

java.lang.ClassNotFoundException - if the class not found

isInstance

boolean isInstance(Component comp)

Returns whether a component belongs to this definition.

If resolveImplementationClass(org.zkoss.zk.ui.Page, java.lang.String) failed to resolve, true is returned!

newInstance

Component newInstance(Page page,
                      java.lang.String clsnm)

Creates an component of this definition.

Note: this method doesn't invoke applyProperties(org.zkoss.zk.ui.Component). It is caller's job to apply these properties if necessary. Since the value of a property might depend on the component tree, it is better to assign the component with a proper parent before calling applyProperties(org.zkoss.zk.ui.Component).

Similarly, this method doesn't attach the component to the specified page. Developers may or may not add it to a page or a parent.

An application developer can invoke UiFactory.newComponent(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Component, org.zkoss.zk.ui.metainfo.ComponentInfo) instead of newInstance(org.zkoss.zk.ui.Page, java.lang.String), since a deployer might customize the way to create components by providing an implementation of UiFactory. In additions, it also invokes applyProperties(org.zkoss.zk.ui.Component) assigning page/parent.

On the other hand, this method is 'low-level'. It simply resolves the implementation class by use of resolveImplementationClass(org.zkoss.zk.ui.Page, java.lang.String), and then uses it to create an instance.

Parameters:

clsnm - [optional] If specified, clsnm is used instead of getImplementationClass(). In other words, it overrides the default class.

page - the page that is used to resolve the implementation class. It is used only this definition is associated with a class name by setImplementationClass(String), or clsnm is not null. Note: this method won't attach the component to the specified page. It can be null if getImplementationClass() returns a Class instance, and clsnm is null.

Returns:

the new component (never null)

newInstance

Component newInstance(java.lang.Class cls)

Creates an component of this definition. Refer to newInstance(Page, String). They are the same except this method accepts the class directly, while newInstance(Page, String) invokes resolveImplementationClass(org.zkoss.zk.ui.Page, java.lang.String) to resolve the class first.

Returns:

the new component (never null)

Since:

3.0.2

addMold

void addMold(java.lang.String name,
             java.lang.String moldURI,
             java.lang.String z2cURI)

Adds a mold based on an URI.

Parameters:

moldURI - an URI of the mold; never null nor empty. If it starts with "class:", the following substring is assumed to be the class name of ComponentRenderer, and then it invokes addMold(String, ComponentRenderer). If not staring with "class:", it is pure an URI, and it may contain XEL expressions.

z2cURI - the URI of ZCS-to-CSS converter. Ignored if null.

Since:

3.5.1

addMold

void addMold(java.lang.String name,
             ComponentRenderer renderer,
             java.lang.String z2cURI)

Adds a mold based on ComponentRenderer.

Parameters:

renderer - a component renderer. It is shared by all component instances belonging to this definition.

z2cURI - the URI of ZCS-to-CSS converter. Ignored if null.

Since:

3.5.1

addMold

void addMold(java.lang.String name,
             java.lang.String moldURI)

Deprecated. As of release 3.5.1, replaced with addMold(String, String, String).

addMold

void addMold(java.lang.String name,
             ComponentRenderer renderer)

Deprecated. As of release 3.5.1, replaced with addMold(String, ComponentRenderer, String).

getMoldURI

java.lang.Object getMoldURI(Component comp,
                            java.lang.String name)

Returns the URI (String) or an instance of ComponentRenderer of the mold, or null if no such mold available. In other words, if a String instance is returned, it is the URI of the mold. If a ComponentRenderer instance is returned, it is the object responsible to handle the generation of the component's output.

If the mold URI contains an expression, it will be evaluated first before returning.

Parameters:

name - the mold name

Returns:

an URI in String, or a ComponentRenderer, as of release 3.0.0

See Also:

AbstractComponent.redraw(java.io.Writer)

getZ2CURI

java.lang.String getZ2CURI(Component comp,
                           java.lang.String name)

Returns the URI of the ZCS-to-CSS converter for the specified mold.

ZCS is ZK cacasding style that allows developers to customize CSS with the component names.

Parameters:

name - the mold name

Since:

3.5.1

hasMold

boolean hasMold(java.lang.String name)

Returns whether the specified mold exists.

getMoldNames

java.util.Collection getMoldNames()

Returns a readonly collection of mold names supported by this definition.

addProperty

void addProperty(java.lang.String name,
                 java.lang.String value)

Adds a property initializer. It will initialize a component when created with is definition.

Parameters:

name - the member name. The component must have a valid setter for it.

value - the value. It might contain expressions (${}).

applyProperties

void applyProperties(Component comp)

Applies the properties and custom attributes defined in this definition to the specified component.

Note: annotations are applied to the component when a component is created. So, this method doesn't and need not to copy them. See also AbstractComponent.AbstractComponent().

evalProperties

java.util.Map evalProperties(java.util.Map propmap,
                             Page owner,
                             Component parent)

Evaluates and retrieves properties to the specified map.

Parameters:

propmap - the map to store the retrieved properties. If null, a HashMap instance is created. (String name, Object value).

owner - the owner page; used if parent is null

parent - the parent

getAnnotationMap

AnnotationMap getAnnotationMap()

Returns the annotation map defined in this definition, or null if no annotation is ever defined.

getApply

java.lang.String getApply()

Returns the apply attribute that is a list of Composer class names or EL expressions returning classes, class names or composer instances, or null if no apply attribute.

Since:

3.6.0

See Also:

getParsedApply()

getParsedApply

ExValue[] getParsedApply()

Return the parsed expressions of the apply attribute.

Since:

3.6.0

See Also:

getApply()

setApply

void setApply(java.lang.String apply)

Sets the apply attribute that is is a list of Composer class or EL expressions returning classes, class names or composer instances.

Parameters:

apply - the attribute this is a list of Composer class or EL expressions El expressions are allowed, but self means the parent, if available; or page, if no parent at all. (Note: the component is not created yet when the apply attribute is evaluated).

Since:

3.6.0

getDeclarationURL

java.net.URL getDeclarationURL()

Returns the URL where this component definition is declared, or null if not available.

Since:

3.0.3

clone

ComponentDefinition clone(LanguageDefinition langdef,
                          java.lang.String name)

Clones this definition and assins with the specified language definition and name.

clone

java.lang.Object clone()

Clones this component definition. You rarely invoke this method directly. Rather, use clone(LanguageDefinition, String).

Note: the caller usually has to change the component name, and then assign to a language definition (LanguageDefinition) or a page definition (PageDefinition).

Returns:

the new component definition by cloning from this definition.