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