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 * 
025 * @see org.apache.tapestry5.corelib.components.Zone
026 */
027public 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}