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 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   *     &lt;div class="errors"&gt;
54   *     #foreach( $e in $errors.all )
55   *       $e &lt;br&gt;
56   *     #end
57   *     &lt;/div&gt;
58   *   #end
59   *
60   * Toolbox configuration:
61   * &lt;tools&gt;
62   *   &lt;toolbox scope="request"&gt;
63   *     &lt;tool class="org.apache.velocity.tools.struts.ErrorsTool"/&gt;
64   *   &lt;/toolbox&gt;
65   * &lt;/tools&gt;
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 }