org.apache.tapestry.contrib.palette
Class Palette

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

All Implemented Interfaces:

IFormComponent, IComponent, ILocatable, ILocationHolder, IRender

public abstract class Palette
extends BaseComponent
implements IFormComponent

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 MultiplePropertySelection component 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 PropertySelection component, to define the possible values.
sort	SortMode	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 Block to 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;
 }
  

Author:

Howard Lewis Ship

Constructor Summary

Palette()

Method Summary

protected void	cleanupAfterRender(IRequestCycle cycle) Invoked by AbstractComponent.render(IMarkupWriter, IRequestCycle) after the component renders, to clear any parameters back to null (or 0, or false, or whatever the correct default is).
protected void	finishLoad() Invoked, as a convienience, from AbstractComponent.finishLoad(IRequestCycle, IPageLoader, IComponentSpecification).
abstract Block	getAvailableTitleBlock()
abstract IAsset	getDeselectDisabledImage()
abstract IAsset	getDeselectImage()
String	getDisplayName() Returns null, but may make sense to implement a displayName parameter.
abstract IAsset	getDownDisabledImage()
abstract IAsset	getDownImage()
abstract IForm	getForm() Returns the IForm which contains the component, or null if the component is not contained by a form, of if the containing Form is not currently renderring.
abstract IPropertySelectionModel	getModel()
abstract String	getName() Returns the name of the component, which is automatically generated during renderring.
abstract int	getRows()
abstract IAsset	getSelectDisabledImage()
abstract List	getSelected()
abstract Block	getSelectedTitleBlock()
abstract IAsset	getSelectImage()
abstract SortMode	getSort()
Map	getSymbols()
abstract IAsset	getUpDisabledImage()
abstract IAsset	getUpImage()
boolean	isDisabled() Returns false.
boolean	isSortUser()
protected void	renderComponent(IMarkupWriter writer, IRequestCycle cycle) Renders the top level components contained by the receiver.
abstract void	setAvailableColumn(PaletteColumn column)
abstract void	setAvailableTitleBlock(Block availableTitleBlock)
abstract void	setDeselectDisabledImage(IAsset deselectDisabledImage)
abstract void	setDeselectImage(IAsset deselectImage)
abstract void	setDownDisabledImage(IAsset downDisabledImage)
abstract void	setDownImage(IAsset downImage)
abstract void	setForm(IForm form)
abstract void	setName(String name) Invoked by IForm.getElementId(IFormComponent) when a name is created for a form component.
abstract void	setRows(int rows)
abstract void	setSelectDisabledImage(IAsset selectDisabledImage)
abstract void	setSelected(List selected)
abstract void	setSelectedColumn(PaletteColumn column)
abstract void	setSelectedTitleBlock(Block selectedTitleBlock)
abstract void	setSelectImage(IAsset selectImage)
abstract void	setSort(SortMode sort)
abstract void	setTableClass(String tableClass)
abstract void	setUpDisabledImage(IAsset upDisabledImage)
abstract void	setUpImage(IAsset upImage)

Methods inherited from class org.apache.tapestry.BaseComponent

addOuter, finishLoad

Methods inherited from class org.apache.tapestry.AbstractComponent

addAsset, addBody, addComponent, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, fireObservedChange, format, format, format, format, formatString, formatString, formatString, formatString, generateAttributes, getAsset, getAssets, getBeans, getBinding, getBindingNames, getBindings, getBody, getBodyCount, getChangeObserver, getComponent, getComponents, getContainer, getExtendedId, getId, getIdPath, getListeners, getMessage, getMessages, getNamespace, getPage, getProperty, getSpecification, getString, pageEndRender, prepareForRender, render, renderBody, renderInformalParameters, setBinding, setContainer, setId, setNamespace, setPage, setProperty, setSpecification, toString

Methods inherited from class org.apache.tapestry.spec.BaseLocatable

getLocation, setLocation

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.tapestry.IComponent

addAsset, addBody, addComponent, finishLoad, getAsset, getAssets, getBinding, getBindingNames, getBindings, getComponent, getComponents, getContainer, getExtendedId, getId, getIdPath, getMessage, getMessages, getNamespace, getPage, getProperty, getSpecification, getString, renderBody, setBinding, setContainer, setId, setNamespace, setPage, setProperty, setSpecification

