Coverage Report - org.apache.tapestry.FormBehavior
 
Classes in this File Line Coverage Branch Coverage Complexity
FormBehavior
N/A 
N/A 
1
 
 1  
 // Copyright 2005 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.tapestry;
 16  
 
 17  
 import org.apache.hivemind.ApplicationRuntimeException;
 18  
 import org.apache.hivemind.Location;
 19  
 import org.apache.tapestry.form.FormEventType;
 20  
 import org.apache.tapestry.form.IFormComponent;
 21  
 import org.apache.tapestry.json.JSONObject;
 22  
 import org.apache.tapestry.services.ResponseBuilder;
 23  
 import org.apache.tapestry.valid.ValidationConstants;
 24  
 
 25  
 /**
 26  
  * Common interface extended by {@link org.apache.tapestry.IForm} and
 27  
  * {@link org.apache.tapestry.form.FormSupport}.
 28  
  * 
 29  
  * @author Howard M. Lewis Ship
 30  
  * @since 4.0
 31  
  */
 32  
 public interface FormBehavior
 33  
 {
 34  
     /**
 35  
      * Adds an additional event handler. The type determines when the handler will be invoked,
 36  
      * {@link FormEventType#SUBMIT}is most typical.
 37  
      * 
 38  
      * @deprecated Wiring of form event handlers is now managed on the client side. This method may
 39  
      *             be removed in a future release of Tapestry.
 40  
      */
 41  
     void addEventHandler(FormEventType type, String functionName);
 42  
 
 43  
     /**
 44  
      * Adds a hidden field value to be stored in the form. This ensures that all of the <input
 45  
      * type="hidden"> (or equivalent) are grouped together, which ensures that the output HTML is
 46  
      * valid (ie. doesn't have <input> improperly nested with <tr>, etc.).
 47  
      * <p>
 48  
      * It is acceptible to add multiple hidden fields with the same name. They will be written in
 49  
      * the order they are received.
 50  
      */
 51  
 
 52  
     void addHiddenValue(String name, String value);
 53  
 
 54  
     /**
 55  
      * Adds a hidden field value to be stored in the form. This ensures that all of the &lt;input
 56  
      * type="hidden"&gt; (or equivalent) are grouped together, which ensures that the output HTML is
 57  
      * valid (ie. doesn't have &lt;input&gt; improperly nested with &lt;tr&gt;, etc.).
 58  
      * <p>
 59  
      * It is acceptible to add multiple hidden fields with the same name. They will be written in
 60  
      * the order they are received.
 61  
      * 
 62  
      * @since 3.0
 63  
      */
 64  
 
 65  
     void addHiddenValue(String name, String id, String value);
 66  
 
 67  
     /**
 68  
      * Constructs a unique identifier (within the Form). The identifier consists of the component's
 69  
      * id, with an index number added to ensure uniqueness.
 70  
      * <p>
 71  
      * Simply invokes {@link #getElementId(IFormComponent, String)}with the component's id.
 72  
      * <p>
 73  
      * Note: yes, some confusion on naming here. This is the form element id, which should be (for
 74  
      * Tapestry purposes) unique within the rendered form. The {@link IFormComponent#getClientId()}
 75  
      * is different, and should be unique within the rendered page.
 76  
      */
 77  
 
 78  
     String getElementId(IFormComponent component);
 79  
 
 80  
     /**
 81  
      * Constructs a unique identifier from the base id. If possible, the id is used as-is.
 82  
      * Otherwise, a unique identifier is appended to the id.
 83  
      * <p>
 84  
      * This method is provided simply so that some components (
 85  
      * {@link org.apache.tapestry.form.ImageSubmit}) have more specific control over their names.
 86  
      * <p>
 87  
      * Invokes {@link IFormComponent#setName(String)}with the result, as well as returning it.
 88  
      * 
 89  
      * @throws StaleLinkException
 90  
      *             if, when the form itself is rewinding, the element id allocated does not match
 91  
      *             the expected id (as allocated when the form rendered). This indicates that the
 92  
      *             state of the application has changed between the time the form renderred and the
 93  
      *             time it was submitted.
 94  
      */
 95  
 
 96  
     String getElementId(IFormComponent component, String baseId);
 97  
     
 98  
     /**
 99  
      * Used internally to "peek" at what the next generated client id will be for the 
 100  
      * given component when it renders. Similar to the logic found in {@link IRequestCycle#peekUniqueId(String)}.
 101  
      * 
 102  
      * @return The next possible client ID for the component.
 103  
      */
 104  
     String peekClientId(IFormComponent component);
 105  
     
 106  
     /**
 107  
      * Returns true if the form is rewinding (meaning, the form was the subject of the request
 108  
      * cycle).
 109  
      */
 110  
 
 111  
     boolean isRewinding();
 112  
 
 113  
     /**
 114  
      * May be invoked by a component to force the encoding type of the form to a particular value.
 115  
      * 
 116  
      * @see org.apache.tapestry.form.Upload
 117  
      * @throws ApplicationRuntimeException
 118  
      *             if the current encoding type is not null and doesn't match the provided encoding
 119  
      *             type
 120  
      */
 121  
 
 122  
     void setEncodingType(String encodingType);
 123  
 
 124  
     /**
 125  
      * Pre-renders the specified field, buffering the result for later use by
 126  
      * {@link #wasPrerendered(IMarkupWriter, IComponent)}. Typically, it is a
 127  
      * {@link org.apache.tapestry.valid.FieldLabel}&nbsp;component that pre-renders an associated
 128  
      * field. This little dance is necessary to properly support field labels inside loops, and to
 129  
      * handle the portlet action/render request cycle.
 130  
      * 
 131  
      * @param writer
 132  
      *            the markup writer (from which a nested markup writer is obtained)
 133  
      * @param field
 134  
      *            the field to pre-render. The field is responsible for invoking
 135  
      *            {@link #wasPrerendered(IMarkupWriter, IComponent)}.
 136  
      * @param location
 137  
      *            an optional location (of the FieldLabel component) used when reporting errors.
 138  
      */
 139  
     void prerenderField(IMarkupWriter writer, IComponent field, Location location);
 140  
 
 141  
     /**
 142  
      * Invoked by a form control component (a field) that may have been pre-rendered. If the field
 143  
      * was pre-rendered, then the buffered output is printed into the writer and true is returned.
 144  
      * Otherwise, false is returned.
 145  
      * 
 146  
      * @return true if the field was pre-rendered and should do nothing during its render phase,
 147  
      *         false if the field should continue as normal.
 148  
      */
 149  
     boolean wasPrerendered(IMarkupWriter writer, IComponent field);
 150  
     
 151  
     /**
 152  
      * Adds a deferred runnable, an object to be executed either before the &lt;/form&gt; tag is
 153  
      * rendered (when rendering), or before the form's listener is invoked (when rewinding).
 154  
      * Runnables are executed in the order in which they are added.
 155  
      * 
 156  
      * @param runnable
 157  
      *            the object to execute (which may not be null)
 158  
      */
 159  
 
 160  
     void addDeferredRunnable(Runnable runnable);
 161  
 
 162  
     /**
 163  
      * Registers a field for automatic focus. The goal is for the first field that is in error to
 164  
      * get focus; failing that, the first required field; failing that, any field.
 165  
      * 
 166  
      * @param field
 167  
      *            the field requesting focus
 168  
      * @param priority
 169  
      *            a priority level used to determine whether the registered field becomes the focus
 170  
      *            field. Constants for this purpose are defined in {@link ValidationConstants}.
 171  
      * @since 4.0
 172  
      */
 173  
 
 174  
     void registerForFocus(IFormComponent field, int priority);
 175  
 
 176  
     /**
 177  
      * The javascript object profile being built by this context to validate/translate
 178  
      * form values.
 179  
      * @return {@link JSONObject} profile.
 180  
      */
 181  
     JSONObject getProfile();
 182  
     
 183  
     /**
 184  
      * Sets a flag denoting whether or not an {@link IFormComponent} field has been
 185  
      * updated according to the logic defined in 
 186  
      * {@link org.apache.tapestry.services.ResponseBuilder#updateComponent(String)}.
 187  
      * 
 188  
      * <p>
 189  
      * Currently this flag is used during ajax/json responses so that cooperating 
 190  
      * {@link ResponseBuilder}s can be worked with to ensure form state is properly
 191  
      * updated on the client. Specifically, that the hidden form input fields and 
 192  
      * any associated validation profiles are updated.
 193  
      * </p>
 194  
      * 
 195  
      * @param value 
 196  
      *          The value to set.
 197  
      */
 198  
     void setFormFieldUpdating(boolean value);
 199  
     
 200  
     /**
 201  
      * Checks to see if a form field has been updated. 
 202  
      * 
 203  
      * @see #setFormFieldUpdating(boolean)
 204  
      * @return True if any form field was updated.
 205  
      */
 206  
     boolean isFormFieldUpdating();
 207  
 }