echopointng
Class TemplatePanel

java.lang.Object
  nextapp.echo2.app.Component
      echopointng.ComponentEx
          echopointng.AbleComponent
              echopointng.TemplatePanel

All Implemented Interfaces:

AccessKeyable, Attributeable, Borderable, Delegateable, Heightable, Insetable, MouseCursorable, Sizeable, ToolTipable, Widthable, java.io.Serializable, PaneContainer, RenderIdSupport

public class TemplatePanel
extends AbleComponent
implements PaneContainer

TemplatePanel is a container that uses a TemplateLayoutData to render a template of content.

This layout data can itself contained "named" Components and "named" Text Substitutions.

A singleton TemplateDataSource can be used for more than one TemplatePanel and hence the memory footprint is reduced if used in this way.

Supplied Implementation

The supplied template implementation reads XHTML template data from a number of different sources including Files, Strings, Resources and JSP pages.

The markup :

 
  
   <component name="xxx" style="xxx"/>
   
  
 

is used to indicate where in the template a named component will be placed.

The style attribute can contain a CSS statement for setting component properties.

For example :

 
  
   <component name="xxx" style="background:red"/>
   
  
 

will set the background of the inserted component to red.

The standard XHTML "controls" markup can also be used also to subsitute components.

<input/>

<button/>

and

<select/>

can all be used as component subsitution markers.

The markup :

<text name="xxx" />

is used to indicate where text subsitutions will be placed.

Text subsitution can occur within components as well.

For example imagine the markup of the template looks a bit like this

... preceding markup <component name="button1">Button 1 Text
 Here</component> and so on ...

If the isInvokeSetText() property is true and the component that maps to the name 'button1' has a public void setText(String s) method, then the text inside the component marker, in this case "Button 1 Text Here", will be placed into the component via its setText() method.

This is only done once when the template is compiled and isStyleApplied() is false. Of course the component in question must have a setText() method.

Custom Implementation

The source template data need not be in XHTML format however you must compile it into a XHTML DOM Element. For example you could write your own custom XML/XSLT implementation that produced XHTML.

To do this you must provide a TemplateCompiler to the rendering framework that takes the raw template data and converts it into a XHTML DOM element.

TemplatePanel is defined as an AbleComponent and as such has border, inset and mouse cursor support. However there is a caveat for to this. These properties only take affect if the top level tag in the the template data source does not provide a style="" attribute. if one is provided then it takes precedence over the AbleComponent properties

TemplatePanel also support the use of DisplayLayoutData and ScrollableDisplayLayoutData when used on child components. This allows the special "style" attributes to be placed within the template around the child component in question, perhaps to make it a certain size or position is aspecial place.

See Also:

TemplateDataSource, TemplateTextSubstitution, DisplayLayoutData, ScrollableDisplayLayoutData, Serialized Form

Field Summary

static java.lang.String	PROPERTY_EXCEPTION_ON_FAILURE
static java.lang.String	PROPERTY_INVOKE_SETTEXT
static java.lang.String	PROPERTY_TEMPLATE_DATA_SOURCE
static java.lang.String	PROPERTY_TEMPLATE_TEXT_SUBSTITUTION

Fields inherited from class echopointng.ComponentEx

PROPERTY_HIDDEN

Fields inherited from class nextapp.echo2.app.Component

CHILDREN_CHANGED_PROPERTY, ENABLED_CHANGED_PROPERTY, FOCUS_TRAVERSAL_INDEX_CHANGED_PROPERTY, FOCUS_TRAVERSAL_PARTICIPANT_CHANGED_PROPERTY, LAYOUT_DIRECTION_CHANGED_PROPERTY, LOCALE_CHANGED_PROPERTY, PROPERTY_BACKGROUND, PROPERTY_FONT, PROPERTY_FOREGROUND, PROPERTY_LAYOUT_DATA, STYLE_CHANGED_PROPERTY, STYLE_NAME_CHANGED_PROPERTY, VISIBLE_CHANGED_PROPERTY

Fields inherited from interface echopointng.able.AccessKeyable

PROPERTY_ACCESS_KEY

Fields inherited from interface echopointng.able.Borderable

PROPERTY_BORDER

Fields inherited from interface echopointng.able.MouseCursorable

CURSOR_AUTO, CURSOR_CROSSHAIR, CURSOR_CUSTOM_URI, CURSOR_DEFAULT, CURSOR_E_RESIZE, CURSOR_HELP, CURSOR_MOVE, CURSOR_N_RESIZE, CURSOR_NE_RESIZE, CURSOR_NW_RESIZE, CURSOR_POINTER, CURSOR_S_RESIZE, CURSOR_SE_RESIZE, CURSOR_SW_RESIZE, CURSOR_TEXT, CURSOR_W_RESIZE, CURSOR_WAIT, PROPERTY_MOUSE_CURSOR, PROPERTY_MOUSE_CURSOR_URI

Fields inherited from interface echopointng.able.Insetable

DEFAULT_INSETS, DEFAULT_OUTSETS, PROPERTY_INSETS, PROPERTY_OUTSETS

Fields inherited from interface echopointng.able.Widthable

PROPERTY_WIDTH

Fields inherited from interface echopointng.able.Heightable

PROPERTY_HEIGHT

Fields inherited from interface echopointng.able.ToolTipable

PROPERTY_TOOL_TIP_TEXT

Constructor Summary

TemplatePanel()
Constructs a TemplatePanel with no template data as yet.

TemplatePanel(TemplateDataSource tds)
Constructs a TemplatePanel with the specified TemplateDataSource.

Method Summary

void	addNamedComponent(Component component, java.lang.String componentName) Adds a component to the TemplatePanel with the associated name which can the be references from the template data.
java.lang.String	getComponentName(Component component) Returns the name associated with the component or null if it cant be found.
Component	getNamedComponent(java.lang.String componentName) Returns a component associated with the name or null if it cant be found.
java.lang.String[]	getNamedComponents()
TemplateDataSource	getTemplateDataSource() Returns the TemplateDataSource which contains the template data.
TemplateTextSubstitution	getTemplateTextSubstitution() Returns the TemplateTextSubstitution in place.
boolean	isExceptionOnFailure() The default value is false.
boolean	isInvokeSetText() Returns true if the text of a component marker is the template is placed into the component via its setTextMethod.
boolean	isStyleApplied() Returns true if the style declarations from the template data have been applied.
void	remove(Component c) Removes the specified child Component from this Component.
void	removeNamedComponent(java.lang.String componentName) Removes a named component from the TemplatePanel that was previously added via the addNamedComponent() method.
void	setExceptionOnFailure(boolean newValue) If set to true, then if the template data cannot be compiled, a a runtime exception will be thrown.
void	setInvokeSetText(boolean newValue) Controls if the text of a component marker is the template is placed into the component via its setTextMethod.
void	setStyleApplied(boolean styleApplied) Controls whether style declarations in the template data have been applied or not.
void	setTemplateDataSource(TemplateDataSource templateDataSource) Sets the TemplateDataSource to be used
void	setTemplateTextSubstitution(TemplateTextSubstitution textSubstitution) Sets the TemplateTextSubstitution to be used to substitute 'named' text into the template data
void	validate() A life-cycle method invoked before the component is rendered to ensure it is in a valid state.

Methods inherited from class echopointng.AbleComponent

getAccessKey, getBorder, getHeight, getInsets, getMouseCursor, getMouseCursorURI, getOutsets, getToolTipText, getWidth, setAccessKey, setBorder, setHeight, setInsets, setMouseCursor, setMouseCursorURI, setOutsets, setToolTipText, setWidth

Methods inherited from class echopointng.ComponentEx

