001// Copyright 2004, 2005 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007//     http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.tapestry.contrib.form;
016
017import java.util.ArrayList;
018import java.util.Collection;
019import java.util.List;
020
021import org.apache.tapestry.IMarkupWriter;
022import org.apache.tapestry.IRequestCycle;
023import org.apache.tapestry.Tapestry;
024import org.apache.tapestry.form.AbstractFormComponent;
025import org.apache.tapestry.form.IPropertySelectionModel;
026import org.apache.tapestry.form.ValidatableField;
027import org.apache.tapestry.form.ValidatableFieldSupport;
028import org.apache.tapestry.valid.ValidatorException;
029
030/**
031 * A component which uses <input type=checkbox> to set a property of some object. Typically,
032 * the values for the object are defined using an {@link org.apache.commons.lang.enum.Enum}. A
033 * MultiplePropertySelection is dependent on an {link IPropertySelectionModel} to provide the list
034 * of possible values.
035 * <p>
036 * Often, this is used to select one or more {@link org.apache.commons.lang.enum.Enum}to assign to
037 * a property; the {@link org.apache.tapestry.form.EnumPropertySelectionModel}class simplifies
038 * this.
039 * <p>
040 * The {@link org.apache.tapestry.contrib.palette.Palette}component is more powerful, but requires
041 * client-side JavaScript and is not fully cross-browser compatible.
042 * <p>
043 * <table border=1>
044 * <tr>
045 * <td>Parameter</td>
046 * <td>Type</td>
047 * <td>Direction</td>
048 * <td>Required</td>
049 * <td>Default</td>
050 * <td>Description</td>
051 * </tr>
052 * <tr>
053 * <td>selectedList</td>
054 * <td>java.util.List</td>
055 * <td>in-out</td>
056 * <td>yes</td>
057 * <td>&nbsp;</td>
058 * <td>The property to set. During rendering, this property is read, and sets the default value of
059 * the options in the select. When the form is submitted, list is cleared, then has each selected
060 * option added to it.</td>
061 * </tr>
062 * <tr>
063 * <td>renderer</td>
064 * <td>{@link IMultiplePropertySelectionRenderer}</td>
065 * <td>in</td>
066 * <td>no</td>
067 * <td>shared instance of {@link CheckBoxMultiplePropertySelectionRenderer}</td>
068 * <td>Defines the object used to render this component. The default renders a table of checkboxes.
069 * </td>
070 * </tr>
071 * <tr>
072 * <td>model</td>
073 * <td>{@link IPropertySelectionModel}</td>
074 * <td>in</td>
075 * <td>yes</td>
076 * <td>&nbsp;</td>
077 * <td>The model provides a list of possible labels, and matches those labels against possible
078 * values that can be assigned back to the property.</td>
079 * </tr>
080 * <tr>
081 * <td>disabled</td>
082 * <td>boolean</td>
083 * <td>in</td>
084 * <td>no</td>
085 * <td>false</td>
086 * <td>Controls whether the &lt;select&gt; is active or not. A disabled PropertySelection does not
087 * update its value parameter.
088 * <p>
089 * Corresponds to the <code>disabled</code> HTML attribute.</td>
090 * </tr>
091 * </table>
092 * <p>
093 * Informal parameters are not allowed.
094 * <p>
095 * As of 4.0, this component can be validated.
096 * 
097 * @author Sanjay Munjal
098 */
099
100public abstract class MultiplePropertySelection extends AbstractFormComponent implements ValidatableField
101{
102    /**
103     * A shared instance of {@link CheckBoxMultiplePropertySelectionRenderer}.
104     */
105    public static final IMultiplePropertySelectionRenderer DEFAULT_CHECKBOX_RENDERER = new CheckBoxMultiplePropertySelectionRenderer();
106
107    public abstract Collection getSelectedList();
108    
109    public abstract void setSelectedList(Collection selectedList);
110    
111    protected void finishLoad()
112    {
113        setRenderer(DEFAULT_CHECKBOX_RENDERER);
114    }
115
116    protected void renderFormComponent(IMarkupWriter writer, IRequestCycle cycle)
117    {
118        Collection selectedList = getSelectedList();
119
120        if (selectedList == null)
121            throw Tapestry.createRequiredParameterException(this, "selectedList");
122
123        IPropertySelectionModel model = getModel();
124
125        if (model == null)
126            throw Tapestry.createRequiredParameterException(this, "model");
127
128        IMultiplePropertySelectionRenderer renderer = getRenderer();
129
130        // Start rendering
131        renderer.beginRender(this, writer, cycle);
132
133        int count = model.getOptionCount();
134
135        for (int i = 0; i < count; i++)
136        {
137            Object option = model.getOption(i);
138
139            // Try to find the option in the list and if yes, then it is checked.
140            boolean optionSelected = selectedList.contains(option);
141
142            renderer.renderOption(this, writer, cycle, model, option, i, optionSelected);
143        }
144
145        // A PropertySelection doesn't allow a body, so no need to worry about
146        // wrapped components.
147        renderer.endRender(this, writer, cycle);
148    }
149
150    /**
151     * @see org.apache.tapestry.form.AbstractRequirableField#rewindFormComponent(org.apache.tapestry.IMarkupWriter, org.apache.tapestry.IRequestCycle)
152     */
153    protected void rewindFormComponent(IMarkupWriter writer, IRequestCycle cycle)
154    {
155        // get all the values
156        String[] optionValues = cycle.getParameters(getName());
157
158        IPropertySelectionModel model = getModel();
159        
160        List selectedList = new ArrayList(getModel().getOptionCount());
161
162        // Nothing was selected
163        if (optionValues != null)
164        {
165            // Go through the array and translate and put back in the list
166            for (int i = 0; i < optionValues.length; i++)
167            {
168                // Translate the new value
169                Object selectedValue = model.translateValue(optionValues[i]);
170
171                // Add this element in the list back
172                selectedList.add(selectedValue);
173            }
174        }
175        
176        try
177        {
178            getValidatableFieldSupport().validate(this, writer, cycle, selectedList);
179            
180            setSelectedList(selectedList);
181        }
182        catch (ValidatorException e)
183        {
184            getForm().getDelegate().record(e);
185        }
186    }
187
188    public abstract IPropertySelectionModel getModel();
189
190    public abstract IMultiplePropertySelectionRenderer getRenderer();
191
192    public abstract void setRenderer(IMultiplePropertySelectionRenderer renderer);
193    
194    public abstract ValidatableFieldSupport getValidatableFieldSupport();
195
196    /**
197     * @see org.apache.tapestry.form.AbstractFormComponent#isRequired()
198     */
199    public boolean isRequired()
200    {
201        return getValidatableFieldSupport().isRequired(this);
202    }
203}