Hi,
I have put all the discussed changes into a new draft. Thanks for all
the feedback. I think we now have a much better API. You find a list
of changes just below. I would like to ask Ted to carefully look at what I
propose on the action messages.
>From my point of view, this now concludes phase 1 (your feedback is still
welcome, of course). I am now going to work out a proposal for phase 2
(how to divide the functionality into tools, naming of methods).
Gabe
Changes:
- Added method getToken() to retrieve the transaction control token for the
current session.
- Added method getCancelMagicName() to retrieve the string to be used for
the name attribute of form cancel buttons if validation is enabled. (Input Ted)
- Remove methods errorMarkup(). The recommened way is to use a VelociMarcro.
- Changed the signatures of methods errors(...). They now return a HashMap.
- Removed all query parameter from the method forwardURL(). The recommended
way is to use a context tools like Nathan's proposed LinkTool to achieve this.
See notes and example at the end of that section. Since the LinkTool makes
sense with and without Struts, I don't want to add all its functionality
to the Struts tool(s) but rather keep it as a separate tool.
- Added set of methods to work with action messages (a new feature in the
upcoming Struts 1.1). See notes in the section. Still need some clarifications
from Ted.
-------------------------------------------------------------------------------
VELOCITY VIEW API FOR STRUTS
============================
Version 0.2, 18-Feb-2002
Category: Handling of URLs
--------------------------
Struts supports a configurable level of indirection between the URLs of a
request and the handler of that request. For example, a URL of /main.do
may be mapped by configuration to a handler of class com.app.my.handler.
Futhermore, Struts knows the concept of 'forwards'. A 'forward' is a name
for a request target, such as a request handler or simply a web page.
This configurable mapping of logical targets to actual targets allows
one to avoid hard-coded URLs in templates. All the logical links between
the different views of an application can be maintained in a configuration
file. The following three methods are used to maps logical names to actual
URLs. The remaining methods are related.
public String actionURL(String action)
Converts the action name into a server-relative URL.
Example:
<form name="login" action='$tool.actionURL("login")'>
produces something like
<form name="login" action="/myapp/actions/loginaction">
public String forwardURL(String forward)
Converts the local or global forward into a server-relative URL.
Example:
<a href='$tool.forwardURL("home")'>Home</a>
produces something like
<a href="/myapp/templates/index.vm">
public String absoluteURL(String path)
Create and return an absolute URL for the specified context-relative
path.
public String baseRef()
Renders the reference for a HTML <base> element.
Example:
<base href="$tool.baseRef()">
produces something like
<base href="/myapp/template/view.vm">
Note:
If you need to append query data to the URLs created with above methods,
it is recommended to use a context tool like Nathan's proposed LinkTool.
Using LinkTool, adding query parameters would works the following way:
#set( $foolink = $link.setPath($struts.forward("login")) )
<a href="$foolink.addQueryData("action", "checkAuth")">Login</a>
Category: Messages
------------------
Struts supports internationalized messages. The messages are stored
in NVP files by language. The following methods operate on these message
files.
public String message(String key)
Return the localized message for the specified key.
Example:
<input type="submit" name="newbutton" value='$tool.message("view35.new")'/>
renders something like
<input type="submit" name="newbutton" value='Neuer Patient anmelden'/>
public String message(String key, Object args[])
Same as above, but supports parametric message strings, for example:
warning.quota=Your mail folder is {0} MB above the limit of {1} MB.
Up to five replacement parameters are supported.
public boolean isMessage(String key)
Return true if a message string for the specified message key
is present for the user's Locale.
Category: Error Handling
------------------------
Errors may stem from the validation of a submitted form or from the
processing of the request. If there are errors, they are made available
to the view to output. A few aspects about errors are:
- Error messages are looked up in a bundle of messages resource files. Support
for internationalized messages is provided.
- Error messages can have up to four replacement parameters.
- Errors have a property that marks them as 'global errors' (meaning that they
apply to the entire form) or 'specific errors' (meaning that they are specific
to one of the form elements). This allows to position error messages precisely
where the error occured on the form.
public boolean hasErrors()
Returns true if there are errors queued, otherwise false.
public int errorSize()
Returns the number of error messages.
public int errorSize(String property)
Returns the number of error messages for a particular property.
public HashMap errors()
Returns a HashMap of localized error messages. A typical application
would use a script similar to the following to output the error messages.
Example:
<ul>
#foreach ($e in $tool.errors )
<li>$e</li>
#end
</ul>
public HashMap errors(String property)
Same as above but only the error messages for a particular
property are retrieved and returned.
Note:
To output a fully formatted error message similar to what the JSP tag
html:errors does, it is recommended to utilise a VelociMacro. The
following example produces the same output that the html:errors JSP
tag does:
#macro ( errorMarkup )
#if ($tool.hasErrors() )
<ul>
#foreach ($e in $tool.errors() )
<li>$e.key()</li>
#end
</ul>
#end
#end
Category: Action Messages
-------------------------
Action messages generalize the concept of error messages to include
all kinds of messages that an action might want to pass to the view.
So, every error message is an action message, but not every action
message is an error message. The set of methods are the same as for
handling error messages. Note: Action messages are not to be confused
with the internationalized message strings. We need to find a good naming
scheme to make sure that people don't confuse it.
Otherwise, same comments apply as to Error Messages above.
public boolean hasMessages();
Returns true if there are messages (stored under MESSAGE_KEY) OR
errors (stored under ERROR_KEY) queued, otherwise false.
public int messageSize();
Returns the total number of messages and errors (stored under MESSAGE_KEY
and ERROR_KEY).
public int messageSize(String property);
Returns the total number of messages and errors (stored under MESSAGE_KEY
and ERROR_KEY) for the specified property.
public HashMap messages();
Returns a HashMap of localized messages and error messages (stored under
MESSAGE_KEY and ERROR_KEY).
public HashMap messages(String property);
Same as above but only messages and error for a particular property
are returned.
Category: ActionForm
--------------------
Struts has support to parse incoming HTTP requests and stick the available
request parameter into a bean. The Struts config file defines what bean
class to use for a particular request. Additionally, a hook allows the
application developer to include form validation code. The form bean is
passed around as an attribute to the servlet request.
public ActionForm getActionForm()
Retrieve and return the ActionForm bean associated with this mapping.
The ActionForm is typically needed by the view designer to populate
HTML form elements with values.
Category: Miscellaneous
-----------------------
public Locale getLocale()
Retrieve and return the Locale for the user. If a Locale is
not found, the default locale is returned. Note: Struts' Locale
is not request.getLocale().
public String getToken()
Retrieve and return the transaction control token for this session.
public String getCancelMagicName()
Retrieve and return the magic name that is to be used for cancel buttons
in HTML forms. If this magic name is used for cancel buttons, the
automatic form validation is skipped. If automatic form validation is
not used, this is irrelevant.
-------------------------------------------------------------------------------
--
Gabriel Sidler
Software Engineer, Eivycom GmbH, Zurich, Switzerland
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
