001 // Copyright 2006, 2007, 2008 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.tapestry5.services;
016
017 import org.apache.tapestry5.ClientElement;
018 import org.apache.tapestry5.ComponentAction;
019 import org.apache.tapestry5.Field;
020
021 /**
022 * Services provided by an enclosing Form control component to the various form element components it encloses.
023 * Implements {@link org.apache.tapestry5.ClientElement}, to share the id of the enclosing form.
024 *
025 * @see org.apache.tapestry5.Field
026 */
027 public interface FormSupport extends ClientElement
028 {
029 /**
030 * Allocates a unique (within the form) control name for some enclosed component, based on the component's id.
031 *
032 * @param id the component's id
033 * @return a unique string, usually the component's id, but sometime extended with a unique number or string
034 */
035 String allocateControlName(String id);
036
037 /**
038 * Stores an action for execution during a later request. If the action contains any mutable state, it should be in
039 * its final state before invoking this method and its internal state should not be changed subsequently.
040 */
041 <T> void store(T component, ComponentAction<T> action);
042
043 /**
044 * As with {@link #store(Object, org.apache.tapestry5.ComponentAction)}}, but the action is also invoked
045 * immediately. This is useful for defining an action that should occur symmetrically in both the render request and
046 * the form submission's action request.
047 *
048 * @param component component against which to trigger the action
049 * @param action the action that will be triggered (and passed the component)
050 */
051 <T> void storeAndExecute(T component, ComponentAction<T> action);
052
053 /**
054 * Defers a command until the end of the form submission. The command will be executed <em>before</em> the Form's
055 * validate notification, but after all other submit actions for the form have been processed. This is used,
056 * primarily, to coordinate validations or other operations that involve multiple components, when the order of the
057 * components can not be determined. During a form render, runnables are executed after the body of the form has
058 * rendered.
059 *
060 * @param command to be executed
061 */
062 void defer(Runnable command);
063
064 /**
065 * Sets the encoding type for the Form. This should only be set once, and if
066 *
067 * @param encodingType MIME type indicating type of encoding for the form
068 * @throws IllegalStateException if the encoding type has already been set to a value different than the supplied
069 */
070 void setEncodingType(String encodingType);
071
072 /**
073 * Collects field validation information. A Form may turn off client-side validation, in which case these calls will
074 * be ignored.
075 *
076 * @param field for which validation is being generated
077 * @param validationName name of validation method (see Tapestry.Validation in tapestry.js)
078 * @param message the error message to display if the field is invalid
079 * @param constraint additional constraint value, or null for validations that don't require a constraint
080 */
081 void addValidation(Field field, String validationName, String message, Object constraint);
082
083 /**
084 * Return true if client validation is enabled for this form, false otherwise.
085 */
086 boolean isClientValidationEnabled();
087
088 /**
089 * Returns the complete id of the underlying Form component. This is needed by {@link
090 * org.apache.tapestry5.corelib.components.FormInjector}.
091 */
092 String getFormComponentId();
093
094 /**
095 * Id used as a prefix when searching {@link org.apache.tapestry5.ioc.Messages} for validation messages and
096 * constraints. This is normally the simple id of the form.
097 *
098 * @return validation id string
099 * @see org.apache.tapestry5.services.FieldTranslatorSource
100 * @see org.apache.tapestry5.services.FieldValidatorSource
101 */
102 String getFormValidationId();
103 }