| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Copyright 2005 The Apache Software Foundation |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <document> |
| <properties> |
| <title>Palette</title> |
| </properties> |
| <body> |
| |
| <section name="Palette"> |
| |
| <p> |
| A component used to make a number of selections from a list. The general look is a |
| pair of <code><select></code> 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"). |
| <br /> |
| This all takes a bit of JavaScript to accomplish (quite a bit), which means a |
| <a href="../../components/general/body.html">Body</a> |
| 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. |
| <br /> |
| Cross-browser compatibility is not perfect. In some cases, the |
| <a href="multiplepropertyselection.html">MultiplePropertySelection</a> |
| component may be a better choice. |
| </p> |
| <img src="../images/palette.png" alt="Sample palette selection."/> |
| <p> |
| <strong> |
| See also: |
| <a href="multiplepropertyselection.html">MultiplePropertySelection</a> |
| </strong> |
| </p> |
| |
| <subsection name="Parameters"> |
| <table> |
| <tr> |
| <th>Name</th> |
| <th>Type</th> |
| <th>Required</th> |
| <th>Default</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>selected</td> |
| <td>java.util.List</td> |
| <td>yes</td> |
| <td></td> |
| <td> |
| 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. |
| <br /> |
| The order may be set by the user, as well, depending on the sortMode |
| parameter. |
| </td> |
| </tr> |
| <tr> |
| <td>model</td> |
| <td> |
| <a |
| href="../../apidocs/org/apache/tapestry/form/IPropertySelectionModel.html"> |
| IPropertySelectionModel |
| </a> |
| </td> |
| <td>yes</td> |
| <td></td> |
| <td> |
| Works, as with a |
| <a href="../../components/form/propertyselection.html">PropertySelection</a> |
| component, to define the possible values. |
| </td> |
| </tr> |
| <tr> |
| <td>sort</td> |
| <td> |
| <a |
| href="../../tapestry-contrib/apidocs/org/apache/tapestry/contrib/palette/SortMode.html"> |
| SortMode |
| </a> |
| </td> |
| <td>no</td> |
| <td> |
| <a |
| href="../../tapestry-contrib/apidocs/org/apache/tapestry/contrib/palette/SortMode.html#NONE"> |
| SortMode.NONE |
| </a> |
| </td> |
| <td>Controls automatic sorting of the options.</td> |
| </tr> |
| <tr> |
| <td>id</td> |
| <td>string</td> |
| <td>no</td> |
| <td></td> |
| <td> |
| Sets the id for the rendered <code><select></code> element that displays the |
| selected items. |
| </td> |
| </tr> |
| <tr> |
| <td>displayName</td> |
| <td>string</td> |
| <td>no</td> |
| <td></td> |
| <td> |
| The user-presentable name for the component, which will be used by a |
| <a href="../../components/form/fieldlabel.html">FieldLabel</a> |
| connected to the component. |
| </td> |
| </tr> |
| <tr> |
| <td>validators</td> |
| <td> |
| Array or collection of |
| <a |
| href="../../apidocs/org/apache/tapestry/form/validator/Validator.html"> |
| Validator |
| </a> |
| </td> |
| <td>no</td> |
| <td></td> |
| <td> |
| The validators to apply to the component. Something along the lines of: |
| <code>validators:required</code> .<br/><br/> |
| |
| <strong>See also:</strong> <a href="../../usersguide/validation.html">Validation</a> |
| </td> |
| </tr> |
| <tr> |
| <td>rows</td> |
| <td>int</td> |
| <td>no</td> |
| <td>10</td> |
| <td> |
| The number of rows that should be visible in the Pallete's |
| <code><select></code> elements. |
| </td> |
| </tr> |
| <tr> |
| <td>tableClass</td> |
| <td>String</td> |
| <td>no</td> |
| <td>tapestry-palette</td> |
| <td> |
| The CSS class for the table which surrounds the other elements of the |
| Palette. |
| </td> |
| </tr> |
| <tr> |
| <td>selectedTitleBlock</td> |
| <td> |
| <a href="../../components/general/block.html">Block</a> |
| </td> |
| <td>no</td> |
| <td>"Selected"</td> |
| <td> |
| If specified, allows a Block to be placed within the <code><th></code> reserved |
| for the title above the selected items <code><select></code> (on the right). |
| This allows for images or other components to be placed there. By |
| default, the simple word Selected is used. |
| </td> |
| </tr> |
| <tr> |
| <td>availableTitleBlock</td> |
| <td> |
| <a href="../../components/general/block.html">Block</a> |
| </td> |
| <td>no</td> |
| <td>"Available"</td> |
| <td> |
| As with selectedTitleBlock, but for the left column, of items which are |
| available to be selected. The default is the word Available. |
| </td> |
| </tr> |
| <tr> |
| <td> |
| selectImage |
| <br /> |
| selectDisabledImage |
| <br /> |
| deselectImage |
| <br /> |
| deselectDisabledImage |
| <br /> |
| upImage |
| <br /> |
| upDisabledImage |
| <br /> |
| downImage |
| <br /> |
| downDisabledImage |
| </td> |
| <td> |
| <a href="../../apidocs/org/apache/tapestry/IAsset.html"> |
| IAsset |
| </a> |
| </td> |
| <td>no</td> |
| <td></td> |
| <td> |
| 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. |
| <br /> |
| 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. |
| </td> |
| </tr> |
| </table> |
| |
| <p> |
| Body: |
| <strong>removed</strong> |
| </p> |
| |
| <p> |
| Informal parameters: |
| <strong>forbidden</strong> |
| </p> |
| |
| <p> |
| Reserved parameters: |
| <em>none</em> |
| </p> |
| |
| <p> |
| 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: |
| <br /> |
| </p> |
| <source xml:space="preserve"> |
| 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; |
| } |
| </source> |
| </subsection> |
| |
| </section> |
| |
| </body> |
| </document> |
