Package com.github.bordertech.wcomponents

Class WTemplate

java.lang.Object

com.github.bordertech.wcomponents.AbstractWComponent

com.github.bordertech.wcomponents.WBeanComponent

com.github.bordertech.wcomponents.WTemplate

All Implemented Interfaces:

BeanAware, BeanBound, BeanProviderBound, Container, DataBound, NamingContextable, WComponent, WebComponent, Serializable

public class WTemplate
extends WBeanComponent
implements Container, NamingContextable

Allows the use of custom templates to layout components, insert custom css and javascript.

Using a template is the preferred method in implementing a responsive design.

WComponents comes configured for Velocity, Handlebars and Plain Text templates.

Components can be included in a template by adding the component via addTaggedComponent(tag, component). These components will be rendered in place of the corresponding tag in the template.

Parameters can be passed into a template via addParameter(tag, value). The instance of WTemplate is passed in as a parameter with a key of "wc". The getter methods of WTemplate can be accessed via the bean notation in the templates. For example "wc.id" to access the WTemplate id or "wc.bean" to access the bean (if set).

If no template engine is set on WTemplate then the default templating engine is used. The default template engine is set via the parameter "bordertech.wcomponents.template.renderer". For example:- bordertech.wcomponents.template.renderer=velocity

To override the default engine for a particular instance of WTemplate, set the chosen template engine via setEngineName(TemplateEngine.Type).

Other templating engines can be implemented by projects by setting a custom engine name via setEngineName(name). The engine name must be correctly configured as per the TemplateRendererFactory requirements and have the necessary implementation of TemplateRenderer.

Configuration options can also be passed to the template engines via addEngineOption(key, value). The options are determined by the TemplateRenderer implementation.

Since:

1.0.3

Author:

Jonathan Austin

See Also:

TemplateRenderer, TemplateRendererFactory, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	WTemplate.TemplateModel	A class used to hold the list of options for this component.

Nested classes/interfaces inherited from class com.github.bordertech.wcomponents.AbstractWComponent

AbstractWComponent.WComponentRef

Field Summary

Fields inherited from interface com.github.bordertech.wcomponents.WComponent

DEFAULT_APPLICATION_ID, DEFAULT_INTERNAL_ID, DEFAULT_NO_ID, ID_CONTEXT_SEPERATOR, ID_FRAMEWORK_ASSIGNED_SEPERATOR, ID_VALIDATION_PATTERN

Constructor Summary

Constructors

Constructor	Description
WTemplate()	Construct WTemplate.
WTemplate(String templateName)
WTemplate(String templateName, TemplateRendererFactory.TemplateEngine engine)
WTemplate(String templateName, String engineName)

Method Summary

Modifier and Type	Method	Description
void	addEngineOption(String key, Object value)	Pass configuration options to the template engine.
void	addParameter(String tag, Object value)	Add a template parameter.
void	addTaggedComponent(String tag, WComponent component)	Add a tagged component to be included in the template.
WComponent	getChildAt(int index)	Retrieves a child component by its index.
int	getChildCount()
List<WComponent>	getChildren()	Retrieves a list of this Container's.
protected WTemplate.TemplateModel	getComponentModel()	Returns the effective component model for this component.
String	getEngineName()
Map<String,Object>	getEngineOptions()
int	getIndexOfChild(WComponent childComponent)	Retrieves the index of the given child.
String	getInlineTemplate()
String	getNamingContextId()	Allow components that implement NamingContextable to selectively disable prepending their ID to their descendent's IDs by breaking the prepending logic into a seperately callable method.
protected WTemplate.TemplateModel	getOrCreateComponentModel()	Retrieves the model for this component so that it can be modified.
Map<String,Object>	getParameters()
Map<String,WComponent>	getTaggedComponents()
String	getTemplateName()
boolean	isNamingContext()	A naming context is only considered active if an Id name has been set.
protected WTemplate.TemplateModel	newComponentModel()	Creates a new component model appropriate for this component.
void	removeAllEngineOptions()	Remove all template engine options.
void	removeAllParameters()	Remove all template parameters.
void	removeAllTaggedComponents()	Remove all tagged components.
void	removeEngineOption(String key)	Remove a template engine option.
void	removeParameter(String tag)	Remove a template parameter.
void	removeTaggedComponent(WComponent component)	Remove a tagged component via the component instance.
void	removeTaggedComponent(String tag)	Remove a tagged component by its tag.
void	setEngineName(TemplateRendererFactory.TemplateEngine templateEngine)	Set a predefined template engine.
void	setEngineName(String engineName)	Set a template engine.
void	setInlineTemplate(String inlineTemplate)
void	setNamingContext(boolean context)	A naming context is only considered active if it has been set active via setNamingContext(boolean) and also has an id name set via AbstractWComponent.setIdName(String).
void	setTemplateName(String templateName)

