View Javadoc

1   package org.apache.velocity.tools.struts;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  import javax.servlet.http.HttpServletRequest;
23  import javax.servlet.http.HttpSession;
24  import org.apache.struts.action.ActionForm;
25  import org.apache.velocity.tools.view.ViewContext;
26  import org.apache.velocity.tools.Scope;
27  import org.apache.velocity.tools.config.DefaultKey;
28  import org.apache.velocity.tools.config.ValidScope;
29  
30  /**
31   * <p>View tool to work with HTML forms in Struts.</p>
32   * 
33   * <p>Struts has support to parse incoming HTTP requests and populate a Java bean
34   * with the submitted request parameters. The same Java bean is used to populate
35   * forms with initial values. Additionally, a hook allows the application developer
36   * to include automatic form validation code.</p>
37   * 
38   * <p>FormTool provides miscellaneous methods to work with forms and form bean in
39   * the context of Struts applications.</p>
40   * 
41   * <p><pre>
42   * Template example(s):
43   *  &lt;input type="hidden" name="$form.tokenName" value="$form.token"&gt;
44   *  &lt;input type="submit" name="$form.cancelName" value="Cancel"&gt;
45   *
46   * Toolbox configuration:
47   * &lt;tools&gt;
48   *   &lt;toolbox scope="request"&gt;
49   *     &lt;tool class="org.apache.velocity.tools.struts.FormTool"/&gt;
50   *   &lt;/toolbox&gt;
51   * &lt;/tools&gt;
52   * </pre></p>
53   *
54   * <p>This tool may only be used in the request scope.</p>
55   *
56   * @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>
57   * @since VelocityTools 1.0
58   * @version $Id: FormTool.java 601976 2007-12-07 03:50:51Z nbubna $
59   */
60  @DefaultKey("form")
61  @ValidScope(Scope.REQUEST)
62  public class FormTool
63  {
64  
65      // --------------------------------------------- Properties ---------------
66  
67  
68      /**
69       * A reference to the HtttpServletRequest.
70       */
71      protected HttpServletRequest request;
72  
73  
74      /**
75       * A reference to the HtttpSession.
76       */
77      protected HttpSession session;
78  
79  
80  
81      // --------------------------------------------- Constructors -------------
82  
83      @Deprecated
84      public void init(Object obj)
85      {
86          if (obj instanceof ViewContext)
87          {
88              setRequest(((ViewContext)obj).getRequest());
89          }
90      }
91  
92      /**
93       * Initializes this tool.
94       *
95       * @param request the current {@link HttpServletRequest}
96       * @throws IllegalArgumentException if the param is not a ViewContext
97       */
98      public void setRequest(HttpServletRequest request)
99      {
100         if (request == null)
101         {
102             throw new NullPointerException("request should not be null");
103         }
104         this.request = request;
105         this.session = request.getSession(false);
106     }
107 
108 
109 
110     // --------------------------------------------- View Helpers -------------
111 
112     /**
113      * <p>Returns the form bean associated with this action mapping.</p>
114      *
115      * <p>This is a convenience method. The form bean is automatically
116      * available in the Velocity context under the name defined in the
117      * Struts configuration.</p>
118      *
119      * <p>If the form bean is used repeatedly, it is recommended to create a
120      * local variable referencing the bean rather than calling getBean()
121      * multiple times.</p>
122      *
123      * <pre>
124      * Example:
125      * #set ($defaults = $form.bean)
126      * &lt;input type="text" name="username" value="$defaults.username"&gt;
127      * </pre>
128      *
129      * @return the {@link ActionForm} associated with this request or
130      * <code>null</code> if there is no form bean associated with this mapping
131      */
132     public ActionForm getBean()
133     {
134         return StrutsUtils.getActionForm(request, session);
135     }
136 
137     /**
138      * <p>Returns the form bean name associated with this action mapping.</p>
139      *
140      * @return the name of the ActionForm associated with this request or
141      * <code>null</code> if there is no form bean associated with this mapping
142      */
143     public String getName()
144     {
145         return StrutsUtils.getActionFormName(request, session);
146     }
147 
148 
149 
150     /**
151      * <p>Returns the query parameter name under which a cancel button press
152      * must be reported if form validation is to be skipped.</p>
153      *
154      * <p>This is the value of
155      * <code>org.apache.struts.taglib.html.Constants.CANCEL_PROPERTY</code></p>
156      */
157     public String getCancelName()
158     {
159         return org.apache.struts.taglib.html.Constants.CANCEL_PROPERTY;
160     }
161 
162 
163     /**
164      * Returns the transaction control token for this session or
165      * <code>null</code> if no token exists.
166      */
167     public String getToken()
168     {
169         return StrutsUtils.getToken(session);
170     }
171 
172 
173     /**
174      * <p>Returns the query parameter name under which a transaction token
175      * must be reported. This is the value of
176      * <code>org.apache.struts.taglib.html.Constants.TOKEN_KEY</code></p>
177      */
178     public String getTokenName()
179     {
180         return org.apache.struts.taglib.html.Constants.TOKEN_KEY;
181     }
182 
183 }