Hi, this is version 0.3 of the Velocity View API for Struts.
Changes are limited to the first section "Handling of URLs".
I consider this now pretty close to final. This should not stop
you from commenting if you see something.
Changes in 0.3:
- Reworked the handling of URL to iron out some "extremly annoying"
behavoir :-). It works now along the lines of what Nathan proposed for
the LinkTool.
Gabe
-------------------------------------------------------------------------------
VELOCITY VIEW API FOR STRUTS
============================
Version 0.3, 20-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 LinkTool setPath(String path)
Returns a copy of this link with the given path setting.
No conversions are applied to path.
Note: It is Struts recommended practice to forward to
actions or forwards, but not directly to templates as this
bypassed the Struts controller. Consider using setAction()
or setForward() instead.
public LinkTool setAction(String action)
Returns a copy of this link with the given action name
converted into a server-relative path (as per configuration
in struts-config.xml).
Example:
<form name="login" action='$link.setAction("login")'>
produces something like
<form name="login" action="/myapp/actions/loginaction">
public LinkTool setForward(String forward)
Returns a copy of this link with the given forward name
converted into a server-relative path (as per configuration
in struts-config.xml).
Example:
<a href='$link.setForward("home")'>Home</a>
produces something like
<a href="/myapp/templates/index.vm">Home</a>
public LinkTool setAbsolute(String path)
Returns a copy of this link with the specified
context-relative path converted to an absolute
path.
public LinkTool addQueryData(String key, Object value)
Adds key/value pair to the query data
This returns a new LinkTool containing both
a copy of this LinkTool's query data and the new data
This makes repeated use in velocity templates much easier.
Query data is URL encoded before it is appended.
public String getPath()
Returns the current path set for this link as set by
the methods setPath(), setAction(), setForward() or
setAbsolute(). Any conversions have been applied.
public String getQueryData()
Returns this link's query data as an url-encoded string
e.g. "key=value&foo=this+is+encoded".
public String getServerPath()
Returns the server & context url
e.g. "http://myserver.net/myapp";.
public String getBaseRef()
Returns a full reference to the template without
any query data.
e.g. "http://myserver.net/myapp/stuff/View.vm";
NOTE! This returns that base ref of the last request.
This will NOT represent any path or query data
set for this LinkTool! A typical application of
this is with the HTML base tag.
e.g. <base href="$tool.baseRef">
public String toString()
Returns the full URI that's been built with this tool
e.g. "http://myserver.net/myapp/stuff/View.vm?id=42&type=blue";
Typically it is not necessary to call this method explicitely.
Velocity will call the toString() method automatically to
obtain a representable version of this object.
-- Nothing changed after here --
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.
-------------------------------------------------------------------------------
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
