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 * <input type="hidden" name="$form.tokenName" value="$form.token"> 44 * <input type="submit" name="$form.cancelName" value="Cancel"> 45 * 46 * Toolbox configuration: 47 * <tools> 48 * <toolbox scope="request"> 49 * <tool class="org.apache.velocity.tools.struts.FormTool"/> 50 * </toolbox> 51 * </tools> 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 * <input type="text" name="username" value="$defaults.username"> 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 }