Methods inherited from class com.github.bordertech.wcomponents.WBeanComponent

addBeanToScratchMap, doUpdateBeanValue, getBean, getBeanFromScratchMap, getBeanId, getBeanProperty, getBeanProvider, getBeanScratchMap, getBeanValue, getData, isBeanInScratchMap, isChanged, isSearchAncestors, isUseRequestScopeScratchMap, removeBeanFromScratchMap, resetData, setBean, setBeanId, setBeanProperty, setBeanProvider, setData, setSearchAncestors, updateBeanValue

Methods inherited from class com.github.bordertech.wcomponents.AbstractWComponent

addHtmlClass, addHtmlClass, addNotify, afterPaint, assertAddSupported, beforePaint, createErrorDiagnostic, createErrorDiagnostic, forward, getAccessibleText, getAttribute, getBaseUrl, getDefaultModel, getEnvironment, getHeaders, getHtmlClass, getHtmlClasses, getId, getIdName, getInternalId, getLabel, getName, getParent, getScratchMap, getTabIndex, getTag, getTemplate, getTemplateMarkUp, getToolTip, handleRequest, hasNoComponentModel, hasTabIndex, initialiseComponentModel, invokeLater, invokeLaters, isDebugStructure, isDefaultState, isFlagSet, isHidden, isInitialised, isLocked, isTracking, isTrackingEnabled, isValidate, isVisible, paint, paintComponent, preparePaint, preparePaintComponent, removeAttribute, removeComponentModel, removeHtmlClass, removeHtmlClass, removeNotify, replaceWComponent, reset, serviceRequest, setAccessibleText, setAttribute, setEnvironment, setFlag, setFocussed, setHidden, setHtmlClass, setHtmlClass, setIdName, setInitialised, setLocked, setTag, setToolTip, setTrackingEnabled, setValidate, setVisible, showErrorIndicators, showErrorIndicatorsForComponent, showWarningIndicators, showWarningIndicatorsForComponent, tidyUpUIContext, tidyUpUIContextForTree, toString, validate, validateComponent, writeReplace

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.github.bordertech.wcomponents.WComponent

addHtmlClass, addHtmlClass, forward, getAccessibleText, getAttribute, getBaseUrl, getEnvironment, getHeaders, getHtmlClass, getHtmlClasses, getId, getIdName, getInternalId, getLabel, getName, getParent, getTabIndex, getTag, getToolTip, handleRequest, hasTabIndex, invokeLater, isDefaultState, isHidden, isInitialised, isLocked, isTracking, isTrackingEnabled, isValidate, isVisible, paint, preparePaint, removeAttribute, removeHtmlClass, removeHtmlClass, reset, serviceRequest, setAccessibleText, setAttribute, setEnvironment, setFocussed, setHtmlClass, setHtmlClass, setIdName, setInitialised, setLocked, setTag, setToolTip, setTrackingEnabled, setValidate, setVisible, showErrorIndicators, showWarningIndicators, tidyUpUIContextForTree, validate

Constructor Detail

WTemplate

public WTemplate()

Construct WTemplate.

WTemplate

public WTemplate(String templateName)

Parameters:

templateName - the template file name

WTemplate

public WTemplate(String templateName,
                 TemplateRendererFactory.TemplateEngine engine)

Parameters:

templateName - the template file name and path

engine - the template engine

WTemplate

public WTemplate(String templateName,
                 String engineName)

Parameters:

templateName - the template file name and path

engineName - the template engine

Method Detail

setTemplateName

public void setTemplateName(String templateName)

Parameters:

templateName - the template file name and path

getTemplateName

public String getTemplateName()

Returns:

the template file name and path

setInlineTemplate

public void setInlineTemplate(String inlineTemplate)

Parameters:

inlineTemplate - the inline template

getInlineTemplate

public String getInlineTemplate()

Returns:

the inline template

addTaggedComponent

public void addTaggedComponent(String tag,
                               WComponent component)

Add a tagged component to be included in the template. The component will be rendered in place of the corresponding tag in the template.

Parameters:

tag - the tag for this component in the template

component - the component to add

removeTaggedComponent

