dwinterfeldt 01/08/16 09:05:10
Modified: src/share/org/apache/struts/taglib/html package.html
Log:
Added documentation for using messages (ActionMessages, ActionMessage, and
html:messages).
Revision Changes Path
1.7 +84 -3
jakarta-struts/src/share/org/apache/struts/taglib/html/package.html
Index: package.html
===================================================================
RCS file:
/home/cvs/jakarta-struts/src/share/org/apache/struts/taglib/html/package.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- package.html 2001/06/11 16:02:51 1.6
+++ package.html 2001/08/16 16:05:10 1.7
@@ -19,8 +19,8 @@
other components of a Web application. Since a dynamic Web application often
depends on gathering data from a user, input forms play an important role in
the Struts framework. Consequently, the majority of the HTML tags involve <a
href="#doc.Form">HTML</a>
- forms. Other important issues addressed by the Struts-HTML tags are <a
href="#doc.Other.errors">error
- messages</a>, <a href="#doc.Other.hyperlinking">hyperlinking</a> and <a
href="#doc.Other.i18n">internationalization</a>.</p>
+ forms. Other important issues addressed by the Struts-HTML tags are <a
href="#doc.Other.messages">messages</a>,
+ <a href="#doc.Other.errors">error messages</a>, <a
href="#doc.Other.hyperlinking">hyperlinking</a> and <a
href="#doc.Other.i18n">internationalization</a>.</p>
<hr>
<h3><a name="doc.Form">HTML "form" tags</a></h3>
@@ -267,8 +267,85 @@
<hr>
<h3><a name="doc.Other">Other HTML tags</a></h3>
<p>Aside from form processing, the Struts-HTML offers several other tags or tag
- properties to help with displaying error messages, maintaining hyperlinks, and
+ properties to help with displaying error messages, messages, maintaining
hyperlinks, and
with internationalizing your application.</p>
+<h4><a name="doc.Other.messages">Displaying Messages</a></h4>
+<p>Message handling is an important part of any application. These messages
+ can be informative messages and/or error messages for the user. Struts provides
a
+ generalized method for communicating runtime messages to users, based on the
+ same technology used to provide internationalization. Messages and
+ error messages can both be used by the messages tag.</p>
+<p>The messages tag has basically the same functionality as the errors tag, but
+ it iterates through the messages so any formatting of messages can be done
+ in the JSP page. Also the header and footer for the message tag are optional.
</p>
+<p>By default, the messages tag will iterate through all pending messages. You can
also specify
+ a property when queuing a message, and then refer to that property in the messages
+ tag. In that case, only the message(s) for that property will be displayed. This
+ is helpful when you would like to place the message for a field next to the
+ actual field.</p>
+<p>Messages are often queued in the Action. The variable info is the ActionForm
+ corresponding to this Action. :</p>
+<pre>
+ ActionMessages messages = new ActionMessages();
+ messages.add(ActionMessages.GLOBAL_MESSAGE, new
ActionMessage("userForm.insert", info.getUserName());
+ messages.add("activationDate", new ActionMessage("userForm.active",
info.getSubscriptionLength());
+</pre>
+<p>This queues two messages, one is a global message and another for
+ the "activationDate" field. To print all the messages together, simply place the
messages
+ tag anywhere in your JSP.</p>
+<pre>
+ <body bgcolor="white">
+ <ul>
+ <html:messages id="message">
+ <li><bean:write name="message"/></li>
+ </html:messages>
+ </ul>
+</pre>
+<p>Or, you can place specific messages at different locations</p>
+<pre>
+ <ul>
+ <html:messages id="message" property="<%=
org.apache.struts.action.ActionMessages.GLOBAL_MESSAGE %>">
+ <li><bean:write name="message"/></li>
+ </html:messages>
+ </ul>
+ <table>
+ <tr>
+ <td align="left">
+ <html:text property="username" size="16" maxlength="16"/>
+ </td>
+ </tr>
+ <tr>
+ <td align="left">
+ <html:text property="activationDate" size="10" maxlength="10"/>
+ <br>
+ <html:messages id="message" property="activationDate">
+ <bean:write name="message"/><br>
+ </html:messages>
+ </td>
+ </tr>
+ </table>
+</pre>
+<p>By default, the actual message is retrieved from the application's standard
+ message resource. This gives you a master list of the messages used by
+ your application, and provides for internationalization. In the code snippet,
+ the message corresponding to "userForm.insert" would be retrieved and
+ displayed to the user at runtime. </p>
+<pre>
+ userForm.insert={0} has successfully been inserted.
+ userForm.active=The account will be active for {0} months.
+</pre>
+<p>A header and footer are optional. The header will be rendered before iteration
begins
+ and the footer will be rendered after iteration is over. If a value is not
assigned
+ to the attribute, then nothing will be rendered for that attribute.</p>
+<pre>
+ <html:messages id="message" header="errors.header" footer="errors.footer">
+ <li><bean:write name="message"/></li>
+ </html:messages>
+
+ errors.header=<h3><font color="red">Validation
Error</font></h3>
+ You must correct the following error(s) before proceeding:<UL>
+ errors.footer=</ul><hr>
+</pre>
<h4><a name="doc.Other.errors">Displaying Error Messages</a></h4>
<p>Error handling is an important part of any application, and curing an error
often involves getting the user's help. Struts provides a generalized method
@@ -540,6 +617,10 @@
different locales. See the tag's <code>altKey</code>, <code>srcKey</code>, and
<code>bundle</code> attributes in the <a
href="../../../../../../struts-html.html">HTML
Tags Reference</a>.</p>
+<p><a href="../../../../../../struts-html.html#messages">Messages</a> - By default,
+ the text for your messages will be returned by the default message resource,
+ which will select the appropriate language for the user. You may also specify
+ another message resource using the <code>bundle</code> attribute.</p>
<p>See the <a href="../../../../../../userGuide/building_view.html#i18n">Users
Guide</a> for more on how Struts helps you internationalize your applications.</p>
<p> </p>