getAttribute, getAttributeNames, getProperty, getProperty, getProperty, getProperty, getProperty, getProperty, getProperty, getProperty, getProperty, getProperty, getProperty, getProperty, getProperty, getProperty, getProperty, getProperty, getProperty, getRenderProperty, getRenderProperty, getRenderProperty, getRenderProperty, getRenderProperty, getRenderProperty, getRenderProperty, getRenderProperty, getRenderProperty, getRenderProperty, getRenderProperty, getRenderProperty, getRenderProperty, getRenderProperty, getRenderProperty, getRenderProperty, getRenderProperty, getRenderProperty, isHidden, setAttribute, setHidden, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty

Methods inherited from class nextapp.echo2.app.Component

add, add, addPropertyChangeListener, dispose, firePropertyChange, getApplicationInstance, getBackground, getComponent, getComponent, getComponentCount, getComponents, getEventListenerList, getFocusTraversalIndex, getFont, getForeground, getId, getIndexedProperty, getLayoutData, getLayoutDirection, getLocale, getParent, getProperty, getRenderId, getRenderIndexedProperty, getRenderIndexedProperty, getRenderLayoutDirection, getRenderLocale, getRenderProperty, getRenderProperty, getStyle, getStyleName, getVisibleComponent, getVisibleComponentCount, getVisibleComponents, hasEventListenerList, indexOf, init, isAncestorOf, isEnabled, isFocusTraversalParticipant, isRegistered, isRenderEnabled, isRenderVisible, isValidChild, isValidParent, isVisible, processInput, remove, removeAll, removePropertyChangeListener, setBackground, setEnabled, setFocusTraversalIndex, setFocusTraversalParticipant, setFont, setForeground, setId, setIndexedProperty, setLayoutData, setLayoutDirection, setLocale, setProperty, setStyle, setStyleName, setVisible, verifyInput, visibleIndexOf

Methods inherited from class java.lang.Object

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

Methods inherited from interface echopointng.able.Delegateable

getRenderProperty, getRenderProperty

Methods inherited from interface echopointng.able.Delegateable

getRenderProperty, getRenderProperty

Methods inherited from interface echopointng.able.Delegateable

getRenderProperty, getRenderProperty

Methods inherited from interface echopointng.able.Delegateable

getRenderProperty, getRenderProperty

Methods inherited from interface echopointng.able.Delegateable

getRenderProperty, getRenderProperty

Methods inherited from interface echopointng.able.Delegateable

getRenderProperty, getRenderProperty

Field Detail

PROPERTY_EXCEPTION_ON_FAILURE

public static final java.lang.String PROPERTY_EXCEPTION_ON_FAILURE

See Also:

Constant Field Values

PROPERTY_INVOKE_SETTEXT

public static final java.lang.String PROPERTY_INVOKE_SETTEXT

See Also:

Constant Field Values

PROPERTY_TEMPLATE_DATA_SOURCE

public static final java.lang.String PROPERTY_TEMPLATE_DATA_SOURCE

See Also:

Constant Field Values

PROPERTY_TEMPLATE_TEXT_SUBSTITUTION

public static final java.lang.String PROPERTY_TEMPLATE_TEXT_SUBSTITUTION

See Also:

Constant Field Values

Constructor Detail

TemplatePanel

public TemplatePanel()

Constructs a TemplatePanel with no template data as yet.

TemplatePanel

public TemplatePanel(TemplateDataSource tds)

Constructs a TemplatePanel with the specified TemplateDataSource.

Parameters:

tds - - the source for the template data.

Method Detail

addNamedComponent

public void addNamedComponent(Component component,
                              java.lang.String componentName)

Adds a component to the TemplatePanel with the associated name which can the be references from the template data.

Parameters:

component - the component to add

componentName - - the name to use when referencing this component in the template data.

getComponentName

public java.lang.String getComponentName(Component component)

Returns the name associated with the component or null if it cant be found.

