org.apache.tapestry.contrib.palette
Class Palette

java.lang.Object
  org.apache.hivemind.impl.BaseLocatable
      org.apache.tapestry.AbstractComponent
          org.apache.tapestry.BaseComponent
              org.apache.tapestry.contrib.palette.Palette

All Implemented Interfaces:

org.apache.hivemind.Locatable, org.apache.hivemind.LocationHolder, IFormComponent, ValidatableField, ValidatableFieldExtension, IComponent, IDirectEvent, Component, IRender, ITemplateComponent

public abstract class Palette
extends BaseComponent
implements ValidatableFieldExtension

A component used to make a number of selections from a list. The general look is a pair of <select> elements. with a pair of buttons between them. The right element is a list of values that can be selected. The buttons move values from the right column ("available") to the left column ("selected").

This all takes a bit of JavaScript to accomplish (quite a bit), which means a Body component must wrap the Palette. If JavaScript is not enabled in the client browser, then the user will be unable to make (or change) any selections.

Cross-browser compatibility is not perfect. In some cases, the MultiplePropertySelectioncomponent may be a better choice.

Parameter	Type	Direction	Required	Default	Description
selected	List	in	yes		A List of selected values. Possible selections are defined by the model; this should be a subset of the possible values. This may be null when the component is renderred. When the containing form is submitted, this parameter is updated with a new List of selected objects. The order may be set by the user, as well, depending on the sortMode parameter.
model	IPropertySelectionModel	in	yes		Works, as with a PropertySelectioncomponent, to define the possible values.
sort	string	in	no	SortMode.NONE	Controls automatic sorting of the options.
rows	int	in	no	10	The number of rows that should be visible in the Pallete's <select> elements.
tableClass	String	in	no	tapestry-palette	The CSS class for the table which surrounds the other elements of the Palette.
selectedTitleBlock	Block	in	no	"Selected"	If specified, allows a Blockto be placed within the <th> reserved for the title above the selected items <select> (on the right). This allows for images or other components to be placed there. By default, the simple word Selected is used.
availableTitleBlock	Block	in	no	"Available"	As with selectedTitleBlock, but for the left column, of items which are available to be selected. The default is the word Available.
selectImage selectDisabledImage deselectImage deselectDisabledImage upImage upDisabledImage downImage downDisabledImage	IAsset	in	no		If any of these are specified then they override the default images provided with the component. This allows the look and feel to be customized relatively easily. The most common reason to replace the images is to deal with backgrounds. The default images are anti-aliased against a white background. If a colored or patterned background is used, the default images will have an ugly white fringe. Until all browsers have full support for PNG (which has a true alpha channel), it is necessary to customize the images to match the background.

A Palette requires some CSS entries to render correctly ... especially the middle column, which contains the two or four buttons for moving selections between the two columns. The width and alignment of this column must be set using CSS. Additionally, CSS is commonly used to give the Palette columns a fixed width, and to dress up the titles. Here is an example of some CSS you can use to format the palette component:

                             TABLE.tapestry-palette TH
                             {
                               font-size: 9pt;
                               font-weight: bold;
                               color: white;
                               background-color: #330066;
                               text-align: center;
                             }
                            
                             TD.available-cell SELECT
                             {
                               font-weight: normal;
                               background-color: #FFFFFF;
                               width: 200px;
                             }
                             
                             TD.selected-cell SELECT
                             {
                               font-weight: normal;
                               background-color: #FFFFFF;
                               width: 200px;
                             }
                             
                             TABLE.tapestry-palette TD.controls
                             {
                               text-align: center;
                               vertical-align: middle;
                               width: 60px;
                             }
 

As of 4.0, this component can be validated.

Author:

Howard Lewis Ship

Field Summary

Fields inherited from class org.apache.tapestry.AbstractComponent

_body, _bodyCount

Constructor Summary

Palette()

Method Summary

