    001// Licensed under the Apache License, Version 2.0 (the "License");
    002// you may not use this file except in compliance with the License.
    003// You may obtain a copy of the License at
    004//
    005//     http://www.apache.org/licenses/LICENSE-2.0
    006//
    007// Unless required by applicable law or agreed to in writing, software
    008// distributed under the License is distributed on an "AS IS" BASIS,
    009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    010// See the License for the specific language governing permissions and
    011// limitations under the License.
    012
    013package org.apache.tapestry5.services;
    014
    015import org.apache.tapestry5.ClientElement;
    016import org.apache.tapestry5.ComponentAction;
    017import org.apache.tapestry5.Field;
    018
    019/**
    020 * Services provided by an enclosing Form control component to the various form element components it encloses.
    021 * Implements {@link org.apache.tapestry5.ClientElement}, to share the id of the enclosing form.
    022 *
    023 * @see org.apache.tapestry5.Field
    024 */
    025public interface FormSupport extends ClientElement
    026{
    027    /**
    028     * Allocates a unique (within the form) control name for some enclosed component, based on the component's id.
    029     *
    030     * @param id
    031     *         the component's id
    032     * @return a unique string, usually the component's id, but sometime extended with a unique number or string
    033     */
    034    String allocateControlName(String id);
    035
    036    /**
    037     * Stores an action for execution during a later request.  If the action contains any mutable state, it should be in
    038     * its final state before invoking this method and its internal state should not be changed subsequently.
    039     */
    040    <T> void store(T component, ComponentAction<T> action);
    041
    042    /**
    043     * Stores an action for execution in a later request when the containing form is canceled. Cancel actions
    044     * are triggered before the form fires its {@link org.apache.tapestry5.EventConstants#CANCELED} event.
    045     *
    046     * @since 5.4
    047     */
    048    <T> void storeCancel(T component, ComponentAction<T> action);
    049
    050    /**
    051     * As with {@link #store(Object, org.apache.tapestry5.ComponentAction)}}, but the action is also invoked
    052     * immediately. This is useful for defining an action that should occur symmetrically in both the render request and
    053     * the form submission's action request.
    054     *
    055     * @param component
    056     *         component against which to trigger the action
    057     * @param action
    058     *         the action that will be triggered (and passed the component)
    059     */
    060    <T> void storeAndExecute(T component, ComponentAction<T> action);
    061
    062    /**
    063     * Defers a command until the end of the form submission. The command will be executed <em>before</em> the Form's
    064     * validate notification, but after all other submit actions for the form have been processed. This is used,
    065     * primarily, to coordinate validations or other operations that involve multiple components, when the order of the
    066     * components can not be determined. During a form render, runnables are executed after the body of the form has
    067     * rendered.
    068     *
    069     * @param command
    070     *         to be executed
    071     */
    072    void defer(Runnable command);
    073
    074    /**
    075     * Sets the encoding type for the Form. This should only be set once, and if
    076     *
    077     * @param encodingType
    078     *         MIME type indicating type of encoding for the form
    079     * @throws IllegalStateException
    080     *         if the encoding type has already been set to a value different than the supplied
    081     */
    082    void setEncodingType(String encodingType);
    083
    084    /**
    085     * Collects field validation information. A Form may turn off client-side validation, in which case these calls will
    086     * be ignored.
    087     *
    088     * @param field
    089     *         for which validation is being generated
    090     * @param validationName
    091     *         name of validation method (see Tapestry.Validation in tapestry.js)
    092     * @param message
    093     *         the error message to display if the field is invalid
    094     * @param constraint
    095     *         additional constraint value, or null for validations that don't require a constraint
    096     * @deprecated Deprecated in 5.4 with no exact replacement; this default implementation now does nothing.
    097     * Invoke {@link #isClientValidationEnabled()}, and (if true),
    098     * use {@link org.apache.tapestry5.services.javascript.JavaScriptSupport} to add necessary modules, and add
    099     * triggering and configuring attributes to the field's {@link org.apache.tapestry5.dom.Element}.
    100     */
    101    void addValidation(Field field, String validationName, String message, Object constraint);
    102
    103    /**
    104     * Return true if client validation is enabled for this form, false otherwise.
    105     */
    106    boolean isClientValidationEnabled();
    107
    108    /**
    109     * Returns the complete id of the underlying Form component.
    110     *
    111     */
    112    String getFormComponentId();
    113
    114    /**
    115     * Id used as a prefix when searching {@link org.apache.tapestry5.ioc.Messages} for validation messages and
    116     * constraints. This is normally the simple id of the form.
    117     *
    118     * @return validation id string
    119     * @see org.apache.tapestry5.services.FieldTranslatorSource
    120     * @see org.apache.tapestry5.services.FieldValidatorSource
    121     */
    122    String getFormValidationId();
    123}