|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface ComponentDefinition
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.
Method Summary | |
---|---|
void |
addMold(java.lang.String name,
java.lang.String widgetClass)
Adds a mold. |
void |
addProperty(java.lang.String name,
java.lang.String value)
Adds a property initializer. |
void |
applyAttributes(Component comp)
Applies the custom attributes defined in this definition to the specified component. |
void |
applyProperties(Component comp)
Applies the properties 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 assigns with the specified language definition and name. |
java.util.Map<java.lang.String,java.lang.Object> |
evalProperties(java.util.Map<java.lang.String,java.lang.Object> 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.String |
getDefaultWidgetClass(Component comp)
Returns the default widget class, 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 temporary definition belonging to a page. |
java.lang.String |
getMacroURI()
Returns the macro URI, or null if not a macro. |
java.util.Collection<java.lang.String> |
getMoldNames()
Returns a readonly collection of the names of the mold. |
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 |
getWidgetClass(Component comp,
java.lang.String moldName)
Returns the widget class associated with specified mold, or the default widget class ( getWidgetClass(org.zkoss.zk.ui.Component, java.lang.String) ) if not available. |
boolean |
hasMold(java.lang.String name)
Returns whether the specified mold exists. |
boolean |
isBlankPreserved()
Returns whether to preserve the blank text. |
boolean |
isChildAllowedInTextAs()
Returns if a child is allowed in the text-as area. |
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<? extends Component> 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 |
setDefaultWidgetClass(java.lang.String widgetClass)
Sets the default widget class. |
void |
setImplementationClass(java.lang.Class<? extends Component> cls)
Sets the class to implements the component. |
void |
setImplementationClass(java.lang.String clsnm)
Sets the class name to implements the component. |
Method Detail |
---|
LanguageDefinition getLanguageDefinition()
java.lang.String getName()
LanguageDefinition
,
if it belongs to a language, i.e.,
getLanguageDefinition()
is not null.
java.lang.String getTextAs()
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 It is also the same as
To enable it, you can declare Notice that it is valid to have XML fragment, including XML elements,
within the element. For example,
If the component allows child components, it is better not to try
XML fragment as the plain text. And then, it shall return true
in
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>
<comp>
<attribute name="content"/>
Hi Text
</attribute>
</comp>
text-as
in
the component definition in lang.xml or lang-addon.xml:
<component>
<component-name>html</component-name>
<text-as>content</text-as>
...
<html>
<ul>
<li forEach="apple, orange">${each}</li>
</ul>
</html>
isChildAllowedInTextAs()
. Example, A
.
isChildAllowedInTextAs()
boolean isChildAllowedInTextAs()
getTextAs()
is not null.
If true, the text enclosed within the element is considered as
text only if there is no other XML element.
For example, <div> in the following example won't be considered as text. Rather, a div component will be created.
<a>
<div>...</div>
</a>
Default: false.
getTextAs()
boolean isBlankPreserved()
Default: false.
boolean isMacro()
getMacroURI()
java.lang.String getMacroURI()
boolean isInlineMacro()
isMacro()
to see whether it
is a regular macro.
boolean isNative()
LanguageDefinition.getNativeDefinition()
java.lang.Object getImplementationClass()
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.
void setImplementationClass(java.lang.Class<? extends Component> cls)
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.
void setImplementationClass(java.lang.String clsnm)
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).
java.lang.Class<?> resolveImplementationClass(Page page, java.lang.String clsnm) throws java.lang.ClassNotFoundException
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.
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 specified
page (Page.getLoadedInterpreters()
).
Note: this method won't attach the component to the specified page.
java.lang.ClassNotFoundException
- if the class not foundboolean isInstance(Component comp)
If resolveImplementationClass(org.zkoss.zk.ui.Page, java.lang.String)
failed to resolve,
true is returned!
Component newInstance(Page page, java.lang.String clsnm)
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, org.zkoss.zk.ui.Component)
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.
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.
Component newInstance(java.lang.Class<? extends Component> cls)
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.
void addMold(java.lang.String name, java.lang.String widgetClass)
name
- the mold name.widgetClass
- the widget class (a.k.a., name).
Ignored if null.java.lang.String getWidgetClass(Component comp, java.lang.String moldName)
getWidgetClass(org.zkoss.zk.ui.Component, java.lang.String)
) if not available.
The returned widget class includes the package name (JavaScript class).
comp
- the component used to evaluate EL expression, if any,
when retrieving the widget class. Ignored if null.moldName
- the mold namejava.lang.String getDefaultWidgetClass(Component comp)
comp
- the component used to evaluate EL expression, if any,
when retrieving the widget class. Ignored if null.void setDefaultWidgetClass(java.lang.String widgetClass)
widgetClass
- the name of the widget class (JavaScript class),
including the package name.boolean hasMold(java.lang.String name)
java.util.Collection<java.lang.String> getMoldNames()
void addProperty(java.lang.String name, java.lang.String value)
name
- the member name. The component must have a valid setter
for it.value
- the value. It might contain expressions (${}).void applyProperties(Component comp)
Note: annotations are applied to the component when a component is created. So, this method doesn't and need not to copy them.
Also notice that, since 5.0.7, custom-attributes are applied automatically
in the constructor of AbstractComponent.AbstractComponent(boolean)
(by invoking applyAttributes(org.zkoss.zk.ui.Component)
,
so they are always available no matter this method is called or not.
void applyAttributes(Component comp)
It is called automatically in
AbstractComponent.AbstractComponent(boolean)
, so
you rarely need to invoke this method.
java.util.Map<java.lang.String,java.lang.Object> evalProperties(java.util.Map<java.lang.String,java.lang.Object> propmap, Page owner, Component parent)
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 nullparent
- the parentAnnotationMap getAnnotationMap()
java.lang.String getApply()
Composer
class
names or EL expressions returning classes, class names or composer
instances, or null if no apply attribute.
getParsedApply()
ExValue[] getParsedApply()
getApply()
void setApply(java.lang.String apply)
Composer
class
or EL expressions returning classes, class names or composer instances.
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).java.net.URL getDeclarationURL()
ComponentDefinition clone(LanguageDefinition langdef, java.lang.String name)
java.lang.Object clone()
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
).
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |