Package com.vaadin.ui.declarative

Class Design

  • All Implemented Interfaces:
    Serializable
    public class Design
extends Object
implements Serializable
    Design is used for reading a component hierarchy from an html string or input stream and, conversely, for writing an html representation corresponding to a given component hierarchy.

    In html form a valid nonempty component hierarchy contains a single root element located under the <body> tag. A hierarchy of components is achieved by nesting other elements under the root element. An empty component hierarchy is represented as no elements under the <body> tag.

    For writing a component hierarchy the root element is specified as a Component parameter or as a DesignContext object containing the root Component. An empty hierarchy can be written by giving a null root Component.

    Since:
    7.4
    Author:
    Vaadin Ltd
    See Also:
    Serialized Form

    • Constructor Detail

      • Design

        public Design()

    • Method Detail

      • setComponentFactory

        public static void setComponentFactory​(Design.ComponentFactory componentFactory)
        Sets the component factory that is used for creating component instances based on fully qualified class names derived from a design file.

        Please note that this setting is global, so care should be taken to avoid conflicting changes.

        Parameters:
        componentFactory - the component factory to set; not null
        Since:
        7.4.1

      • setComponentMapper

        public static void setComponentMapper​(Design.ComponentMapper componentMapper)
        Sets the component mapper that is used for resolving between tag names and component instances.

        Please note that this setting is global, so care should be taken to avoid conflicting changes.

        Parameters:
        componentMapper - the component mapper to set; not null
        Since:
        7.5.0

      • read

        public static DesignContext read​(Component rootComponent)
                          throws DesignException
        Loads a design for the given root component.

        This methods assumes that the component class (or a super class) has been marked with an DesignRoot annotation and will either use the value from the annotation to locate the design file, or will fall back to using a design with the same same as the annotated class file (with an .html extension)

        Any Component type fields in the root component which are not assigned (i.e. are null) are mapped to corresponding components in the design. Matching is done based on field name in the component class and id/local id/caption in the design file.

        The type of the root component must match the root element in the design

        Parameters:
        rootComponent - The root component of the layout
        Returns:
        The design context used in the load operation
        Throws:
        DesignException - If the design could not be loaded

      • read

        public static DesignContext read​(String filename,
                                 Component rootComponent)
                          throws DesignException
        Loads a design from the given file name using the given root component.

        Any Component type fields in the root component which are not assigned (i.e. are null) are mapped to corresponding components in the design. Matching is done based on field name in the component class and id/local id/caption in the design file.

        The type of the root component must match the root element in the design.

        Parameters:
        filename - The file name to load. Loaded from the same package as the root component
        rootComponent - The root component of the layout
        Returns:
        The design context used in the load operation
        Throws:
        DesignException - If the design could not be loaded

      • read

        public static DesignContext read​(InputStream stream,
                                 Component rootComponent)
        Loads a design from the given stream using the given root component. If rootComponent is null, the type of the root node is read from the design.

        Any Component type fields in the root component which are not assigned (i.e. are null) are mapped to corresponding components in the design. Matching is done based on field name in the component class and id/local id/caption in the design file.

        If rootComponent is not null, its type must match the type of the root element in the design

        Parameters:
        stream - The stream to read the design from
        rootComponent - The root component of the layout
        Returns:
        The design context used in the load operation
        Throws:
        DesignException - If the design could not be loaded

      • read

        public static Component read​(InputStream design)
        Loads a design from the given input stream
        Parameters:
        design - The stream to read the design from
        Returns:
        The root component of the design

      • write

        public static void write​(Component component,
                         OutputStream outputStream)
                  throws IOException
        Writes the given component tree in design format to the given output stream.
        Parameters:
        component - the root component of the component tree, null can be used for generating an empty design
        outputStream - the output stream to write the design to. The design is always written as UTF-8
        Throws:
        IOException - if writing fails

      • write

        public static void write​(DesignContext designContext,
                         OutputStream outputStream)
                  throws IOException
        Writes the component, given in the design context, in design format to the given output stream. The design context is used for writing local ids and other information not available in the component tree.
        Parameters:
        designContext - The DesignContext object specifying the component hierarchy and the local id values of the objects. If designContext.getRootComponent() is null, an empty design will be generated.
        outputStream - the output stream to write the design to. The design is always written as UTF-8
        Throws:
        IOException - if writing fails