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