diff --git a/spring-webflow-reference/src/spring-js.xml b/spring-webflow-reference/src/spring-js.xml new file mode 100644 index 00000000..84932686 --- /dev/null +++ b/spring-webflow-reference/src/spring-js.xml @@ -0,0 +1,214 @@ + + + Spring JavaScript Quick Reference + + Introduction + + Spring Javascript is intended to be a lightweight wrapper around common JavaScript toolkits such as Dojo. It + aims to provide a common client-side programming model for progressively enhancing a web page with rich + widget behavior and Ajax remoting. + + + The Spring Javascript library has been used to apply rich functionality to the Spring MVC + Spring Web Flow + version of the Spring Travel application. + + + + Including Spring Javascript in a Page + + Spring Javascript is designed such that an implementation of its API can be built for any of the popular + Javascript toolkits. The first implementation provided is for the Dojo toolkit. (Implementations for jQuery, + Ext, Prototype and YUI will be considered in future releases.) Using Spring Javascript in a page requires + including both the underlying library as normal, the + Spring.js + base interface file and the + Spring-(library implementation).js + file for the corresponding toolkit, in this case + Spring-Dojo.js + . The following scripts includes are used to serve the files from the + ResourceServlet + + "> + +]]> + + + When using the widget system from an underlying library, typically you must also include some CSS resources + to obtain the desired look and feel. For the Dojo-based sample, Dojo's + tundra.css + is included: + + " />]]> + + + + Spring Javascript Decorations + + A central concept in Spring Javascript is the notion of applying decorations to existing DOM nodes. This + technique is used to progressively enhance a web page such that the page will still be functional in a less + capable browser. The + addDecoration + method is used to apply decorations. For example, to enhance a Spring MVC + <form:input> + tag with rich suggestion behavior: + + +]]> + + + The + ElementDecoration + is used to apply rich widget behavior to an existing DOM node. This decoration type does not aim to + completely hide the underlying toolkit, so the toolkit's native widget type and widget attributes are used + directly. This approach will allow you to use this common decoration model to apply any rich widget from the + underlying toolkit in a consistent manner. + + + When using the + ElementDecoration + to apply widgets that have rich validation behavior, a common need is to prevent the form from being + submitted to the server until validation passes. This can be done with the + ValidateAllDecoration + : + + +]]> + + + This decorates the "Proceed" button with a special onclick event handler that fires the client side + validators and does not allow the form to submit until they pass successfully. + + + An + AjaxEventDecoration + will apply a client-side event listener that fires a remote Ajax request to the server and installs a + callback for automatically handling the response: + + Previous Results +]]> + + + This decorates the onclick event of the "Previous Results" link with an Ajax call, passing along a special + parameter that specifies the fragment to be re-rendered in the response. Note that this link would still be + fully functional if Javascript was unavailable in the client. (See the section on + Handling Ajax Requests + for details on how this request is handled on the server.) + + + Sometimes it is necessary to calling Spring Javascript's + RemotingHandler + directly instead of using the + AjaxEventDecoration + . For example, see inline + onclick + handler of this button: + + +]]> + + + + Handling Ajax Requests + + Spring Javascript's client-side Ajax response handling is built upon the notion of receiving "fragments" + back from the server. These fragments are just standard HTML that is meant to replace portions of the + existing page. The key piece needed on the server is a way to determine which pieces of a full repsonse need + to be pulled out for partial rendering. + + + In order to be able to render partial fragments of a full response, the full response must be built using a + templating technology that allows the use of composition for constructing the response, and for the member + parts of the composition to be referenced and rendered individually. Spring Javascript initially provides + some simple Spring MVC extensions that make use of Tiles to achieve this, but the same effect could + theoretically be achieved with any templating system that meets the same criteria, and more such options + will be explored in future releases. + + + Spring Javascript's Ajax remoting functionality is built upon the notion that the core handling code for an + Ajax request should not differ from a standard browser request, thus no special knowledge of an Ajax request + is needed directly in the code and the same hanlder can be used for both styles of request. + + + Handling Ajax Requests with Spring MVC Controllers + + In order to handle Ajax requests with Spring MVC controllers, all that is needed is the configuration of + the provided Spring MVC extensions in your Spring application context for rendering the partial response + (note that these extensions require the use of Tiles for templating): + + + +]]> + + + This configures the + AjaxUrlBasedViewResolver + which in turn is able to interpret Ajax requests and create a + FlowAjaxTilesView + to handle rendering of the appropriate fragments. Note that + FlowAjaxTilesView + is capable of handling the rendering for both Web Flow and pure Spring MVC requests. The fragments + correspond to individual attributes of a Tiles view definition. For example, take the following Tiles + view definition: + + + + + + + +]]> + + + An Ajax request could specify the "body", "hotelSearchForm" or "bookingsTable" to be rendered as + fragments in the request. + + + + Handling Ajax Requests with Spring MVC + Spring Web Flow + + Spring Web Flow handles the optional rendering of fragments directly in the flow definition language + through use of the + render + element. The benefit of this approach is that the selection of fragments is completely decoupled from + client-side code, such that no special parameters need to be passed with the request the way they + currently must be with the pure Spring MVC controller approach. For example, if you wanted to render + the "hotelSearchForm" fragment from the previous example Tiles view into a rich Javascript popup: + + + + + + + + +]]> + + + + \ No newline at end of file diff --git a/spring-webflow-reference/src/spring-webflow-reference.xml b/spring-webflow-reference/src/spring-webflow-reference.xml index fbee6aad..4ae6f3fb 100644 --- a/spring-webflow-reference/src/spring-webflow-reference.xml +++ b/spring-webflow-reference/src/spring-webflow-reference.xml @@ -11,6 +11,7 @@ + @@ -83,6 +84,7 @@ &flow-inheritance; &system-setup; &spring-mvc; + &spring-js; &spring-faces; &portlet; &testing;