Clover coverage report - Code Coverage for tapestry release 4.0-beta-3
Coverage timestamp: Sun Jul 24 2005 08:26:33 EDT
file stats: LOC: 166   Methods: 0
NCLOC: 19   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
FormBehavior.java - - - -
coverage
 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.valid.ValidationConstants;
 22   
 23    /**
 24    * Common interface extended by {@link org.apache.tapestry.IForm} and
 25    * {@link org.apache.tapestry.form.FormSupport}.
 26    *
 27    * @author Howard M. Lewis Ship
 28    * @since 4.0
 29    */
 30    public interface FormBehavior
 31    {
 32    /**
 33    * Adds an additional event handler. The type determines when the handler will be invoked,
 34    * {@link FormEventType#SUBMIT}is most typical.
 35    *
 36    * @deprecated Wiring of form event handlers is now managed on the client side. This method may
 37    * be removed in a future release of Tapestry.
 38    */
 39    public void addEventHandler(FormEventType type, String functionName);
 40   
 41    /**
 42    * Adds a hidden field value to be stored in the form. This ensures that all of the <input
 43    * type="hidden"> (or equivalent) are grouped together, which ensures that the output HTML is
 44    * valid (ie. doesn't have <input> improperly nested with <tr>, etc.).
 45    * <p>
 46    * It is acceptible to add multiple hidden fields with the same name. They will be written in
 47    * the order they are received.
 48    */
 49   
 50    public void addHiddenValue(String name, String value);
 51   
 52    /**
 53    * Adds a hidden field value to be stored in the form. This ensures that all of the &lt;input
 54    * type="hidden"&gt; (or equivalent) are grouped together, which ensures that the output HTML is
 55    * valid (ie. doesn't have &lt;input&gt; improperly nested with &lt;tr&gt;, etc.).
 56    * <p>
 57    * It is acceptible to add multiple hidden fields with the same name. They will be written in
 58    * the order they are received.
 59    *
 60    * @since 3.0
 61    */
 62   
 63    public void addHiddenValue(String name, String id, String value);
 64   
 65    /**
 66    * Constructs a unique identifier (within the Form). The identifier consists of the component's
 67    * id, with an index number added to ensure uniqueness.
 68    * <p>
 69    * Simply invokes {@link #getElementId(IFormComponent, String)}with the component's id.
 70    * <p>
 71    * Note: yes, some confusion on naming here. This is the form element id, which should be (for
 72    * Tapestry purposes) unique within the rendered form. The {@link IFormComponent#getClientId()}
 73    * is different, and should be unique within the rendered page.
 74    */
 75   
 76    public String getElementId(IFormComponent component);
 77   
 78    /**
 79    * Constructs a unique identifier from the base id. If possible, the id is used as-is.
 80    * Otherwise, a unique identifier is appended to the id.
 81    * <p>
 82    * This method is provided simply so that some components (
 83    * {@link org.apache.tapestry.form.ImageSubmit}) have more specific control over their names.
 84    * <p>
 85    * Invokes {@link IFormComponent#setName(String)}with the result, as well as returning it.
 86    *
 87    * @throws StaleLinkException
 88    * if, when the form itself is rewinding, the element id allocated does not match
 89    * the expected id (as allocated when the form rendered). This indicates that the
 90    * state of the application has changed between the time the form renderred and the
 91    * time it was submitted.
 92    */
 93   
 94    public String getElementId(IFormComponent component, String baseId);
 95   
 96    /**
 97    * Returns true if the form is rewinding (meaning, the form was the subject of the request
 98    * cycle).
 99    */
 100   
 101    public boolean isRewinding();
 102   
 103    /**
 104    * May be invoked by a component to force the encoding type of the form to a particular value.
 105    *
 106    * @see org.apache.tapestry.form.Upload
 107    * @throws ApplicationRuntimeException
 108    * if the current encoding type is not null and doesn't match the provided encoding
 109    * type
 110    */
 111   
 112    public void setEncodingType(String encodingType);
 113   
 114    /**
 115    * Pre-renders the specified field, buffering the result for later use by
 116    * {@link #wasPrerendered(IMarkupWriter, IComponent)}. Typically, it is a
 117    * {@link org.apache.tapestry.valid.FieldLabel}&nbsp;component that pre-renders an associated
 118    * field. This little dance is necessary to properly support field labels inside loops, and to
 119    * handle the portlet action/render request cycle.
 120    *
 121    * @param writer
 122    * the markup writer (from which a nested markup writer is obtained)
 123    * @param field
 124    * the field to pre-render. The field is responsible for invoking
 125    * {@link #wasPrerendered(IMarkupWriter, IComponent)}.
 126    * @param location
 127    * an optional location (of the FieldLabel component) used when reporting errors.
 128    */
 129    public void prerenderField(IMarkupWriter writer, IComponent field, Location location);
 130   
 131    /**
 132    * Invoked by a form control component (a field) that may have been pre-rendered. If the field
 133    * was pre-rendered, then the buffered output is printed into the writer and true is returned.
 134    * Otherwise, false is returned.
 135    *
 136    * @return true if the field was pre-rendered and should do nothing during its render phase,
 137    * false if the field should continue as normal.
 138    */
 139    public boolean wasPrerendered(IMarkupWriter writer, IComponent field);
 140   
 141    /**
 142    * Adds a deferred runnable, an object to be executed either before the &lt;/form&gt; tag is
 143    * rendered (when rendering), or before the form's listener is invoked (when rewinding).
 144    * Runnables are executed in the order in which they are added.
 145    *
 146    * @param runnable
 147    * the object to execute (which may not be null)
 148    */
 149   
 150    public void addDeferredRunnable(Runnable runnable);
 151   
 152    /**
 153    * Registers a field for automatic focus. The goal is for the first field that is in error to
 154    * get focus; failing that, the first required field; failing that, any field.
 155    *
 156    * @param field
 157    * the field requesting focus
 158    * @param priority
 159    * a priority level used to determine whether the registered field becomes the focus
 160    * field. Constants for this purpose are defined in {@link ValidationConstants}.
 161    * @since 4.0
 162    */
 163   
 164    public void registerForFocus(IFormComponent field, int priority);
 165   
 166    }