Package org.zkoss.zk.ui.metainfo

Interface ComponentDefinition

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      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.
      boolean isShadowElement()
      Returns whether this is a shadow element.
      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

      • getLanguageDefinition

        LanguageDefinition getLanguageDefinition()
        Returns the language definition, or null if it is a temporary 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>
...

        Notice that it is valid to have XML fragment, including XML elements, within the element. For example, 

        <html>
        <ul>
        <li forEach="apple, orange">${each}</li>
        </ul>
        </html>

        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 isChildAllowedInTextAs(). Example, A.

        Since:
        3.0.0
        See Also:
        isChildAllowedInTextAs()

      • isChildAllowedInTextAs

        boolean isChildAllowedInTextAs()
        Returns if a child is allowed in the text-as area. It is meaningful only if 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.

        Since:
        6.0.0
        See Also:
        getTextAs()

      • 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.

      • 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<? extends Component> 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.

      • 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 specified page (Page.getLoadedInterpreters()). Note: this method won't attach the component to the specified page.
        Throws:
        java.lang.ClassNotFoundException - if the class not found

      • addMold

        void addMold​(java.lang.String name,
             java.lang.String widgetClass)
        Adds a mold.
        Parameters:
        name - the mold name.
        widgetClass - the widget class (a.k.a., name). Ignored if null.
        Since:
        5.0.0 (the 2nd argument is the class name of the peer widget)

      • getWidgetClass

        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. The returned widget class includes the package name (JavaScript class).
        Parameters:
        comp - the component used to evaluate EL expression, if any, when retrieving the widget class. Ignored if null.
        moldName - the mold name
        Since:
        5.0.4

      • getDefaultWidgetClass

        java.lang.String getDefaultWidgetClass​(Component comp)
        Returns the default widget class, or null if not available.
        Parameters:
        comp - the component used to evaluate EL expression, if any, when retrieving the widget class. Ignored if null.
        Since:
        5.0.4

      • setDefaultWidgetClass

        void setDefaultWidgetClass​(java.lang.String widgetClass)
        Sets the default widget class.
        Parameters:
        widgetClass - the name of the widget class (JavaScript class), including the package name.
        Since:
        5.0.0

      • hasMold

        boolean hasMold​(java.lang.String name)
        Returns whether the specified mold exists.

      • getMoldNames

        java.util.Collection<java.lang.String> getMoldNames()
        Returns a readonly collection of the names of the mold.

      • 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 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.

        Also notice that, since 5.0.7, custom-attributes are applied automatically in the constructor of AbstractComponent(boolean) (by invoking applyAttributes(org.zkoss.zk.ui.Component), so they are always available no matter this method is called or not.

      • applyAttributes

        void applyAttributes​(Component comp)
        Applies the custom attributes defined in this definition to the specified component.

        It is called automatically in AbstractComponent(boolean), so you rarely need to invoke this method.

        Since:
        5.0.7

      • evalProperties

        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.
        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

        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.