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 <div>). 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 <a> 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    }