1   // Copyright 2007, 2008 The Apache Software Foundation
    2   //
    3   // Licensed under the Apache License, Version 2.0 (the "License");
    4   // you may not use this file except in compliance with the License.
    5   // You may obtain a copy of the License at
    6   //
    7   //     http://www.apache.org/licenses/LICENSE-2.0
    8   //
    9   // Unless required by applicable law or agreed to in writing, software
   10   // distributed under the License is distributed on an "AS IS" BASIS,
   11   // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   12   // See the License for the specific language governing permissions and
   13   // limitations under the License.
   14   
   15   package org.apache.tapestry5.internal.services;
   16   
   17   import org.apache.tapestry5.Field;
   18   import org.apache.tapestry5.Link;
   19   import org.apache.tapestry5.corelib.data.InsertPosition;
   20   
   21   /**
   22    * Collects details about zone usage for efficient initialization of the client side objects.  This has grown to include
   23    * the client-side behavior associated with {@link org.apache.tapestry5.corelib.components.FormFragment}s.
   24    *
   25    * @see org.apache.tapestry5.corelib.components.Zone
   26    */
   27   public interface ClientBehaviorSupport
   28   {
   29       /**
   30        * Adds a new client-side Tapestry.Zone object. Zones are linked to a an element (typically, a <div>).  A Zone
   31        * may have handlers used to initially show it, or to highlight it when its content changes. Such handlers are
   32        * referenced by name, as functions of the Tapestry.ElementEffect object.
   33        *
   34        * @param clientId           client-side id of the element that will be updated by the zone
   35        * @param showFunctionName   name of the function used to initially show the zone (if not visible), or null for
   36        *                           default
   37        * @param updateFunctionName name of function used to highlight the function after an update, or null for default
   38        */
   39       void addZone(String clientId, String showFunctionName, String updateFunctionName);
   40   
   41       /**
   42        * Sets the client-side onclick handler for an <a> element to perform an Ajax update of a zone.
   43        *
   44        * @param linkId    id of the link to Ajax enable
   45        * @param elementId id of an element that has been previously registered as a Zone
   46        * @param eventLink
   47        */
   48       void linkZone(String linkId, String elementId, Link eventLink);
   49   
   50       /**
   51        * Adds a new client-side Tapestry.FormFragment object.  FormFragment's are used to make parts of a client-side form
   52        * visible or invisible, which involves interactions with both the server-side and client-side validation.
   53        *
   54        * @param clientId         client-side id of the element that will be made visible or invisible
   55        * @param showFunctionName name of function (of the Tapestry.ElementEffect object) used to make the SubForm visible,
   56        *                         or null for the default
   57        * @param hideFunctionName name of the function used to make the SubForm invisible, or null for the default
   58        */
   59       void addFormFragment(String clientId, String showFunctionName, String hideFunctionName);
   60   
   61       /**
   62        * Adds a new client-side Tapestry.FormInjector object.  FormInjectors are used to extend an existing Form with new
   63        * content.
   64        *
   65        * @param clientId         client-side id of the element that identifiess where the new content will be placed
   66        * @param link             action request link used to trigger the server-side object, to render the new content
   67        * @param insertPosition   where the new content should go (above or below the element)
   68        * @param showFunctionName name of function (of the Tapestry.ElementEffect object) used to make the new element
   69        *                         visible, or null for the default
   70        */
   71       void addFormInjector(String clientId, Link link, InsertPosition insertPosition, String showFunctionName);
   72   
   73       /**
   74        * Collects field validation information.
   75        *
   76        * @param field          for which validation is being generated
   77        * @param validationName name of validation method (see Tapestry.Validation in tapestry.js)
   78        * @param message        the error message to display if the field is invalid
   79        * @param constraint     additional constraint value, or null for validations that don't require a constraint
   80        */
   81       void addValidation(Field field, String validationName, String message, Object constraint);
   82   }
   83