This look quite good Gabriel. I also made a pass on the original ContextHelper object, and reduced it to an interface, which essentially dovetails with this API. There are some minor differences, which I will need to give some additonal thought.
http://husted.com/struts/resources/ConfigHelperInterface.java The name change corresponds to the new support for multiple Struts configurations. The goal would be to provide an object that worked with both 1.0 or 1.1, and supported multiple configurations when they are being used. My original object compiled fine, but I need to test it, and then add the new configuration support. Currently, the default type for other Struts controller elements, ActionMapping, ActionForward, et cetera, can be specified in the ActionServlet configuration. I'm thinking that we could do the same with the ConfigHelper. There would be a default base object type, but another could be specified. For example, a Velocity ConfigHelper might provide signatures that didn't bother with the get* convention, and provide additional helper methods. For 1.0 compatibility, a Velocity Servlet could instantiate this object itself. In 1.1, the Struts controller could instantiate it instead; the Velocity Servlet could then expose the ConfigHelper through the Velocity context, and do the template merging thing. The ActionMessages are basically an enhanced version of ActionErrors. It acts like an iterator, rather than just spitting everything out. We kept the ActionErrors mostly for backward compatability. It also lets developers send confirmations through one queue, and "errors" through another. But I generally just use one or the other myself. The ActionMessages should not be confused with the Message Resource. ActionMessages live in the request scope, and are meant to be passed along to the page. The other messages live in application scope, and are used directly by the page to print localized labels and what not. Both the ErrorMessages and ActionMessages refer to the Message Resource to generate localized messages. Switching back and forth between HTTP and HTTPS has always been tricky. There's a new contribution available, but it relies on Servlet 2.3. -- Ted Husted, Husted dot Com, Fairport NY USA. -- Java Web Development with Struts. -- Tel +1 585 737-3463. -- Web http://www.husted.com/struts/ Gabriel Sidler wrote: > > 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]> -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
