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 }