001 /*
002 * Copyright 2002-2004 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005 * use this file except in compliance with the License. You may obtain a copy of
006 * the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013 * License for the specific language governing permissions and limitations under
014 * the License.
015 */
016 package org.springframework.binding.form;
017
018 import org.springframework.binding.value.ValueModel;
019
020 /**
021 * Sub-interface implemented by form models that allow for configuration of the
022 * form's value models, id etc..
023 *
024 * @author Keith Donald
025 * @author Oliver Hutchison
026 * @author Jan Hoskens
027 */
028 public interface ConfigurableFormModel extends FormModel {
029
030 /**
031 * An id to identify this formModel.
032 *
033 * @param id
034 */
035 void setId(String id);
036
037 /**
038 * <p>
039 * Set the enabled state of this formModel. All fieldMetaData should take
040 * the enabled state of the formModel into account but should not alter
041 * their own enclosed enabled state.
042 * </p>
043 *
044 * <p>
045 * A disabled formModel can be compared to a visual component which doesn't
046 * respond to any user interaction (grey-out).
047 * </p>
048 *
049 * @param enabled set to <code>true</code> if the formModel should be
050 * enabled. Set to <code>false</code> if all fields should be disabled.
051 */
052 void setEnabled(boolean enabled);
053
054 /**
055 * <p>
056 * Set the readOnly state of this formModel. All fieldMetaData should take
057 * the readOnly state of the formModel into account but should not alter
058 * their own enclosed readOnly state.
059 * </p>
060 *
061 * <p>
062 * A formModel in readOnly state can be seen as visual component in which
063 * the user can navigate but not alter any values. (Eg editable TextFields)
064 * </p>
065 *
066 * @param readOnly set to <code>true</code> if all fields should be set
067 * readOnly.
068 */
069 void setReadOnly(boolean readOnly);
070
071 /**
072 * Add a valueModel for the given property. Property should be accessible on
073 * the formObject.
074 *
075 * @param propertyName the property to create a valueModel for.
076 * @return a ValueModel that wraps the property.
077 */
078 ValueModel add(String propertyName);
079
080 /**
081 * Add the given valueModel as wrapper for the given property. Property
082 * should be accessible on the formObject. Note that the given valueModel
083 * should be used to access the property, but may be wrapped(chained) a
084 * number of times in other valueModels.
085 *
086 * @param propertyName the property.
087 * @param valueModel the valueModel to access the property.
088 * @return a valueModel that wraps the given valueModel.
089 */
090 ValueModel add(String propertyName, ValueModel valueModel);
091
092 /**
093 * Add the given valueModel as wrapper for the given property. Note that the
094 * given valueModel should be used to access the property, but may be
095 * wrapped(chained) a number of times in other valueModels.
096 *
097 * <p>
098 * This adds another dimension to the formModel as this makes it possible to
099 * provide your own property that is not present on the formObject but does
100 * have a valueModel and metadata to bind fields and listen to.
101 * </p>
102 *
103 * @param propertyName the property, possibly not bound to the formObject.
104 * @param valueModel the valueModel to access the property.
105 * @param fieldMetadata the metadata for this valueModel.
106 * @return a valueModel that is or wraps the given valueModel.
107 *
108 * @see org.springframework.binding.value.DerivedValueModel
109 * @see org.springframework.binding.value.support.AbstractDerivedValueModel
110 * @see org.springframework.binding.value.support.MessageFormatValueModel
111 */
112 ValueModel add(String propertyName, ValueModel valueModel, FieldMetadata fieldMetadata);
113
114 /**
115 * Add a valueModel that holds a derived value computed by invoking the
116 * given method with the given property as argument on the formModel.
117 *
118 * @param propertyMethodName method to invoke.
119 * @param derivedFromProperty property to use as argument.
120 * @return a valueModel holding the derived value.
121 */
122 ValueModel addMethod(String propertyMethodName, String derivedFromProperty);
123
124 /**
125 * Add a valueModel that holds a derived value computed by invoking the
126 * given method with a number of other properties as arguments on the
127 * formModel.
128 *
129 * @param propertyMethodName method to invoke.
130 * @param derivedFromProperties a number of properties to use as arguments
131 * on the method.
132 * @return a valueModel holding the derived value.
133 */
134 ValueModel addMethod(String propertyMethodName, String[] derivedFromProperties);
135 }