    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.Field;
    016import org.apache.tapestry5.corelib.data.InsertPosition;
    017import org.apache.tapestry5.http.Link;
    018
    019/**
    020 * Collects details about zone usage for efficient initialization of the client side objects. This has grown to include
    021 * the client-side behavior associated with {@link org.apache.tapestry5.corelib.components.FormFragment}s.
    022 *
    023 * This interface is only kept for binary compatibility in Tapestry 5.4; the implementation no longer does anything but
    024 * throw exceptions and will be removed in 5.5.
    025 *
    026 * @see org.apache.tapestry5.corelib.components.Zone
    027 * @deprecated Deprecated in 5.4 with no replacement. Use {@link org.apache.tapestry5.services.javascript.JavaScriptSupport} directly,
    028 *             instead.
    029 */
    030public interface ClientBehaviorSupport
    031{
    032    /**
    033     * Adds a new client-side Tapestry.Zone object. Zones are linked to a an element (typically, a &lt;div&gt;). A Zone
    034     * may have handlers used to initially show it, or to highlight it when its content changes. Such handlers are
    035     * referenced by name, as functions of the Tapestry.ElementEffect object.
    036     *
    037     * @param clientId
    038     *         client-side id of the element that will be updated by the zone
    039     * @param showFunctionName
    040     *         name of the function used to initially show the zone (if not visible), or null for
    041     *         default
    042     * @param updateFunctionName
    043     *         name of function used to highlight the function after an update, or null for default
    044     */
    045    void addZone(String clientId, String showFunctionName, String updateFunctionName);
    046
    047    /**
    048     * Sets the client-side onclick handler for an &lt;a&gt; element to perform an Ajax update of a zone.
    049     *
    050     * Starting in Tapestry 5.4, this can be accomplished by adding a "data-update-zone" attribute
    051     * to the element.  The attribute value may be {@code ^} or the id of the zone's client element.
    052     *
    053     * @param linkId
    054     *         id of the link to Ajax enable
    055     * @param elementId
    056     *         id of an element that has been previously registered as a Zone
    057     * @param eventLink
    058     */
    059    void linkZone(String linkId, String elementId, Link eventLink);
    060
    061    /**
    062     * Adds a new client-side Tapestry.FormFragment object. FormFragment's are used to make parts of a client-side form
    063     * visible or invisible, which involves interactions with both the server-side and client-side validation.
    064     *
    065     * @param clientId
    066     *         client-side id of the element that will be made visible or invisible
    067     * @param showFunctionName
    068     *         name of function (of the Tapestry.ElementEffect object) used to make the SubForm visible,
    069     *         or null for the default
    070     * @param hideFunctionName
    071     *         name of the function used to make the SubForm invisible, or null for the default
    072     * @deprecated Use {@link #addFormFragment(String, boolean, String, String, String)} instead
    073     */
    074    void addFormFragment(String clientId, String showFunctionName, String hideFunctionName);
    075
    076    /**
    077     * Adds a new client-side Tapestry.FormFragment object. FormFragment's are used to make parts of a client-side form
    078     * visible or invisible, which involves interactions with both the server-side and client-side validation.
    079     *
    080     * @param clientId
    081     *         client-side id of the element that will be made visible or invisible
    082     * @param alwaysSubmit
    083     *         if true, the fragment ignores client-side visiblility and always submits its values
    084     * @param showFunctionName
    085     *         name of function (of the Tapestry.ElementEffect object) used to make the SubForm visible,
    086     *         or null for the default
    087     * @param hideFunctionName
    088     *         name of the function used to make the SubForm invisible, or null for the default
    089     * @deprecated Use {@link #addFormFragment(String, boolean, String, String, String)} instead
    090     */
    091    void addFormFragment(String clientId, boolean alwaysSubmit, String showFunctionName, String hideFunctionName);
    092
    093    /**
    094     * Adds a new client-side Tapestry.FormFragment object. FormFragment's are used to make parts of a client-side form
    095     * visible or invisible, which involves interactions with both the server-side and client-side validation.
    096     *
    097     * <strong>This implementation has been removed in 5.4; it throws an {@link UnsupportedOperationException}.</strong>
    098     *
    099     * @param clientId
    100     *         client-side id of the element that will be made visible or invisible
    101     * @param alwaysSubmit
    102     *         if true, the fragment ignores client-side visiblility and always submits its values
    103     * @param showFunctionName
    104     *         name of function (of the Tapestry.ElementEffect object) used to make the SubForm visible,
    105     *         or null for the default
    106     * @param hideFunctionName
    107     *         name of the function used to make the SubForm invisible, or null for the default
    108     * @param visibilityBoundFunctionName
    109     *         name of the function used to bound the isDeepVisible search, or null for the default
    110     * @since 5.3
    111     * @deprecated In 5.4; use the <code>core/form-fragment</code> module instead.
    112     */
    113    void addFormFragment(String clientId, boolean alwaysSubmit, String showFunctionName, String hideFunctionName, String visibilityBoundFunctionName);
    114
    115    /**
    116     * Adds a new client-side Tapestry.FormInjector object. FormInjectors are used to extend an existing Form with new
    117     * content.
    118     *
    119     * @param clientId
    120     *         client-side id of the element that identifiess where the new content will be placed
    121     * @param link
    122     *         action request link used to trigger the server-side object, to render the new content
    123     * @param insertPosition
    124     *         where the new content should go (above or below the element)
    125     * @param showFunctionName
    126     *         name of function (of the Tapestry.ElementEffect object) used to make the new element
    127     *         visible, or null for the default
    128     */
    129    void addFormInjector(String clientId, Link link, InsertPosition insertPosition, String showFunctionName);
    130
    131    /**
    132     * Collects field validation information.
    133     *
    134     * @param field
    135     *         for which validation is being generated
    136     * @param validationName
    137     *         name of validation method (see Tapestry.Validation in tapestry.js)
    138     * @param message
    139     *         the error message to display if the field is invalid
    140     * @param constraint
    141     *         additional constraint value, or null for validations that don't require a constraint
    142     */
    143    void addValidation(Field field, String validationName, String message, Object constraint);
    144}