protected void	cleanupAfterRender(IRequestCycle cycle) Invoked by AbstractComponent.render(IMarkupWriter, IRequestCycle)after the component renders.
abstract Block	getAvailableTitleBlock()
abstract IAsset	getDeselectDisabledImage()
abstract IAsset	getDeselectImage()
abstract IAsset	getDownDisabledImage()
abstract IAsset	getDownImage()
abstract IPropertySelectionModel	getModel()
abstract int	getRows()
abstract IScript	getScript() Injected.
abstract IAsset	getSelectDisabledImage()
abstract List	getSelected()
abstract Block	getSelectedTitleBlock()
abstract IAsset	getSelectImage()
abstract String	getSort()
Map	getSymbols()
abstract IAsset	getUpDisabledImage()
abstract IAsset	getUpImage()
abstract ValidatableFieldSupport	getValidatableFieldSupport() Injected.
boolean	isDisabled() Returns false.
boolean	isRequired() Returns true if the field is required.
boolean	isSortUser()
void	overrideContributions(Validator validator, FormComponentContributorContext context, IMarkupWriter writer, IRequestCycle cycle) Very similar to the method signature used by ValidatableFieldSupport.renderContributions(ValidatableField, IMarkupWriter, IRequestCycle), with the additional parameter being the Validator that this component has chosen to override.
boolean	overrideValidator(Validator validator, IRequestCycle cycle) Called during render of the specified component.
protected void	renderComponent(IMarkupWriter writer, IRequestCycle cycle) Renders the top level components contained by the receiver.
protected void	renderFormComponent(IMarkupWriter writer, IRequestCycle cycle)
protected void	rewindFormComponent(IMarkupWriter writer, IRequestCycle cycle)
abstract void	setAvailableColumn(PaletteColumn column)
abstract void	setForm(IForm form)
abstract void	setName(String name) Invoked by FormBehavior.getElementId(IFormComponent) when a name is created for a form component.
abstract void	setRequiredMessage(String message)
abstract void	setSelected(List selected)
abstract void	setSelectedColumn(PaletteColumn column)

Methods inherited from class org.apache.tapestry.BaseComponent

addOuter, finishLoad, getContainedRenderers, getInnerRenderers

Methods inherited from class org.apache.tapestry.AbstractComponent

addAsset, addBody, addComponent, checkActiveLock, enterActiveState, equals, finishLoad, generateClientId, getAsset, getAssets, getBeans, getBinding, getBindingNames, getBindings, getBody, getBodyCount, getBoundId, getClientId, getComponent, getComponents, getContainedComponent, getContainer, getEventInvoker, getExtendedId, getId, getIdPath, getListeners, getMessages, getNamespace, getPage, getRenderWorker, getSpecification, getSpecifiedId, getTemplateTagName, hasEvents, hashCode, isInActiveState, isParameterBound, isRendering, isStateful, pageEndRender, peekClientId, prepareForRender, render, renderBody, renderIdAttribute, renderInformalParameters, setBinding, setClientId, setContainedComponent, setContainer, setHasEvents, setId, setNamespace, setPage, setTemplateTagName, toString, triggerEvent

Methods inherited from class org.apache.hivemind.impl.BaseLocatable

getLocation, setLocation

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.tapestry.form.ValidatableField

getValidators

Methods inherited from interface org.apache.tapestry.form.IFormComponent

getClientId, getDisplayName, getForm, getName

Methods inherited from interface org.apache.tapestry.IComponent

addAsset, addBody, addComponent, enterActiveState, finishLoad, getAsset, getAssets, getBeans, getBinding, getBindingNames, getBindings, getComponent, getComponents, getContainedComponent, getContainer, getEventInvoker, getExtendedId, getId, getIdPath, getListeners, getMessages, getNamespace, getPage, getSpecification, getSpecifiedId, getTemplateTagName, isRendering, peekClientId, renderBody, setBinding, setClientId, setContainedComponent, setContainer, setId, setNamespace, setPage, setTemplateTagName

Methods inherited from interface org.apache.tapestry.IRender

render

Methods inherited from interface org.apache.hivemind.LocationHolder

setLocation

Methods inherited from interface org.apache.hivemind.Locatable

getLocation

Constructor Detail

Palette

public Palette()

Method Detail

setAvailableColumn

public abstract void setAvailableColumn(PaletteColumn column)

Since:

