Package com.vaadin.ui.declarative

Class DesignContext

  • All Implemented Interfaces:
    Serializable
    public class DesignContext
extends Object
implements Serializable
    This class contains contextual information that is collected when a component tree is constructed based on HTML design template. This information includes mappings from local ids, global ids and captions to components , as well as a mapping between prefixes and package names (such as "vaadin" -> "com.vaadin.ui"). Versions prior to 7.6 use "v" as the default prefix. Versions starting with 7.6 support reading designs with either "v" or "vaadin" as the prefix, but only write "vaadin" by default. Writing with the legacy prefix can be activated with the property or context parameter Constants.SERVLET_PARAMETER_LEGACY_DESIGN_PREFIX.
    Since:
    7.4
    Author:
    Vaadin Ltd
    See Also:
    Serialized Form

    • Constructor Detail

      • DesignContext

        public DesignContext​(org.jsoup.nodes.Document doc)

      • DesignContext

        public DesignContext()

    • Method Detail

      • getComponentByLocalId

        public Component getComponentByLocalId​(String localId)
        Returns a component having the specified local id. If no component is found, returns null.
        Parameters:
        localId - The local id of the component
        Returns:
        a component whose local id equals localId

      • getComponentById

        public Component getComponentById​(String globalId)
        Returns a component having the specified global id. If no component is found, returns null.
        Parameters:
        globalId - The global id of the component
        Returns:
        a component whose global id equals globalId

      • getComponentByCaption

        public Component getComponentByCaption​(String caption)
        Returns a component having the specified caption. If no component is found, returns null.
        Parameters:
        caption - The caption of the component
        Returns:
        a component whose caption equals the caption given as a parameter

      • setComponentLocalId

        public boolean setComponentLocalId​(Component component,
                                   String localId)
        Creates a mapping between the given local id and the component. Returns true if localId was already mapped to some component or if component was mapped to some string. Otherwise returns false. If the string was mapped to a component c different from the given component, the mapping from c to the string is removed. Similarly, if component was mapped to some string s different from localId, the mapping from s to component is removed.
        Parameters:
        component - The component whose local id is to be set.
        localId - The new local id of the component.
        Returns:
        true, if there already was a local id mapping from the string to some component or from the component to some string. Otherwise returns false.
        Since:
        7.5.0

      • getComponentLocalId

        public String getComponentLocalId​(Component component)
        Returns the local id for a component.
        Parameters:
        component - The component whose local id to get.
        Returns:
        the local id of the component, or null if the component has no local id assigned
        Since:
        7.5.0

      • addPackagePrefix

        public void addPackagePrefix​(String prefix,
                             String packageName)
        Creates a two-way mapping between a prefix and a package name. Note that modifying the mapping for "com.vaadin.ui" may invalidate the backwards compatibility mechanism supporting reading such components with either "v" or "vaadin" as prefix.
        Parameters:
        prefix - the prefix name without an ending dash (for instance, "vaadin" is by default used for "com.vaadin.ui")
        packageName - the name of the package corresponding to prefix
        Since:
        7.5.0
        See Also:
        getPackagePrefixes(), getPackagePrefix(String), getPackage(String)

      • getPackagePrefix

        public String getPackagePrefix​(String packageName)
        Gets the prefix mapping for a given package, or null if there is no mapping for the package.
        Parameters:
        packageName - the package name to get a prefix for
        Returns:
        the prefix for the package, or null if no prefix is registered
        Since:
        7.5.0
        See Also:
        addPackagePrefix(String, String), getPackagePrefixes()

      • getPackagePrefixes

        public Collection<String> getPackagePrefixes()
        Gets all registered package prefixes.
        Returns:
        a collection of package prefixes
        Since:
        7.5.0
        See Also:
        getPackage(String)

      • getPackage

        public String getPackage​(String prefix)
        Gets the package corresponding to the give prefix, or null no package has been registered for the prefix.
        Parameters:
        prefix - the prefix to find a package for
        Returns:
        the package prefix, or null if no package is registered for the provided prefix
        Since:
        7.5.0
        See Also:
        addPackagePrefix(String, String)

      • getDefaultInstance

        public <T> T getDefaultInstance​(Component component)
        Returns the default instance for the given class. The instance must not be modified by the caller.
        Type Parameters:
        T - a component class
        Parameters:
        component - the component that determines the class
        Returns:
        the default instance for the given class. The return value must not be modified by the caller

      • readPackageMappings

        protected void readPackageMappings​(org.jsoup.nodes.Document doc)
        Reads and stores the mappings from prefixes to package names from meta tags located under <head> in the html document.
        Parameters:
        doc - the document

      • writePackageMappings

        public void writePackageMappings​(org.jsoup.nodes.Document doc)
        Writes the package mappings (prefix -> package name) of this object to the specified document.

        The prefixes are stored as <meta> tags under <head> in the document.

        Parameters:
        doc - the Jsoup document tree where the package mappings are written

      • isLegacyPrefixEnabled

        protected boolean isLegacyPrefixEnabled()
        Check whether the legacy prefix "v" or the default prefix "vaadin" should be used when writing designs. The property or context parameter Constants.SERVLET_PARAMETER_LEGACY_DESIGN_PREFIX can be used to switch to the legacy prefix.
        Returns:
        true to use the legacy prefix, false by default
        Since:
        7.5.7

      • createElement

        public org.jsoup.nodes.Element createElement​(Component childComponent)
        Creates an html tree node corresponding to the given element. Also initializes its attributes by calling writeDesign. As a result of the writeDesign() call, this method creates the entire subtree rooted at the returned Node.
        Parameters:
        childComponent - The component with state that is written in to the node
        Returns:
        An html tree node corresponding to the given component. The tag name of the created node is derived from the class name of childComponent.

      • readDesign

        public Component readDesign​(org.jsoup.nodes.Element componentDesign)
        Reads the given design node and creates the corresponding component tree.
        Parameters:
        componentDesign - The design element containing the description of the component to be created.
        Returns:
        the root component of component tree

      • readDesign

        public void readDesign​(org.jsoup.nodes.Element componentDesign,
                       Component component)
        Reads the given design node and populates the given component with the corresponding component tree.

        Additionally registers the component id, local id and caption of the given component and all its children in the context

        Parameters:
        componentDesign - The design element containing the description of the component to be created
        component - The component which corresponds to the design element

      • getRootComponent

        public Component getRootComponent()
        Returns the root component of a created component hierarchy.
        Returns:
        the root component of the hierarchy

      • setRootComponent

        public void setRootComponent​(Component rootComponent)
        Sets the root component of a created component hierarchy.
        Parameters:
        rootComponent - the root component of the hierarchy

      • addComponentCreationListener

        public Registration addComponentCreationListener​(DesignContext.ComponentCreationListener listener)
        Adds a component creation listener. The listener will be notified when components are created while parsing a design template
        Parameters:
        listener - the component creation listener to be added
        Returns:
        a registration object for removing the listener

      • shouldWriteChildren

        public boolean shouldWriteChildren​(Component c,
                                   Component defaultC)
        Helper method for component write implementors to determine whether their children should be written out or not.
        Parameters:
        c - The component being written
        defaultC - The default instance for the component
        Returns:
        whether the children of c should be written

      • shouldWriteData

        public boolean shouldWriteData​(Component component)
        Determines whether the container data of a component should be written out by delegating to a ShouldWriteDataDelegate. The default delegate assumes that all component data is provided by a data provider connected to a back end system and that the data should thus not be written.
        Parameters:
        component - the component to check
        Returns:
        true if container data should be written out for the provided component; otherwise false.
        Since:
        7.5.0
        See Also:
        setShouldWriteDataDelegate(ShouldWriteDataDelegate)

      • getCustomAttributes

        public Map<String,​String> getCustomAttributes​(Component component)
        Gets the attributes that the component did not handle.
        Parameters:
        component - the component to get the attributes for
        Returns:
        map of the attributes which were not recognized by the component
        Since:
        7.7

      • setCustomAttribute

        public void setCustomAttribute​(Component component,
                               String attribute,
                               String value)
        Sets a custom attribute not handled by the component. These attributes are directly written to the component tag.
        Parameters:
        component - the component to set the attribute for
        attribute - the attribute to set
        value - the value of the attribute
        Since:
        7.7

      • setShouldWriteDefaultValues

        public void setShouldWriteDefaultValues​(boolean value)
        Set whether default attribute values should be written by the DesignAttributeHandler#writeAttribute(String, Attributes, Object, Object, Class, DesignContext) method. Default is false.
        Parameters:
        value - true to write default values of attributes, false to disable writing of default values
        Since:
        8.0

      • shouldWriteDefaultValues

        public boolean shouldWriteDefaultValues()
        Determines whether default attribute values should be written by the DesignAttributeHandler#writeAttribute(String, Attributes, Object, Object, Class, DesignContext) method. Default is false.
        Returns:
        true if default values of attributes should be written, otherwise false
        Since:
        8.0