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    
015    package org.apache.tapestry.contrib.form;
016    
017    import java.util.ArrayList;
018    import java.util.Collection;
019    import java.util.List;
020    
021    import org.apache.tapestry.IMarkupWriter;
022    import org.apache.tapestry.IRequestCycle;
023    import org.apache.tapestry.Tapestry;
024    import org.apache.tapestry.form.AbstractFormComponent;
025    import org.apache.tapestry.form.IPropertySelectionModel;
026    import org.apache.tapestry.form.ValidatableField;
027    import org.apache.tapestry.form.ValidatableFieldSupport;
028    import 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    
100    public 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    }