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
015package org.apache.tapestry5.services;
016
017import org.apache.tapestry5.ClientElement;
018import org.apache.tapestry5.ComponentAction;
019import 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 */
027public 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}