com.vaadin.ui.declarative

Class DesignContext

java.lang.Object

com.vaadin.ui.declarative.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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	DesignContext.ComponentCreatedEvent Component creation event that is fired when a component is created in the context
static interface	DesignContext.ComponentCreationListener Interface to be implemented by component creation listeners

Field Summary

Fields

Modifier and Type	Field and Description
static String	CAPTION_ATTRIBUTE
static String	ID_ATTRIBUTE
static String	LOCAL_ID_ATTRIBUTE

Constructor Summary

Constructors

Constructor and Description
DesignContext()
DesignContext(org.jsoup.nodes.Document doc)

Method Summary

Modifier and Type	Method and Description
void	addComponentCreationListener(DesignContext.ComponentCreationListener listener) Adds a component creation listener.
void	addPackagePrefix(String prefix, String packageName) Creates a two-way mapping between a prefix and a package name.
org.jsoup.nodes.Element	createElement(Component childComponent) Creates an html tree node corresponding to the given element.
Component	getComponentByCaption(String caption) Returns a component having the specified caption.
Component	getComponentById(String globalId) Returns a component having the specified global id.
Component	getComponentByLocalId(String localId) Returns a component having the specified local id.
String	getComponentLocalId(Component component) Returns the local id for a component.
Map<String,String>	getCustomAttributes(Component component) Gets the attributes that the component did not handle
<T> T	getDefaultInstance(Component component) Returns the default instance for the given class.
String	getPackage(String prefix) Gets the package corresponding to the give prefix, or null no package has been registered for the prefix
String	getPackagePrefix(String packageName) Gets the prefix mapping for a given package, or null if there is no mapping for the package.
Collection<String>	getPackagePrefixes() Gets all registered package prefixes.
Component	getRootComponent() Returns the root component of a created component hierarchy.
ShouldWriteDataDelegate	getShouldWriteDataDelegate() Gets the delegate that determines whether the container data of a component should be written out.
protected boolean	isLegacyPrefixEnabled() Check whether the legacy prefix "v" or the default prefix "vaadin" should be used when writing designs.
Component	readDesign(org.jsoup.nodes.Element componentDesign) Reads the given design node and creates the corresponding component tree
void	readDesign(org.jsoup.nodes.Element componentDesign, Component component) Reads the given design node and populates the given component with the corresponding component tree
protected void	readPackageMappings(org.jsoup.nodes.Document doc) Reads and stores the mappings from prefixes to package names from meta tags located under in the html document.
void	removeComponentCreationListener(DesignContext.ComponentCreationListener listener) Removes a component creation listener.
boolean	setComponentLocalId(Component component, String localId) Creates a mapping between the given local id and the component.
void	setCustomAttribute(Component component, String attribute, String value) Sets a custom attribute not handled by the component.
void	setRootComponent(Component rootComponent) Sets the root component of a created component hierarchy.
void	setShouldWriteDataDelegate(ShouldWriteDataDelegate shouldWriteDataDelegate) Sets the delegate that determines whether the container data of a component should be written out.
boolean	shouldWriteChildren(Component c, Component defaultC) Helper method for component write implementors to determine whether their children should be written out or not
boolean	shouldWriteData(Component component) Determines whether the container data of a component should be written out by delegating to a ShouldWriteDataDelegate.
void	writePackageMappings(org.jsoup.nodes.Document doc) Writes the package mappings (prefix -> package name) of this object to the specified document.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ID_ATTRIBUTE

public static final String ID_ATTRIBUTE

See Also:

Constant Field Values

CAPTION_ATTRIBUTE

public static final String CAPTION_ATTRIBUTE

See Also:

Constant Field Values

LOCAL_ID_ATTRIBUTE

public static final String LOCAL_ID_ATTRIBUTE

See Also:

Constant Field Values

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 may invalidate the backwards compatibility mechanism supporting reading such components with either or 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.

Parameters:

abstractComponent -

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 in the html 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 tags under 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 void 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

removeComponentCreationListener

public void removeComponentCreationListener(DesignContext.ComponentCreationListener listener)

Removes a component creation listener.

Parameters:

listener - the component creation listener to be removed

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 source 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)

setShouldWriteDataDelegate

public void setShouldWriteDataDelegate(ShouldWriteDataDelegate shouldWriteDataDelegate)

Sets the delegate that determines whether the container data of a component should be written out.

Parameters:

shouldWriteDataDelegate - the delegate to set, not null

Throws:

IllegalArgumentException - if the provided delegate is null

Since:

7.5.0

See Also:

shouldWriteChildren(Component, Component), getShouldWriteDataDelegate()

getShouldWriteDataDelegate

public ShouldWriteDataDelegate getShouldWriteDataDelegate()

Gets the delegate that determines whether the container data of a component should be written out.

Returns:

the shouldWriteDataDelegate the currently use delegate

Since:

7.5.0

See Also:

setShouldWriteDataDelegate(ShouldWriteDataDelegate), shouldWriteChildren(Component, Component)

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