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}