FormBehavior


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