public void removeTaggedComponent(WComponent component)

Remove a tagged component via the component instance.

Parameters:

component - the tagged component to remove

removeTaggedComponent

public void removeTaggedComponent(String tag)

Remove a tagged component by its tag.

Parameters:

tag - the tag of the component to remove

removeAllTaggedComponents

public void removeAllTaggedComponents()

Remove all tagged components.

getTaggedComponents

public Map<String,WComponent> getTaggedComponents()

Returns:

the tagged components

addParameter

public void addParameter(String tag,
                         Object value)

Add a template parameter.

Parameters:

tag - the tag for the template parameter

value - the value for the template parameter

removeParameter

public void removeParameter(String tag)

Remove a template parameter.

Parameters:

tag - the tag of the template parameter to remove

removeAllParameters

public void removeAllParameters()

Remove all template parameters.

getParameters

public Map<String,Object> getParameters()

Returns:

the template parameters

setEngineName

public void setEngineName(TemplateRendererFactory.TemplateEngine templateEngine)

Set a predefined template engine. If null then the default engine is used.

Parameters:

templateEngine - the provided template engine or null to use the default engine

setEngineName

public void setEngineName(String engineName)

Set a template engine. If null then the default engine is used.

The engine name must be supported by TemplateRendererFactory and correctly configured as per the factory requirements and have the necessary implementation of TemplateRenderer.

Parameters:

engineName - the template engine name

getEngineName

public String getEngineName()

Returns:

the template engine name

addEngineOption

public void addEngineOption(String key,
                            Object value)

Pass configuration options to the template engine.

The options are determined by the TemplateRenderer implementation for the template engine.

The TemplateRenderer implemented is determined by the TemplateRendererFactory.

Parameters:

key - the engine option key

value - the engine option value

removeEngineOption

public void removeEngineOption(String key)

Remove a template engine option.

Parameters:

key - the engine option to remove

removeAllEngineOptions

public void removeAllEngineOptions()

Remove all template engine options.

getEngineOptions

public Map<String,Object> getEngineOptions()

Returns:

the engine options

getChildCount

public int getChildCount()

Specified by:

getChildCount in interface Container

Returns:

the number of child components currently contained within this component.

getChildAt

public WComponent getChildAt(int index)

Retrieves a child component by its index.

Specified by:

getChildAt in interface Container

Parameters:

index - the index of the child component to be retrieved.

Returns:

the child component at the given index.

getIndexOfChild

public int getIndexOfChild(WComponent childComponent)

Retrieves the index of the given child.

Specified by:

getIndexOfChild in interface Container

Parameters:

childComponent - the child component to retrieve the index for.

Returns:

the index of the given child component, or -1 if the component is not a child of this component.

getChildren

public List<WComponent> getChildren()

Retrieves a list of this Container's.

Specified by:

getChildren in interface Container

Returns:

an immutable list of this Container.

setNamingContext

public void setNamingContext(boolean context)

A naming context is only considered active if it has been set active via setNamingContext(boolean) and also has an id name set via AbstractWComponent.setIdName(String).

Parameters:

context - set true if this is a naming context.

isNamingContext

public boolean isNamingContext()

A naming context is only considered active if an Id name has been set.

Specified by:

isNamingContext in interface NamingContextable

Returns:

true if active naming context.

getNamingContextId

public String getNamingContextId()

Allow components that implement NamingContextable to selectively disable prepending their ID to their descendent's IDs by breaking the prepending logic into a seperately callable method.

See WComponent.getId() for usage.

By default, this method will call through to WComponent.getId() and return the result.

Specified by:

getNamingContextId in interface NamingContextable

Returns:

by default, return getId().

getComponentModel

protected WTemplate.TemplateModel getComponentModel()

Returns the effective component model for this component. Subclass may override this method to narrow the return type to their specific model type.

Overrides:

getComponentModel in class WBeanComponent

Returns:

the effective component model

getOrCreateComponentModel

protected WTemplate.TemplateModel getOrCreateComponentModel()

Retrieves the model for this component so that it can be modified. If this method is called during request processing, and a session specific model does not yet exist, then a new model is created. Subclasses may override this method to narrow the return type to their specific model type.

Overrides:

getOrCreateComponentModel in class WBeanComponent

Returns:

the model for this component

newComponentModel

protected WTemplate.TemplateModel newComponentModel()

Creates a new component model appropriate for this component.

Overrides:

newComponentModel in class WBeanComponent

Returns:

a new PanelModel.