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