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.form;
016
017import org.apache.tapestry.IMarkupWriter;
018import org.apache.tapestry.IRequestCycle;
019import org.apache.tapestry.Tapestry;
020import org.apache.tapestry.valid.ValidatorException;
021
022/**
023 * A component used to render a drop-down list of options that the user may select. [ <a
024 * href="../../../../../ComponentReference/PropertySelection.html">Component Reference </a>]
025 * <p>
026 * Earlier versions of PropertySelection (through release 2.2) were more flexible, they included a
027 * <b>renderer </b> property that controlled how the selection was rendered. Ultimately, this proved
028 * of little value and this portion of functionality was deprecated in 2.3 and will be removed in
029 * 2.3.
030 * <p>
031 * Typically, the values available to be selected are defined using an
032 * {@link org.apache.commons.lang.enum.Enum}. A PropertySelection is dependent on an
033 * {@link IPropertySelectionModel} to provide the list of possible values.
034 * <p>
035 * Often, this is used to select a particular {@link org.apache.commons.lang.enum.Enum} to assign to
036 * a property; the {@link EnumPropertySelectionModel} class simplifies this.
037 * <p>
038 * Often, a drop-down list will contain an initial option that serves both as a label and to represent 
039 * that nothing is selected. This can behavior can easily be achieved by decorating an existing 
040 * {@link IPropertySelectionModel} with a {@link LabeledPropertySelectionModel}.
041 * <p>
042 * As of 4.0, this component can be validated.
043 * 
044 * @author Howard Lewis Ship
045 * @author Paul Ferraro
046 */
047public abstract class PropertySelection extends AbstractFormComponent implements ValidatableField
048{
049    /**
050     * @see org.apache.tapestry.form.AbstractFormComponent#renderFormComponent(org.apache.tapestry.IMarkupWriter, org.apache.tapestry.IRequestCycle)
051     */
052    protected void renderFormComponent(IMarkupWriter writer, IRequestCycle cycle)
053    {
054        renderDelegatePrefix(writer, cycle);
055
056        writer.begin("select");
057        writer.attribute("name", getName());
058
059        if (isDisabled())
060            writer.attribute("disabled", "disabled");
061
062        if (getSubmitOnChange())
063            writer.attribute("onchange", "javascript:   this.form.events.submit();");
064
065        renderIdAttribute(writer, cycle);
066
067        renderDelegateAttributes(writer, cycle);
068
069        getValidatableFieldSupport().renderContributions(this, writer, cycle);
070        
071        // Apply informal attributes.
072        renderInformalParameters(writer, cycle);
073
074        writer.println();
075
076        IPropertySelectionModel model = getModel();
077
078        if (model == null)
079            throw Tapestry.createRequiredParameterException(this, "model");
080
081        int count = model.getOptionCount();
082        boolean foundSelected = false;
083        Object value = getValue();
084
085        for (int i = 0; i < count; i++)
086        {
087            Object option = model.getOption(i);
088
089            writer.begin("option");
090            writer.attribute("value", model.getValue(i));
091
092            if (!foundSelected && isEqual(option, value))
093            {
094                writer.attribute("selected", "selected");
095
096                foundSelected = true;
097            }
098
099            writer.print(model.getLabel(i));
100
101            writer.end();
102
103            writer.println();
104        }
105
106        writer.end(); // <select>
107
108        renderDelegateSuffix(writer, cycle);
109    }
110
111    /**
112     * @see org.apache.tapestry.form.AbstractFormComponent#rewindFormComponent(org.apache.tapestry.IMarkupWriter, org.apache.tapestry.IRequestCycle)
113     */
114    protected void rewindFormComponent(IMarkupWriter writer, IRequestCycle cycle)
115    {
116        String value = cycle.getParameter(getName());
117        
118        Object object = (value == null) ? null : getModel().translateValue(value);
119        
120        try
121        {
122            getValidatableFieldSupport().validate(this, writer, cycle, object);
123            
124            setValue(object);
125        }
126        catch (ValidatorException e)
127        {
128            getForm().getDelegate().record(e);
129        }
130    }
131
132    private boolean isEqual(Object left, Object right)
133    {
134        // Both null, or same object, then are equal
135
136        if (left == right)
137            return true;
138
139        // If one is null, the other isn't, then not equal.
140
141        if (left == null || right == null)
142            return false;
143
144        // Both non-null; use standard comparison.
145
146        return left.equals(right);
147    }
148
149    public abstract IPropertySelectionModel getModel();
150
151    /** @since 2.2 * */
152    public abstract boolean getSubmitOnChange();
153
154    /** @since 2.2 * */
155    public abstract Object getValue();
156
157    /** @since 2.2 * */
158    public abstract void setValue(Object value);
159
160    /**
161     * Injected.
162     */
163    public abstract ValidatableFieldSupport getValidatableFieldSupport();
164
165    /**
166     * @see org.apache.tapestry.form.AbstractFormComponent#isRequired()
167     */
168    public boolean isRequired()
169    {
170        return getValidatableFieldSupport().isRequired(this);
171    }
172}