    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    }