Parameters:

component - - the component associated with the name

Returns:

a name associated with component

getNamedComponent

public Component getNamedComponent(java.lang.String componentName)

Returns a component associated with the name or null if it cant be found.

Parameters:

componentName - - the name associated with the component

Returns:

a component associated with componentName

getNamedComponents

public java.lang.String[] getNamedComponents()

Returns:

an array of all the component names in the TemplatePanel.

getTemplateDataSource

public TemplateDataSource getTemplateDataSource()

Returns the TemplateDataSource which contains the template data.

Returns:

the TemplateDataSource in place

getTemplateTextSubstitution

public TemplateTextSubstitution getTemplateTextSubstitution()

Returns the TemplateTextSubstitution in place.

Returns:

Returns the textSubstitution in place.

isExceptionOnFailure

public boolean isExceptionOnFailure()

The default value is false.

Returns:

- the exception failure value

isInvokeSetText

public boolean isInvokeSetText()

Returns true if the text of a component marker is the template is placed into the component via its setTextMethod.

Returns:

true if the text of a component marker is the template is placed into the component via its setTextMethod.

isStyleApplied

public boolean isStyleApplied()

Returns true if the style declarations from the template data have been applied. Typically not used outside the template rendering framework. The template rendering framework use this to keep track of when styles have been applied and to prevent them being unecessarity applied again.

Returns:

true if the the style declarations have been applied

remove

public void remove(Component c)

Description copied from class: Component

Removes the specified child Component from this Component.

All Component remove operations use this method to remove Components. Components that require notification of all child removals should override this method (while ensuring to call the superclass' implementation).

Overrides:

remove in class Component

Parameters:

c - the child Component to remove

See Also:

Component.remove(nextapp.echo2.app.Component)

removeNamedComponent

public void removeNamedComponent(java.lang.String componentName)

Removes a named component from the TemplatePanel that was previously added via the addNamedComponent() method.

Parameters:

componentName - - the name of the component

setExceptionOnFailure

public void setExceptionOnFailure(boolean newValue)

If set to true, then if the template data cannot be compiled, a a runtime exception will be thrown. If this is false, then a prominent error message will be returned as the template data but no exception will be thrown.

Some people prefer exceptions and "defined" error behaviour. Others prefer soft failures and the system to keep on running.

Parameters:

newValue - - the new failure value

setInvokeSetText

public void setInvokeSetText(boolean newValue)

Controls if the text of a component marker is the template is placed into the component via its setTextMethod.

The markup of the template might look like this

... preceding markup <component name="button1">Button 1 Text Here</component> and so on ...

If this property is true and the component that maps to the name button1 has a public void setText(String s) method, then the text inside the component marker, in this case "Button 1 Text Here", will be placed into the component via its setText() method.

This is only done once when the template is compiled and isStyleApplied() is false. Of course the component in question must have a setText() method.

Parameters:

newValue - - the new boolean value

setStyleApplied

public void setStyleApplied(boolean styleApplied)

Controls whether style declarations in the template data have been applied or not. Typically you would not use this method. It is intended for use by the rendering framework

Parameters:

styleApplied - - The newValue to set.

setTemplateDataSource

public void setTemplateDataSource(TemplateDataSource templateDataSource)

Sets the TemplateDataSource to be used

Parameters:

templateDataSource - the TemplateDataSource to be used

setTemplateTextSubstitution

public void setTemplateTextSubstitution(TemplateTextSubstitution textSubstitution)

Sets the TemplateTextSubstitution to be used to substitute 'named' text into the template data

Parameters:

textSubstitution - - The newValue to set.

validate

public void validate()

Description copied from class: Component

A life-cycle method invoked before the component is rendered to ensure it is in a valid state. Default implementation is empty. Overriding implementations should ensure to invoke super.validate() out of convention.

Overrides:

validate in class Component

See Also:

Component.validate()