001// Copyright 2006-2014 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
033     *         the component's id
034     * @return a unique string, usually the component's id, but sometime extended with a unique number or string
035     */
036    String allocateControlName(String id);
037
038    /**
039     * Stores an action for execution during a later request.  If the action contains any mutable state, it should be in
040     * its final state before invoking this method and its internal state should not be changed subsequently.
041     */
042    <T> void store(T component, ComponentAction<T> action);
043
044    /**
045     * Stores an action for execution in a later request when the containing form is canceled. Cancel actions
046     * are triggered before the form fires its {@link org.apache.tapestry5.EventConstants#CANCELED} event.
047     *
048     * @since 5.4
049     */
050    <T> void storeCancel(T component, ComponentAction<T> action);
051
052    /**
053     * As with {@link #store(Object, org.apache.tapestry5.ComponentAction)}}, but the action is also invoked
054     * immediately. This is useful for defining an action that should occur symmetrically in both the render request and
055     * the form submission's action request.
056     *
057     * @param component
058     *         component against which to trigger the action
059     * @param action
060     *         the action that will be triggered (and passed the component)
061     */
062    <T> void storeAndExecute(T component, ComponentAction<T> action);
063
064    /**
065     * Defers a command until the end of the form submission. The command will be executed <em>before</em> the Form's
066     * validate notification, but after all other submit actions for the form have been processed. This is used,
067     * primarily, to coordinate validations or other operations that involve multiple components, when the order of the
068     * components can not be determined. During a form render, runnables are executed after the body of the form has
069     * rendered.
070     *
071     * @param command
072     *         to be executed
073     */
074    void defer(Runnable command);
075
076    /**
077     * Sets the encoding type for the Form. This should only be set once, and if
078     *
079     * @param encodingType
080     *         MIME type indicating type of encoding for the form
081     * @throws IllegalStateException
082     *         if the encoding type has already been set to a value different than the supplied
083     */
084    void setEncodingType(String encodingType);
085
086    /**
087     * Collects field validation information. A Form may turn off client-side validation, in which case these calls will
088     * be ignored.
089     *
090     * @param field
091     *         for which validation is being generated
092     * @param validationName
093     *         name of validation method (see Tapestry.Validation in tapestry.js)
094     * @param message
095     *         the error message to display if the field is invalid
096     * @param constraint
097     *         additional constraint value, or null for validations that don't require a constraint
098     * @deprecated Deprecated in 5.4 with no exact replacement; this default implementation now does nothing.
099     * Invoke {@link #isClientValidationEnabled()}, and (if true),
100     * use {@link org.apache.tapestry5.services.javascript.JavaScriptSupport} to add necessary modules, and add
101     * triggering and configuring attributes to the field's {@link org.apache.tapestry5.dom.Element}.
102     */
103    void addValidation(Field field, String validationName, String message, Object constraint);
104
105    /**
106     * Return true if client validation is enabled for this form, false otherwise.
107     */
108    boolean isClientValidationEnabled();
109
110    /**
111     * Returns the complete id of the underlying Form component.  This is needed by {@link
112     * org.apache.tapestry5.corelib.components.FormInjector}.
113     */
114    String getFormComponentId();
115
116    /**
117     * Id used as a prefix when searching {@link org.apache.tapestry5.ioc.Messages} for validation messages and
118     * constraints. This is normally the simple id of the form.
119     *
120     * @return validation id string
121     * @see org.apache.tapestry5.services.FieldTranslatorSource
122     * @see org.apache.tapestry5.services.FieldValidatorSource
123     */
124    String getFormValidationId();
125}