3.0 *

setSelectedColumn

public abstract void setSelectedColumn(PaletteColumn column)

Since:

3.0 *

setName

public abstract void setName(String name)

Description copied from interface: IFormComponent

Invoked by FormBehavior.getElementId(IFormComponent) when a name is created for a form component.

Specified by:

setName in interface IFormComponent

See Also:

FormBehavior.getElementId(IFormComponent)

setForm

public abstract void setForm(IForm form)

setRequiredMessage

public abstract void setRequiredMessage(String message)

Since:

4.0

renderComponent

protected void renderComponent(IMarkupWriter writer,
                               IRequestCycle cycle)

Description copied from class: BaseComponent

Renders the top level components contained by the receiver.

Overrides:

renderComponent in class BaseComponent

renderFormComponent

protected void renderFormComponent(IMarkupWriter writer,
                                   IRequestCycle cycle)

rewindFormComponent

protected void rewindFormComponent(IMarkupWriter writer,
                                   IRequestCycle cycle)

overrideContributions

public void overrideContributions(Validator validator,
                                  FormComponentContributorContext context,
                                  IMarkupWriter writer,
                                  IRequestCycle cycle)

Very similar to the method signature used by ValidatableFieldSupport.renderContributions(ValidatableField, IMarkupWriter, IRequestCycle), with the additional parameter being the Validator that this component has chosen to override.

This method will only be called if ValidatableFieldExtension.overrideValidator(Validator, IRequestCycle) returns true for the specified Validator.

Specified by:

overrideContributions in interface ValidatableFieldExtension

Parameters:

validator - The original Validator that component opted to override.

context - The context object used by validation contributors.

writer - The markup writer to send content to. (if any is needed)

cycle - The current request cycle.

overrideValidator

public boolean overrideValidator(Validator validator,
                                 IRequestCycle cycle)

Called during render of the specified component. Renders any contributions from validators. Check to see if this field would like to override the default contributions made by the specified Validator with it's own contributions.

Specified by:

overrideValidator in interface ValidatableFieldExtension

Parameters:

validator - The validator to check if component wants to override.

cycle - The current request cycle.

Returns:

True if this field wants to override default, false otherwise.

cleanupAfterRender

protected void cleanupAfterRender(IRequestCycle cycle)

Description copied from class: AbstractComponent

Invoked by AbstractComponent.render(IMarkupWriter, IRequestCycle)after the component renders.

Overrides:

cleanupAfterRender in class AbstractComponent

getSymbols

public Map getSymbols()

isSortUser

public boolean isSortUser()

getAvailableTitleBlock

public abstract Block getAvailableTitleBlock()

getDeselectDisabledImage

public abstract IAsset getDeselectDisabledImage()

getDeselectImage

public abstract IAsset getDeselectImage()

getDownDisabledImage

public abstract IAsset getDownDisabledImage()

getDownImage

public abstract IAsset getDownImage()

getSelectDisabledImage

public abstract IAsset getSelectDisabledImage()

getModel

public abstract IPropertySelectionModel getModel()

getRows

public abstract int getRows()

getSelectedTitleBlock

public abstract Block getSelectedTitleBlock()

getSelectImage

public abstract IAsset getSelectImage()

getSort

public abstract String getSort()

getUpDisabledImage

public abstract IAsset getUpDisabledImage()

getUpImage

public abstract IAsset getUpImage()

isDisabled

public boolean isDisabled()

Returns false. Palette components are never disabled.

Specified by:

isDisabled in interface IFormComponent

Since:

2.2

getSelected

public abstract List getSelected()

Since:

2.2 *

setSelected

public abstract void setSelected(List selected)

Since:

2.2 *

getScript

public abstract IScript getScript()

Injected.

Since:

4.0

getValidatableFieldSupport

public abstract ValidatableFieldSupport getValidatableFieldSupport()

Injected.

Since:

4.0

isRequired

public boolean isRequired()

Description copied from interface: IFormComponent

Returns true if the field is required. This will (typically) involve consulting the component's validators.

Specified by:

isRequired in interface IFormComponent

See Also:

AbstractFormComponent.isRequired()