Methods inherited from interface org.apache.tapestry.IRender

render

Methods inherited from interface org.apache.tapestry.ILocationHolder

setLocation

Methods inherited from interface org.apache.tapestry.ILocatable

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

finishLoad

protected void finishLoad()

Description copied from class: AbstractComponent

Invoked, as a convienience, from AbstractComponent.finishLoad(IRequestCycle, IPageLoader, IComponentSpecification). This implemenation does nothing. Subclasses may override without invoking this implementation.

Overrides:

finishLoad in class AbstractComponent

getName

public abstract String getName()

Description copied from interface: IFormComponent

Returns the name of the component, which is automatically generated during renderring.

This value is set inside the component's render method and is not cleared. If the component is inside a Foreach, the value returned is the most recent name generated for the component.

This property is made available to facilitate writing JavaScript that allows components (in the client web browser) to interact.

In practice, a Script component works with the Body component to get the JavaScript code inserted and referenced.

Specified by:

getName in interface IFormComponent

setName

public abstract void setName(String name)

Description copied from interface: IFormComponent

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

Specified by:

setName in interface IFormComponent

getForm

public abstract IForm getForm()

Description copied from interface: IFormComponent

Returns the IForm which contains the component, or null if the component is not contained by a form, of if the containing Form is not currently renderring.

Specified by:

getForm in interface IFormComponent

setForm

public abstract void setForm(IForm form)

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

cleanupAfterRender

protected void cleanupAfterRender(IRequestCycle cycle)

Description copied from class: AbstractComponent

Invoked by AbstractComponent.render(IMarkupWriter, IRequestCycle) after the component renders, to clear any parameters back to null (or 0, or false, or whatever the correct default is). Primarily, this is used to ensure that the component doesn't hold onto any objects that could otherwise be garbage collected.

Subclasses may override this implementation, but must also invoke it.

Overrides:

cleanupAfterRender in class AbstractComponent

getSymbols

public Map getSymbols()

isSortUser

public boolean isSortUser()

getDisplayName

public String getDisplayName()

Returns null, but may make sense to implement a displayName parameter.

Specified by:

getDisplayName in interface IFormComponent

getAvailableTitleBlock

public abstract Block getAvailableTitleBlock()

setAvailableTitleBlock

public abstract void setAvailableTitleBlock(Block availableTitleBlock)

getDeselectDisabledImage

public abstract IAsset getDeselectDisabledImage()

setDeselectDisabledImage

public abstract void setDeselectDisabledImage(IAsset deselectDisabledImage)

getDeselectImage

public abstract IAsset getDeselectImage()

setDeselectImage

public abstract void setDeselectImage(IAsset deselectImage)

getDownDisabledImage

public abstract IAsset getDownDisabledImage()

setDownDisabledImage

public abstract void setDownDisabledImage(IAsset downDisabledImage)

getDownImage

public abstract IAsset getDownImage()

setDownImage

public abstract void setDownImage(IAsset downImage)

getModel

public abstract IPropertySelectionModel getModel()

getRows

public abstract int getRows()

setRows

public abstract void setRows(int rows)

getSelectDisabledImage

public abstract IAsset getSelectDisabledImage()

setSelectDisabledImage

public abstract void setSelectDisabledImage(IAsset selectDisabledImage)

getSelectedTitleBlock

public abstract Block getSelectedTitleBlock()

setSelectedTitleBlock

public abstract void setSelectedTitleBlock(Block selectedTitleBlock)

getSelectImage

public abstract IAsset getSelectImage()

setSelectImage

public abstract void setSelectImage(IAsset selectImage)

getSort

public abstract SortMode getSort()

setSort

public abstract void setSort(SortMode sort)

setTableClass

public abstract void setTableClass(String tableClass)

getUpDisabledImage

public abstract IAsset getUpDisabledImage()

setUpDisabledImage

public abstract void setUpDisabledImage(IAsset upDisabledImage)

getUpImage

public abstract IAsset getUpImage()

setUpImage

public abstract void setUpImage(IAsset upImage)

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