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 org.apache.struts.action.ActionMessages;
23 import org.apache.velocity.tools.Scope;
24 import org.apache.velocity.tools.config.DefaultKey;
25 import org.apache.velocity.tools.config.ValidScope;
26
27 /**
28 * <p>
29 * This tool deals with Struts error messages. Errors may stem from the validation
30 * of a submitted form or from the processing of a request. If there are errors,
31 * they are made available to the view to render. A few important aspects about errors
32 * are:</p>
33 * <ul>
34 * <li>Error message strings are looked up in the message resources. Support
35 * for internationalized messages is provided.</li>
36 * <li>Error messages can have up to five replacement parameters.</li>
37 * <li>Errors have an attribute <code>property</code> that describes the category of
38 * error. This allows the view designer to place error messages precisely where an
39 * error occurred. For example, errors that apply to the entire page can be rendered
40 * at the top of the page, errors that apply to a specific input field can be rendered
41 * next to this input field. Several methods of this tool provide a parameter
42 * <code>property</code> that allows to select a specific category of errors to operate
43 * on. Without the <code>property</code> parameter, methods operate on all error messages.</li>
44 * </ul>
45 *
46 * <p>See the Struts User's Guide, section
47 * <a href="http://struts.apache.org/1.3.8/userGuide/building_view.html">Building View Components</a>
48 * for more information on this topic.</p>
49 *
50 * <p><pre>
51 * Template example(s):
52 * #if( $errors.exist() )
53 * <div class="errors">
54 * #foreach( $e in $errors.all )
55 * $e <br>
56 * #end
57 * </div>
58 * #end
59 *
60 * Toolbox configuration:
61 * <tools>
62 * <toolbox scope="request">
63 * <tool class="org.apache.velocity.tools.struts.ErrorsTool"/>
64 * </toolbox>
65 * </tools>
66 * </pre></p>
67 *
68 * <p>This tool should only be used in the request scope.</p>
69 * <p>Since VelocityTools 1.1, ErrorsTool extends ActionMessagesTool.</p>
70 *
71 * @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>
72 * @author Nathan Bubna
73 * @since VelocityTools 1.0
74 * @version $Id: ErrorsTool.java 601976 2007-12-07 03:50:51Z nbubna $
75 */
76 @DefaultKey("errors")
77 @ValidScope(Scope.REQUEST)
78 public class ErrorsTool extends ActionMessagesTool
79 {
80
81 protected ActionMessages getActionMessages()
82 {
83 if (this.actionMsgs == null)
84 {
85 this.actionMsgs = StrutsUtils.getErrors(this.request);
86 }
87 return this.actionMsgs;
88 }
89
90
91 /**
92 * <p>Renders the queued error messages as a list. This method expects
93 * the message keys <code>errors.header</code> and <code>errors.footer</code>
94 * in the message resources. The value of the former is rendered before
95 * the list of error messages and the value of the latter is rendered
96 * after the error messages.</p>
97 *
98 * @return The formatted error messages. If no error messages are queued,
99 * an empty string is returned.
100 */
101 public String getMsgs()
102 {
103 return getMsgs(null, null);
104 }
105
106
107 /**
108 * <p>Renders the queued error messages of a particual category as a list.
109 * This method expects the message keys <code>errors.header</code> and
110 * <code>errors.footer</code> in the message resources. The value of the
111 * former is rendered before the list of error messages and the value of
112 * the latter is rendered after the error messages.</p>
113 *
114 * @param property the category of errors to render
115 *
116 * @return The formatted error messages. If no error messages are queued,
117 * an empty string is returned.
118 */
119 public String getMsgs(String property)
120 {
121 return getMsgs(property, null);
122 }
123
124
125 /**
126 * <p>Renders the queued error messages of a particual category as a list.
127 * This method expects the message keys <code>errors.header</code> and
128 * <code>errors.footer</code> in the message resources. The value of the
129 * former is rendered before the list of error messages and the value of
130 * the latter is rendered after the error messages.</p>
131 *
132 * @param property the category of errors to render
133 * @param bundle the message resource bundle to use
134 *
135 * @return The formatted error messages. If no error messages are queued,
136 * an empty string is returned.
137 * @since VelocityTools 1.1
138 */
139 public String getMsgs(String property, String bundle)
140 {
141 return StrutsUtils.errorMarkup(property, bundle, request,
142 request.getSession(false), application);
143 }
144
145 }