001// Copyright 2006-2014 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.ClientElement; 018import org.apache.tapestry5.ComponentAction; 019import org.apache.tapestry5.Field; 020 021/** 022 * Services provided by an enclosing Form control component to the various form element components it encloses. 023 * Implements {@link org.apache.tapestry5.ClientElement}, to share the id of the enclosing form. 024 * 025 * @see org.apache.tapestry5.Field 026 */ 027public interface FormSupport extends ClientElement 028{ 029 /** 030 * Allocates a unique (within the form) control name for some enclosed component, based on the component's id. 031 * 032 * @param id 033 * the component's id 034 * @return a unique string, usually the component's id, but sometime extended with a unique number or string 035 */ 036 String allocateControlName(String id); 037 038 /** 039 * Stores an action for execution during a later request. If the action contains any mutable state, it should be in 040 * its final state before invoking this method and its internal state should not be changed subsequently. 041 */ 042 <T> void store(T component, ComponentAction<T> action); 043 044 /** 045 * Stores an action for execution in a later request when the containing form is canceled. Cancel actions 046 * are triggered before the form fires its {@link org.apache.tapestry5.EventConstants#CANCELED} event. 047 * 048 * @since 5.4 049 */ 050 <T> void storeCancel(T component, ComponentAction<T> action); 051 052 /** 053 * As with {@link #store(Object, org.apache.tapestry5.ComponentAction)}}, but the action is also invoked 054 * immediately. This is useful for defining an action that should occur symmetrically in both the render request and 055 * the form submission's action request. 056 * 057 * @param component 058 * component against which to trigger the action 059 * @param action 060 * the action that will be triggered (and passed the component) 061 */ 062 <T> void storeAndExecute(T component, ComponentAction<T> action); 063 064 /** 065 * Defers a command until the end of the form submission. The command will be executed <em>before</em> the Form's 066 * validate notification, but after all other submit actions for the form have been processed. This is used, 067 * primarily, to coordinate validations or other operations that involve multiple components, when the order of the 068 * components can not be determined. During a form render, runnables are executed after the body of the form has 069 * rendered. 070 * 071 * @param command 072 * to be executed 073 */ 074 void defer(Runnable command); 075 076 /** 077 * Sets the encoding type for the Form. This should only be set once, and if 078 * 079 * @param encodingType 080 * MIME type indicating type of encoding for the form 081 * @throws IllegalStateException 082 * if the encoding type has already been set to a value different than the supplied 083 */ 084 void setEncodingType(String encodingType); 085 086 /** 087 * Collects field validation information. A Form may turn off client-side validation, in which case these calls will 088 * be ignored. 089 * 090 * @param field 091 * for which validation is being generated 092 * @param validationName 093 * name of validation method (see Tapestry.Validation in tapestry.js) 094 * @param message 095 * the error message to display if the field is invalid 096 * @param constraint 097 * additional constraint value, or null for validations that don't require a constraint 098 * @deprecated Deprecated in 5.4 with no exact replacement; this default implementation now does nothing. 099 * Invoke {@link #isClientValidationEnabled()}, and (if true), 100 * use {@link org.apache.tapestry5.services.javascript.JavaScriptSupport} to add necessary modules, and add 101 * triggering and configuring attributes to the field's {@link org.apache.tapestry5.dom.Element}. 102 */ 103 void addValidation(Field field, String validationName, String message, Object constraint); 104 105 /** 106 * Return true if client validation is enabled for this form, false otherwise. 107 */ 108 boolean isClientValidationEnabled(); 109 110 /** 111 * Returns the complete id of the underlying Form component. This is needed by {@link 112 * org.apache.tapestry5.corelib.components.FormInjector}. 113 */ 114 String getFormComponentId(); 115 116 /** 117 * Id used as a prefix when searching {@link org.apache.tapestry5.ioc.Messages} for validation messages and 118 * constraints. This is normally the simple id of the form. 119 * 120 * @return validation id string 121 * @see org.apache.tapestry5.services.FieldTranslatorSource 122 * @see org.apache.tapestry5.services.FieldValidatorSource 123 */ 124 String getFormValidationId(); 125}