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