As promised, I put together a proposal for the view API of Velocity
in the Struts framework. I consulted:
- the ContextHelper.java by Ted
- the MessageTool.java by Nathan
- the existing Struts RequestUtil class
- the existing Struts JSP taglibs
to come up with a set of methods that should provide the necessary
Struts support from within Velocity templates. I have grouped functionality
by categories to give the whole method list some structure. I have really
focused on the Struts support. Other tools, like Nathan's LinkTool,
are useful additions to the tools project, but are independent of Struts.
This is going to be a difficult discussion if we don't structure it
a bit. Let's please define the following three phases:
Phase 1) What functionality should be covered by the view API. Is
the proposed method set adequate. What needs to be added, what is irrelevant.
How should method signatures be changed to make them Velocity-friendly.
This does *not* cover the method names and the grouping of methods
into tools. It's meaningless to talk about grouping before we are
clear what methods there are.
Phase 2) Group methods into tools. Define tool names and method names.
(The method names really depend on the tools that we define)
Phase 3) Hash out the implementation strategy. ContextHelper or not?
ControllerAPI? Was parts are implemented on the Struts side and what
on the Velocity side, etc.
I'll serve as the editor of this draft and provide you with updated versions
as the discussion progresses.
Anyone with some Struts experience should really come forward now and
comment on the proposal. I look forward to your feedback. Remember,
it's phase 1 now! :-)
Gabe
-------------------------------------------------------------------------------
VELOCITY VIEW API FOR STRUTS
============================
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 forwardURL(String target, String parameters)
Same as above but appends the string parameters are the end of the URL.
Example:
<a href='$tool.forwardURL("home", "frames=no&style=simple")'>Home</a>
produces something like
<a href="/myapp/templates/index.vm?frames=no&style=simple">
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">
Support for the switch between HTTP and HTTPS would be useful here too.
There has been some discussion on the list but currently Struts doesn't
support it as far I know, right Ted?
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.
Question to Ted: How should the new ActionMessage be considered? What's
its role and how are they different than ActionError
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 String[] errors()
Returns an array 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 String[] errors(String property)
Same as above but only the error messages for a particular
property are retrieved and returned.
public String errorMarkup()
Returns a formatted error text consisting of all queued
error messages. The markup is composed of an 'errors.header',
followed by all error messages, followed by an 'errors.footer'.
'errors.header' and 'errors.footer' are keys that reference
messages in the messages resources bundle. If no errors are
queued, an empty String is returned.
While some may consider it not nice that markup is produced
by this method, it is important to note that all markup is under
the control of the view designer.
Example:
$tool.errorMarkup
Does all that's needed to output a formatted error message.
public String errorMarkup(String property)
Same as above but only error messages for a specific property
are included.
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().
-------------------------------------------------------------------------------
--
Gabriel Sidler
Software Engineer, Eivycom GmbH, Zurich, Switzerland
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
