Package org.zkoss.zk.ui.metainfo

Class LanguageDefinition

java.lang.Object
org.zkoss.zk.ui.metainfo.LanguageDefinition
public class LanguageDefinition extends Object
A definition of a language, such as xul.
Author:
tomyeh

  • Field Details

    • ZK_NAMESPACE

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

    • NATIVE_NAMESPACE

      public static final String NATIVE_NAMESPACE
      The namespace for ZK native components.
      Since:
      3.0.0
      See Also:

    • CLIENT_NAMESPACE

      public static final 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:

    • CLIENT_ATTRIBUTE_NAMESPACE

      public static final 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:

    • ANNOTATION_NAMESPACE

      public static final 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:

    • NATIVE_NAMESPACE_PREFIX

      public static final 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:

    • SHADOW_NAMESPACE

      public static final String SHADOW_NAMESPACE
      The namespace for ZK shadow components.
      Since:
      8.0.0
      See Also:

    • SHADOW_NAME

      public static final String SHADOW_NAME
      The names of ZK shadow components.
      Since:
      8.0.0
      See Also:

    • CLIENT_ATTRIBUTE_PREFIX_NAMESPACE

      public static final 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:

    • CLIENT_ATTRIBUTE_PREFIX_NAME

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

  • Constructor Details

    • LanguageDefinition

      public LanguageDefinition(String deviceType, String name, String namespace, List<String> extensions, PageRenderer pageRenderer, boolean ignoreCase, boolean bNative, org.zkoss.util.resource.Locator locator, 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 Details

    • exists

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

    • getTreeBuilderClass

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

    • lookup

      public static final LanguageDefinition lookup(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(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(String ext, 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 List<LanguageDefinition> getByDeviceType(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:

    • getAll

      public static final List<LanguageDefinition> getAll()
      Returns a readonly list of all language definitions regardless of the device type.
      Since:
      2.4.1
      See Also:

    • getDeviceTypes

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

    • getDeviceType

      public 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 String getName()
      Returns name of this language. Each language definition has a unique name and namespace.

    • getNamespace

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

    • getExtensions

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

    • getShadowDefinitions

      public 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 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(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(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(String name, PageDefinition pgdef, 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:
      UnsupportedOperationException - if this language doesn't support the shadows
      Since:
      8.0.0

    • getShadowDefinitionIfAny

      public ComponentDefinition getShadowDefinitionIfAny(String name)
      Returns ComponentDefinition of the specified name, or null if not found. It is the same as getShadowDefinition(java.lang.String), except this method won't throw any exception.
      Parameters:
      name - the name of the shadow element definition.
      Since:
      8.0.0

    • getShadowDefinitionIfAny

      public ComponentDefinition getShadowDefinitionIfAny(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(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(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(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(String name)
      Returns ComponentDefinition of the specified name, or null if not found. It is the same as getComponentDefinition(java.lang.String), except this method won't throw any exception.
      Parameters:
      name - the name of the component definition.
      Since:
      3.0.2

    • getComponentDefinitionIfAny

      public ComponentDefinition getComponentDefinitionIfAny(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(String name)
      Returns whether the specified component is defined.

    • addComponentDefinition

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

    • hasWidgetDefinition

      public boolean hasWidgetDefinition(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(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(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(String zslang, 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 String getInitScript(String zslang)
      Returns the initial scripts of the specified language, or null if no script.

    • addEachTimeScript

      public void addEachTimeScript(String zslang, 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 String getEachTimeScript(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(org.zkoss.html.JavaScript js)
      Adds a JavaScript required by this language.

    • removeJavaScript

      public void removeJavaScript(String src)
      Removes a JavaScript of the give source required by this language.
      Since:
      5.0.4
      See Also:

    • getJavaScripts

      public Collection<org.zkoss.html.JavaScript> getJavaScripts()
      Returns a readonly list of all JavaScript required by this language.

    • mergeJavaScriptPackage

      public void mergeJavaScriptPackage(String pkgFrom, 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

    • unmergeJavaScriptPackage

      public boolean unmergeJavaScriptPackage(String pkgFrom, String pkgTo)
      Undo the merge of a JavaScript package to another.
      Since:
      6.0.0
      See Also:

    • getMergedJavaScriptPackages

      public Collection<String> getMergedJavaScriptPackages(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 Set<String> getJavaScriptPackagesWithMerges()
      Returns a readonly collection of the packages that will be merged by other packages.
      Since:
      6.0.0

    • addJavaScriptModule

      public void addJavaScriptModule(String name, 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 Map<String,String> getJavaScriptModules()
      Returns a readonly map of definitions of JavaScript modules, (String name, String version).

    • addStyleSheet

      public void addStyleSheet(org.zkoss.html.StyleSheet ss)
      Adds a StyleSheet required by this language.

    • getStyleSheets

      public Collection<org.zkoss.html.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 Collection<MessageLoader> getMessageLoaders()
      Returns the message loader for this language.
      Since:
      5.0.11

    • setMacroTemplate

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

    • getMacroDefinition

      public ComponentDefinition getMacroDefinition(String name, 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:
      UnsupportedOperationException - if this language doesn't support the macros
      Since:
      3.0.0

    • setShadowTemplate

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

    • setNativeTemplate

      public void setNativeTemplate(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:
      UnsupportedOperationException - if this language doesn't support the native namespace
      Since:
      3.0.0

    • setLabelTemplate

      public void setLabelTemplate(String compName, String propName, boolean raw)
      Sets the component and attribute names used to represent a label. Since label is used a lot in a page, there is a simple way to create an ComponentInfo by calling newLabelInfo(org.zkoss.zk.ui.metainfo.NodeInfo, java.lang.String).

      To be able to call newLabelInfo(org.zkoss.zk.ui.metainfo.NodeInfo, java.lang.String), this method must be called to define the component and attribute names used to create an ComponentInfo for a label.

    • newLabelInfo

      public ComponentInfo newLabelInfo(NodeInfo parent, 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 String getLabelAttribute()
      Returns the label attribute of the label template in the language setting.
      Since:
      8.0.0

    • setDynamicTagInfo

      public void setDynamicTagInfo(String compnm, Set<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(String attr)
      Returns whether a reserved attribute is used by the dynamic tag (getDynamicTagDefinition()).

    • addTaglib

      public void addTaglib(org.zkoss.xel.taglib.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(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 Collection<String> getCSSURIs()
      Returns a readonly collection of the URIs of CSS files of this language.
      Since:
      5.0.0

    • toString

      public String toString()
      Overrides:
      toString in class Object