Package org.zkoss.zk.ui.metainfo

Class LanguageDefinition

  • public class LanguageDefinition
extends java.lang.Object
    A definition of a language, such as xul.
    Author:
    tomyeh

    • Field Detail

      • ZK_NAMESPACE

        public static final java.lang.String ZK_NAMESPACE
        The namespace for ZK. It is mainly used to resolve special components and attributes, such as zscript and use.
        See Also:
        Constant Field Values

      • NATIVE_NAMESPACE

        public static final java.lang.String NATIVE_NAMESPACE
        The namespace for ZK native components.
        Since:
        3.0.0
        See Also:
        Constant Field Values

      • CLIENT_NAMESPACE

        public static final java.lang.String CLIENT_NAMESPACE
        The namespace for ZK client (a.k.a., widget). It is used to specify the widget's properties and event listeners.

        Notice that CLIENT_NAMESPACE specifies the property or event listener for a widget, while CLIENT_ATTRIBUTE_NAMESPACE specifies the DOM attributes. In other words, the attribute specified with CLIENT_ATTRIBUTE_NAMESPACE are generated directly.

        Since:
        5.0.0
        See Also:
        Constant Field Values

      • CLIENT_ATTRIBUTE_NAMESPACE

        public static final java.lang.String CLIENT_ATTRIBUTE_NAMESPACE
        The namespace for ZK client attributes. It is used to specify custom DOM attributes.

        Notice that CLIENT_NAMESPACE specifies the property or event listener for a widget, while CLIENT_ATTRIBUTE_NAMESPACE specifies the DOM attributes. In other words, the attribute specified with CLIENT_ATTRIBUTE_NAMESPACE are generated directly.

        You can use it to listen DOM events such as onload and specify browser-specific attributes (such as accessibility related attributes).

        Since:
        5.0.3
        See Also:
        Constant Field Values

      • ANNOTATION_NAMESPACE

        public static final java.lang.String ANNOTATION_NAMESPACE
        The namespace for annotation. It is mainly used to resolve the conflict between a normal value and an annotation.
        Since:
        6.0.0
        See Also:
        Constant Field Values

      • NATIVE_NAMESPACE_PREFIX

        public static final java.lang.String NATIVE_NAMESPACE_PREFIX
        The namespace for ZK native namespace prefix. If a namespace starts with NATIVE_NAMESPACE_PREFIX ("native:"), it means it is also a native space (NATIVE_NAMESPACE but the namespace prefix and uri will be generated.

        For example, 

        <s:svg xmlns:s="native:http://www.w3.org/2000/svg"/>

        generates the following output: 

        <s:svg xmlns:s="http://www.w3.org/2000/svg"/>
        where the prefix s and URI http://www.w3.org/2000/svg are both generated.
        Since:
        3.0.0
        See Also:
        Constant Field Values

      • SHADOW_NAMESPACE

        public static final java.lang.String SHADOW_NAMESPACE
        The namespace for ZK shadow components.
        Since:
        8.0.0
        See Also:
        Constant Field Values

      • SHADOW_NAME

        public static final java.lang.String SHADOW_NAME
        The names of ZK shadow components.
        Since:
        8.0.0
        See Also:
        Constant Field Values

      • CLIENT_ATTRIBUTE_PREFIX_NAMESPACE

        public static final java.lang.String CLIENT_ATTRIBUTE_PREFIX_NAMESPACE
        The namespace for the prefix of ZK client attributes. It is used to specify DOM attributes including the prefix.
        Since:
        9.0.1
        See Also:
        Constant Field Values

      • CLIENT_ATTRIBUTE_PREFIX_NAME

        public static final java.lang.String CLIENT_ATTRIBUTE_PREFIX_NAME
        The name for the prefix of ZK client attributes.
        Since:
        9.0.1
        See Also:
        Constant Field Values

    • Constructor Detail

      • LanguageDefinition

        public LanguageDefinition​(java.lang.String deviceType,
                          java.lang.String name,
                          java.lang.String namespace,
                          java.util.List<java.lang.String> extensions,
                          PageRenderer pageRenderer,
                          boolean ignoreCase,
                          boolean bNative,
                          Locator locator,
                          java.lang.String treeBuilderClass)
        Constructs a language definition.

        Note: the name and namespace of any language cannot be the same. In other words, each language has two names, name and namespace. You can find the language back by either of them via lookup(java.lang.String).

        Parameters:
        deviceType - the device type; never null or empty
        pageRenderer - the page renderer used to render a page; never null.
        ignoreCase - whether the component name is case-insensitive
        bNative - whether it is native (i.e., all tags are Native). If native, the namespaces found in a ZUML page is no longer used to specified a language. Rather, it is output to the client directly.
        treeBuilderClass - a tree builder class for this language (since 8.0.0)
        Since:
        5.0.0

    • Method Detail

      • exists

        public static boolean exists​(java.lang.String name)
        Returns whether the specified language exists.

      • getTreeBuilderClass

        public java.lang.String getTreeBuilderClass()
        Returns the tree builder class for this language
        Since:
        8.0.0

      • lookup

        public static final LanguageDefinition lookup​(java.lang.String name)
        Returns the language definition of the specified name or namespace.

        Note: the name and namespace of any language cannot be the same.

        Parameters:
        name - the name or the namespace; If null or empty, "xul/html" is assumed.
        Throws:
        DefinitionNotFoundException - is thrown if the definition is not found

      • getByExtension

        public static final LanguageDefinition getByExtension​(java.lang.String ext)
        Returns the language definition by specifying an extension.
        Parameters:
        ext - the extension, e.g., "zul". If null, "zul" is assumed.
        Throws:
        DefinitionNotFoundException - is thrown if the definition is not found

      • addExtension

        public static final void addExtension​(java.lang.String ext,
                                      java.lang.String lang)
        Associates an extension to a language.
        Parameters:
        lang - the language name. It cannot be null.
        ext - the extension, e.g., "svg". It cannot be null.
        Since:
        3.0.0

      • getByDeviceType

        public static final java.util.List<LanguageDefinition> getByDeviceType​(java.lang.String deviceType)
        Returns a readonly list of language definitions belong to the specified device type.

        A device type identifies the type of a client. For example, "ajax" represents all Web browsers with Ajax support, while "mil" represents clients that supports Mobile User interface markup Language (on Limited Connected Device, such as mobile phones).

        Parameters:
        deviceType - the device type, e.g., "ajax".
        See Also:
        getDeviceType(), getAll()

      • getDeviceTypes

        public static final java.util.Collection<java.lang.String> getDeviceTypes()
        Returns a readonly collection of all device types.
        See Also:
        getByDeviceType(java.lang.String)

      • getDeviceType

        public java.lang.String getDeviceType()
        Returns the device type that this definition belongs to.

        A device type identifies the type of a client. For example, "ajax" represents all HTML compatible clients (a.k.a., browsers), while "mil" represents clients that supports Mobile Interactive markup Language (on Limited Connected Device, such as mobile phones).

      • isNative

        public boolean isNative()
        Returns whether this is a native language. If true, it means all tags in a ZUML page is considered as native and all namespaces (except ZK namespace) are output the client directly.
        Since:
        3.0.0

      • getName

        public java.lang.String getName()
        Returns name of this language. Each language definition has a unique name and namespace.

      • getNamespace

        public java.lang.String getNamespace()
        Returns the name space. Each language definition has a unique name and namespace.

      • getExtensions

        public java.util.List<java.lang.String> getExtensions()
        Returns the readonly list of extensions that this language definition is associated with (never null).
        Since:
        2.4.1

      • getShadowDefinitions

        public java.util.Collection<ComponentDefinition> getShadowDefinitions()
        Returns a readonly collection of all shadow element definitions in this language.
        Since:
        8.0.0

      • getShadowDefinitionMap

        public ComponentDefinitionMap getShadowDefinitionMap()
        Returns the map of shadow elements defined in this language (never null).

      • getComponentDefinitions

        public java.util.Collection<ComponentDefinition> getComponentDefinitions()
        Returns a readonly collection of all component definitions in this language.
        Since:
        3.6.3

      • getComponentDefinitionMap

        public ComponentDefinitionMap getComponentDefinitionMap()
        Returns the map of components defined in this language (never null).

      • getShadowDefinition

        public ComponentDefinition getShadowDefinition​(java.lang.String name)
        Returns ComponentDefinition of the specified name.

        Note: anonymous shadow element definition won't be returned by this method.

        Parameters:
        name - the name of the shadow element definition.
        Throws:
        DefinitionNotFoundException - is thrown if the definition is not found

      • getShadowDefinition

        public ComponentDefinition getShadowDefinition​(java.lang.Class klass)
        Returns ComponentDefinition of the specified class.

        Note: anonymous shadow element definition won't be returned by this method.

        Parameters:
        klass - the class that implements the shadow element.
        Throws:
        DefinitionNotFoundException - is thrown if the definition is not found
        Since:
        8.0.0

      • getShadowDefinition

        public ComponentDefinition getShadowDefinition​(java.lang.String name,
                                               PageDefinition pgdef,
                                               java.lang.String templateURI)
        Instantiates and returns the component definition for the specified condition.
        Parameters:
        pgdef - the page definition the shadow definition belongs to. If null, it belongs to this language definition.
        Throws:
        java.lang.UnsupportedOperationException - if this language doesn't support the shadows
        Since:
        8.0.0

      • getShadowDefinitionIfAny

        public ComponentDefinition getShadowDefinitionIfAny​(java.lang.Class klass)
        Returns ComponentDefinition of the specified class, or null if not found. It is the same as getShadowDefinition(Class), except this method won't throw any exception.
        Parameters:
        klass - the class that implements the shadow element.
        Since:
        8.6.1

      • hasShadowDefinition

        public boolean hasShadowDefinition​(java.lang.String name)
        Returns whether the specified shadow element is defined.
        Since:
        8.0.0

      • addShadowDefinition

        public void addShadowDefinition​(ComponentDefinition compdef)
        Adds a shadow element definition.

      • getComponentDefinition

        public ComponentDefinition getComponentDefinition​(java.lang.String name)
        Returns ComponentDefinition of the specified name.

        Note: anonymous component definition won't be returned by this method.

        Parameters:
        name - the name of the component definition.
        Throws:
        DefinitionNotFoundException - is thrown if the definition is not found

      • getComponentDefinition

        public ComponentDefinition getComponentDefinition​(java.lang.Class klass)
        Returns ComponentDefinition of the specified class.

        Note: anonymous component definition won't be returned by this method.

        Parameters:
        klass - the class that implements the component.
        Throws:
        DefinitionNotFoundException - is thrown if the definition is not found

      • getComponentDefinitionIfAny

        public ComponentDefinition getComponentDefinitionIfAny​(java.lang.Class klass)
        Returns ComponentDefinition of the specified class, or null if not found. It is the same as getComponentDefinition(Class), except this method won't throw any exception.
        Parameters:
        klass - the class that implements the component.
        Since:
        8.6.1

      • hasComponentDefinition

        public boolean hasComponentDefinition​(java.lang.String name)
        Returns whether the specified component is defined.

      • addComponentDefinition

        public void addComponentDefinition​(ComponentDefinition compdef)
        Adds a component definition.

      • hasWidgetDefinition

        public boolean hasWidgetDefinition​(java.lang.String widgetClass)
        Returns whether the specified widget is defined.
        Parameters:
        widgetClass - the name of the widget class (JavaScript class), including the package name.
        Since:
        5.0.0

      • getWidgetDefinition

        public WidgetDefinition getWidgetDefinition​(java.lang.String widgetClass)
        Returns the widget of the specified class name.
        Parameters:
        widgetClass - the name of the widget class (JavaScript class), including the package name.
        Throws:
        DefinitionNotFoundException - is thrown if the definition is not found
        Since:
        5.0.0

      • getWidgetDefinitionIfAny

        public WidgetDefinition getWidgetDefinitionIfAny​(java.lang.String widgetClass)
        Returns the widget of the specified class name, or null if not found. It is the same as getWidgetDefinition(java.lang.String), except this method won't throw any exception.
        Parameters:
        widgetClass - the name of the widget class (JavaScript class), including the package name.
        Since:
        5.0.0

      • addWidgetDefinition

        public void addWidgetDefinition​(WidgetDefinition wgtdef)
        Adds a widget definition.
        Since:
        5.0.0

      • addInitScript

        public void addInitScript​(java.lang.String zslang,
                          java.lang.String script)
        Adds the script that shall execute when a page's interpreter is initialized. In other words, they are evaluated only once for each page.

        Note: it doesn't test the existence of the specified language, such that you can add the scripting language later.

        Parameters:
        zslang - the scripting language, say, Java.

      • getInitScript

        public java.lang.String getInitScript​(java.lang.String zslang)
        Returns the initial scripts of the specified language, or null if no script.

      • addEachTimeScript

        public void addEachTimeScript​(java.lang.String zslang,
                              java.lang.String script)
        Adds the script that shall execute each time before evaluating zscript.

        Note: it doesn't test the existence of the specified language, such that you can add the scripting language later.

        Parameters:
        zslang - the scripting language, say, Java.

      • getEachTimeScript

        public java.lang.String getEachTimeScript​(java.lang.String zslang)
        Returns the each-time scripts of the specified language, or null if no scripts.

        The each-time script is evaluated each time before evaluating zscript.

      • addJavaScript

        public void addJavaScript​(JavaScript js)
        Adds a JavaScript required by this language.

      • getJavaScripts

        public java.util.Collection<JavaScript> getJavaScripts()
        Returns a readonly list of all JavaScript required by this language.

      • mergeJavaScriptPackage

        public void mergeJavaScriptPackage​(java.lang.String pkgFrom,
                                   java.lang.String pkgTo)
        Merge a JavaScript package, say pkgFrom, to another package, say pkgTo, such that, when loading pkgTo, pkgFrom will be placed in the same WPD file. Thus, the number of WPD fields to load will be reduced, and the load time will be improved.

        Notice that

        • pkgTo shall be a package that will be pre-loaded, i.e., they will be loaded when a ZUML page is loaded.
        Parameters:
        pkgFrom - the package name, such as "foo.fly", that will be merged to pkgTo
        pkgTo - the target package, such as "zk" and "zul.lang", that will contain the code from pkgFrom.
        Since:
        6.0.0

      • getMergedJavaScriptPackages

        public java.util.Collection<java.lang.String> getMergedJavaScriptPackages​(java.lang.String pkg)
        Returns a list of JavaScript packages that are merged the given package, such as "zk" and "zul.lang".
        Since:
        6.0.0

      • getJavaScriptPackagesWithMerges

        public java.util.Set<java.lang.String> getJavaScriptPackagesWithMerges()
        Returns a readonly collection of the packages that will be merged by other packages.
        Since:
        6.0.0

      • addJavaScriptModule

        public void addJavaScriptModule​(java.lang.String name,
                                java.lang.String version)
        Adds the definition of a JavaScript module to this language.

        A JavaScript module represents a JavaScript file. This definition is mainly used to define its version, such that ZK could encode its URL such that browsers know when to reload it.

      • getJavaScriptModules

        public java.util.Map<java.lang.String,​java.lang.String> getJavaScriptModules()
        Returns a readonly map of definitions of JavaScript modules, (String name, String version).

      • addStyleSheet

        public void addStyleSheet​(StyleSheet ss)
        Adds a StyleSheet required by this language.

      • getStyleSheets

        public java.util.Collection<StyleSheet> getStyleSheets()
        Returns a readonly list of all StyleSheet required by this language.

      • isCaseInsensitive

        public boolean isCaseInsensitive()
        Returns whether the component names are case-insensitive.

      • getPageRenderer

        public PageRenderer getPageRenderer()
        Returns the page render for this language.
        Since:
        5.0.0

      • addMessageLoader

        public void addMessageLoader​(MessageLoader loader)
        Adds a MessageLoader
        Since:
        5.0.11

      • getMessageLoaders

        public java.util.Collection<MessageLoader> getMessageLoaders()
        Returns the message loader for this language.
        Since:
        5.0.11

      • setMacroTemplate

        public void setMacroTemplate​(java.lang.Class<? extends Component> klass)
        Sets the macro template.
        Since:
        5.0.0

      • getMacroDefinition

        public ComponentDefinition getMacroDefinition​(java.lang.String name,
                                              java.lang.String macroURI,
                                              boolean inline,
                                              PageDefinition pgdef)
        Instantiates and returns the component definition for the specified condition.
        Parameters:
        pgdef - the page definition the macro definition belongs to. If null, it belongs to this language definition.
        macroURI - the ZUML page's URI that is used to render instances of this macro definition.
        Throws:
        java.lang.UnsupportedOperationException - if this language doesn't support the macros
        Since:
        3.0.0

      • setShadowTemplate

        public void setShadowTemplate​(java.lang.Class<? extends Component> klass)
        Sets the shadow template.
        Since:
        8.0.0

      • setNativeTemplate

        public void setNativeTemplate​(java.lang.Class<? extends Component> klass)
        Sets the native template.
        Since:
        3.0.0

      • getNativeDefinition

        public ComponentDefinition getNativeDefinition()
        Returns the component definition for the native components.
        Throws:
        java.lang.UnsupportedOperationException - if this language doesn't support the native namespace
        Since:
        3.0.0

      • newLabelInfo

        public ComponentInfo newLabelInfo​(NodeInfo parent,
                                  java.lang.String text)
        Constructs and returns an ComponentInfo for the specified parent and text.
        Since:
        6.0.0

      • isRawLabel

        public boolean isRawLabel()
        Returns whether this language prefers the raw label. By raw labels we mean the text shall not be trimmed and shall be generated directly to the output (rather than wrapping with, say, SPAN).

      • getLabelAttribute

        public java.lang.String getLabelAttribute()
        Returns the label attribute of the label template in the language setting.
        Since:
        8.0.0

      • setDynamicTagInfo

        public void setDynamicTagInfo​(java.lang.String compnm,
                              java.util.Set<java.lang.String> reservedAttrs)
        Adds the definition for the dynamic tag.
        Parameters:
        compnm - the component name used to represent any of dynamic tags for this language. If null, it means this language definition doesn't support the dynamic tag.
        reservedAttrs - a set of reserved attributes that the dynamic tag support. The reserved attributes are the if, unless and use attributes.

      • getDynamicTagDefinition

        public ComponentDefinition getDynamicTagDefinition()
        Returns the component definition of the dynamic tag, or null if this language doesn't support the dynamic tag.
        Throws:
        DefinitionNotFoundException - is thrown if the definition is not found

      • isDynamicReservedAttributes

        public boolean isDynamicReservedAttributes​(java.lang.String attr)
        Returns whether a reserved attribute is used by the dynamic tag (getDynamicTagDefinition()).

      • addTaglib

        public void addTaglib​(Taglib taglib)
        Adds a tag lib.

      • getEvaluator

        public Evaluator getEvaluator()
        Returns the evaluator based on this language definition (never null).
        Since:
        3.0.0

      • getEvaluatorRef

        public EvaluatorRef getEvaluatorRef()
        Returns the evaluator reference (never null).

        This method is used only for implementation only.

        Since:
        3.0.0

      • addCSSURI

        public void addCSSURI​(java.lang.String cssURI)
        Adds the URI of a CSS file that is part of this language.
        Parameters:
        cssURI - the URI of a CSS file
        Since:
        5.0.0

      • getCSSURIs

        public java.util.Collection<java.lang.String> getCSSURIs()
        Returns a readonly collection of the URIs of CSS files of this language.
        Since:
        5.0.0

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object