Spring/spring-webflow
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Revert "Remove Spring JavaScript library"

Browse Source 
This reverts commit 4d59b21e49.

Issue: SWF-1693
This commit is contained in:
Rossen Stoyanchev
2018-02-07 10:12:31 -05:00
parent 086e4ec728
commit 7215a49e4a
30 changed files with 2464 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

228
src/reference/spring-js.xml
View File

@@ -7,14 +7,228 @@
xsi:schemaLocation="
http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd">
<title>Handling Ajax Requests</title>
<title>Spring JavaScript Quick Reference</title>
<sect1 xml:id="spring-js-introduction">
<title>Introduction</title>
<para>
Spring Javascript (spring-js) is a lightweight abstraction over 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.
</para>
<para>
Use of the Spring JS API is demonstrated in the the Spring MVC + Web Flow version of the Spring Travel reference application.
</para>
</sect1>
<sect1 xml:id="spring-js-resource-servlet">
<title>Serving Javascript Resources</title>
<para>
Spring JS provides a generic <code>ResourceServlet</code> to serve web resources such as JavaScript and CSS files from jar files,
as well as the webapp root directory.
This servlet provides a convenient way to serve Spring.js files to your pages.
To deploy this servlet, declare the following in <code>web.xml</code>:
</para>
<programlisting language="xml"><![CDATA[
<!-- Serves static resource content from .jar files such as spring-js.jar -->
<servlet>
<servlet-name>Resource Servlet</servlet-name>
<servlet-class>org.springframework.js.resource.ResourceServlet</servlet-class>
</servlet>
<!-- Map all /resources requests to the Resource Servlet for handling -->
<servlet-mapping>
<servlet-name>Resource Servlet</servlet-name>
<url-pattern>/resources/*</url-pattern>
</servlet-mapping>]]>
</programlisting>
<para>
Note that starting with version 3.0.4, the Spring Framework includes
a replacement for the <code>ResourceServlet</code> (see the
<link xl:href="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/mvc.html#mvc-static-resources">Spring Framework documentation</link>).
With the new &lt;mvc:resources&gt; element resource requests (.js, .css) are handled by the
<code>DispatcherSevlet</code> without the need for a separate <code>ResourceServlet</code>.
Here is the relevant portion of the Spring MVC configuration in
the mvc-booking sample:
</para>
<programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:mvc="http://www.springframework.org/schema/mvc"
xsi:schemaLocation="http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-4.0.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.0.xsd">
<mvc:annotation-driven/>
<mvc:resources mapping="/resources/**" location="/, classpath:/META-INF/web-resources/" />
...
</beans>
]]>
</programlisting>
<para>
This incoming maps requests for <code>/resources</code> to resources found under
<code>/META-INF/web-resources</code> on the classpath. That's where Spring JavaScript resources
are bundled. However, you can modify the location attribute in the above configuration in order
to serve resources from any classpath or web application relative location.
</para>
<para>
Note that the full resource URL depends on how your DispatcherServlet is mapped.
In the mvc-booking sample we've chosen to map it with the default servlet mapping '/':
</para>
<programlisting language="xml"><![CDATA[
<servlet>
<servlet-name>Spring MVC Dispatcher Servlet</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>Spring MVC Dispatcher Servlet</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>
]]>
</programlisting>
<para>
That means the full URL to load <code>Spring.js</code> is <code>/myapp/resources/spring/Spring.js</code>.
If your <code>DispatcherServlet</code> was instead mapped to <code>/main/*</code> then the full
URL would be <code>/myapp/main/resources/spring/Spring.js</code>.
</para>
<para>
When using of the default servlet mapping it is also recommended to add this to your Spring MVC
configuration, which ensures that any resource requests not handled by your Spring MVC mappings
will be delegated back to the Servlet container.
</para>
<programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:mvc="http://www.springframework.org/schema/mvc"
xsi:schemaLocation="http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-4.0.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.0.xsd">
...
<mvc:default-servlet-handler />
</beans>
]]>
</programlisting>
</sect1>
<sect1 xml:id="spring-js-includes">
<title>Including Spring Javascript in a Page</title>
<para>
Spring JS is designed such that an implementation of its API can be built for any of the popular Javascript toolkits.
The initial implementation of Spring.js builds on the Dojo toolkit.
</para>
<para>
Using Spring Javascript in a page requires including the underlying toolkit as normal,
the <code>Spring.js</code> base interface file, and the <code>Spring-(library implementation).js</code> file for the underlying toolkit.
As an example, the following includes obtain the Dojo implementation of Spring.js using the <code>ResourceServlet</code>:
</para>
<programlisting language="xml"><![CDATA[
<script type="text/javascript" src="<c:url value="/resources/dojo/dojo.js" />"> </script>
<script type="text/javascript" src="<c:url value="/resources/spring/Spring.js" />"> </script>
<script type="text/javascript" src="<c:url value="/resources/spring/Spring-Dojo.js" />"> </script>]]>
</programlisting>
<para>
When using the widget system of an underlying library, typically you must also include some CSS resources to obtain the desired look and feel.
For the booking-mvc reference application, Dojo's <code>tundra.css</code> is included:
</para>
<programlisting language="xml"><![CDATA[
<link type="text/css" rel="stylesheet" href="<c:url value="/resources/dijit/themes/tundra/tundra.css" />" />]]>
</programlisting>
</sect1>
<sect1 xml:id="spring-js-decorations">
<title>Spring Javascript Decorations</title>
<para>
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 <code>addDecoration</code> method is used to apply decorations.
</para>
<para>
The following example illustrates enhancing a Spring MVC <code>&lt;form:input&gt;</code> tag with rich suggestion behavior:
</para>
<programlisting language="xml"><![CDATA[
<form:input id="searchString" path="searchString"/>
<script type="text/javascript">
Spring.addDecoration(new Spring.ElementDecoration({
elementId: "searchString",
widgetType: "dijit.form.ValidationTextBox",
widgetAttrs: { promptMessage : "Search hotels by name, address, city, or zip." }}));
</script>]]>
</programlisting>
<para>
The <code>ElementDecoration</code> 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 attributes are used directly.
This approach allows you to use a common decoration model to integrate any widget from the underlying toolkit in a consistent manner.
See the <code>booking-mvc</code> reference application for more examples of applying decorations to do things from suggestions to client-side validation.
</para>
<para>
When using the <code>ElementDecoration</code> 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 <code>ValidateAllDecoration</code>:
</para>
<programlisting language="xml"><![CDATA[
<input type="submit" id="proceed" name="_eventId_proceed" value="Proceed" />
<script type="text/javascript">
Spring.addDecoration(new Spring.ValidateAllDecoration({ elementId:'proceed', event:'onclick' }));
</script>]]>
</programlisting>
<para>
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.
</para>
<para>
An <code>AjaxEventDecoration</code> applies a client-side event listener that fires a remote Ajax request to the server. It also auto-registers a callback function to link in the response:
</para>
<programlisting language="xml"><![CDATA[
<a id="prevLink" href="search?searchString=${criteria.searchString}&page=${criteria.page - 1}">Previous</a>
<script type="text/javascript">
Spring.addDecoration(new Spring.AjaxEventDecoration({
elementId: "prevLink",
event: "onclick",
params: { fragments: "body" }
}));
</script>]]>
</programlisting>
<para>
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 <xref linkend="spring-js-ajax"/> for details on how this request is handled on the server.)
</para>
<para>
It is also possible to apply more than one decoration to an element.
The following example shows a button being decorated with Ajax and validate-all submit suppression:
</para>
<programlisting language="xml"><![CDATA[
<input type="submit" id="proceed" name="_eventId_proceed" value="Proceed" />
<script type="text/javascript">
Spring.addDecoration(new Spring.ValidateAllDecoration({elementId:'proceed', event:'onclick'}));
Spring.addDecoration(new Spring.AjaxEventDecoration({elementId:'proceed', event:'onclick',formId:'booking', params:{fragments:'messages'}}));
</script>]]>
</programlisting>
<para>
It is also possible to apply a decoration to multiple elements in a single statement using Dojo's query API.
The following example decorates a set of checkbox elements as Dojo Checkbox widgets:
</para>
<programlisting language="xml"><![CDATA[
<div id="amenities">
<form:checkbox path="amenities" value="OCEAN_VIEW" label="Ocean View" /></li>
<form:checkbox path="amenities" value="LATE_CHECKOUT" label="Late Checkout" /></li>
<form:checkbox path="amenities" value="MINIBAR" label="Minibar" /></li>
<script type="text/javascript">
dojo.query("#amenities input[type='checkbox']").forEach(function(element) {
Spring.addDecoration(new Spring.ElementDecoration({
elementId: element.id,
widgetType : "dijit.form.CheckBox",
widgetAttrs : { checked : element.checked }
}));
});
</script>
</div>]]>
</programlisting>
</sect1>
<sect1 xml:id="spring-js-ajax">
<title>Handling Ajax Requests</title>
<para>
TODO
</para>
<para>
Spring Web Flow's Ajax response handling is built upon the notion of receiving "fragments" back from the server.
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 response need to be pulled out for partial rendering.
</para>
@@ -22,11 +236,11 @@
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 Web Flow provides some simple Spring MVC extensions that make use of Tiles to achieve this.
Spring Javascript provides some simple Spring MVC extensions that make use of Tiles to achieve this.
The same technique could theoretically be used with any templating system supporting composition.
</para>
<para>
Spring Web Flow's Ajax remoting functionality is built upon the notion that the core handling code for an
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.
</para>

200
src/reference/whatsnew.xml
View File

@@ -101,4 +101,204 @@
</para>
</sect2>
</sect1>
<sect1 xml:id="whatsnew-swf-230">
<title>Spring Web Flow 2.3</title>
<sect2 xml:id="whatsnew-swf-embedded-flow">
<title>Embedding A Flow On A Page</title>
<para>
By default Web Flow does a client-side redirect upon entering every view state.
That makes it impossible to embed a flow on a page or within a modal dialog and execute more than one view state without causing a full-page refresh.
Web Flow now supports launching a flow in "embedded" mode.
In this mode a flow can transition to other view states without a client-side redirect during Ajax requests.
See <xref linkend="spring-mvc-embedded-flow"/> and <xref linkend="spring-faces-embedded-mode"/>.
</para>
</sect2>
<sect2 xml:id="whatsnew-jsr303">
<title>Support For JSR-303 Bean Validation</title>
<para>
Support for the JSR-303 Bean Validation API is now available building on equivalent support available in Spring MVC.
See <xref linkend="view-validate"/> for more details.
</para>
</sect2>
<sect2 xml:id="whatsnew-pc-propagation">
<title>Flow-Managed Persistence Context Propagation</title>
<para>
Starting with Web Flow 2.3 a flow managed <code>PersistenceContext</code> is automatically extended (propagated) to sub-flows assuming the subflow also has the feature enabled as well.
See <xref linkend="flow-managed-persistence-propagation"/>.
</para>
</sect2>
<sect2 xml:id="whatsnew-portlet-resource-requests">
<title>Portlet 2.0 Resource Requests</title>
<para>
Support for Portlet 2.0 resource requests has now been added enabling Ajax requests with partial rendering.
URLs for such requests can be prepared with the <code>&lt;portlet:resourceURL&gt;</code> tag in JSP pages.
Server-side processing is similar to a combined an action and a render requests but combined in a single request.
Unlike a render request, the response from a resource request includes content from the target portlet only.
</para>
</sect2>
<sect2 xml:id="whatsnew-conversation-manager">
<title>Custom ConversationManager</title>
<para>
The <code>&lt;flow-execution-repository&gt;</code> element now provides a conversation-manager attribute accepting a reference to a ConversationManager instance.
</para>
</sect2>
<sect2 xml:id="whatsnew-redirect-in-same-state">
<title>Redirect In Same State</title>
<para>
By default Web Flow does a client-side redirect when remaining in the same view state as long as the current request is not an Ajax request.
This is useful after form validation failure.
Hitting Refresh or Back won't result in browser warnings.
Hence this behavior is usually desirable.
However a new flow execution attribute makes it possible to disable it and that may also be necessary in some cases specific to JSF applications.
See <xref linkend="spring-faces-redirect-in-same-state"/>.
</para>
</sect2>
<sect2 xml:id="whatsnew-samples">
<title>Samples</title>
<para>
The process for building the samples included with the distribution has been simplified.
Maven can be used to build all samples in one step.
Eclipse settings include source code references to simplify debugging.
</para>
<para>
Additional samples can be accessed as follows:
<programlisting language="xml">mkdir spring-samples
cd spring-samples
svn co https://src.springframework.org/svn/spring-samples/webflow-primefaces-showcase
cd webflow-primefaces-showcase
mvn package
# import into Eclipse
</programlisting>
<programlisting language="xml">mkdir spring-samples
cd spring-samples
svn co https://src.springframework.org/svn/spring-samples/webflow-showcase
cd webflow-showcase
mvn package
# import into Eclipse
</programlisting>
</para>
</sect2>
</sect1>
<sect1 xml:id="whatsnew-swf-220">
<title>Spring Web Flow 2.2</title>
<sect2 xml:id="whatsnew-jsf2">
<title>JSF 2 Support</title>
<sect3>
<title>Comprehensive JSF 2 Support</title>
<para>
Building on 2.1, Spring Web Flow version 2.2 adds support for core JSF 2 features
The following features that were not supported in 2.1 are now available:
partial state saving, JSF 2 resource request, handling, and JSF 2 Ajax requests.
At this point support for JSF 2 is considered
comprehensive although not covering every JSF 2 feature --
excluded are mostly features that overlap with the core value Web Flow provides
such as those relating to navigation and state management.
</para>
<para>
See <xref linkend="spring-faces-webflow-config"/> for important configuration changes.
Note that partial state saving is only supported with Sun Mojarra 2.0.3 or later.
It is not yet supported with Apache MyFaces. This is due to the
fact MyFaces was not as easy to customize with regards to how component state is stored.
We will work with Apache MyFaces to provide this support. In the mean time you will need to use
the <code>javax.faces.PARTIAL_STATE_SAVING</code> context parameter in <code>web.xml</code>
to disable partial state saving with Apache MyFaces.
</para>
</sect3>
<sect3>
<title>Travel Sample With the PrimeFaces Components</title>
<para>
The main Spring Travel sample demonstrating Spring Web Flow and JSF support
is now built on JSF 2 and components from the PrimeFaces component library.
Please check out the booking-faces sample in the distribution.
</para>
<para>
Additional samples can be found at the Spring Web Flow - Prime Faces
<link xl:href="https://src.springframework.org/svn/spring-samples/webflow-primefaces-showcase">
Showcase</link>, an SVN repository within the
<link xl:href="https://src.springframework.org/svn/spring-samples">spring-samples</link>
repository. Use these commands to check out and build:
</para>
<programlisting><![CDATA[svn co https://src.springframework.org/svn/spring-samples/webflow-primefaces-showcase
cd webflow-primefaces-showcase
mvn package
]]></programlisting>
</sect3>
</sect2>
<sect2 xml:id="whatsnew-sec">
<title>Spring Security Facelets Tag Library</title>
<para>
A new Spring Security tag library is available for use with with JSF 2.0 or with JSF 1.2 Facelets views.
It provides an &lt;authorize&gt; tag as well as several EL functions.
See <xref linkend="spring-faces-security-taglib"/> for more details.
</para>
</sect2>
<sect2 xml:id="whatsnew-versions">
<title>Spring JavaScript Updates</title>
<sect3>
<title>Deprecated ResourcesServlet</title>
<para>
Starting with Spring 3.0.4, the Spring Framework includes
a replacement for the ResourcesServlet. Please see
the Spring Framework documentation for details on the custom mvc namespace,
specifically the new
<link xl:href="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/mvc.html#mvc-static-resources">"resources"</link>
element.
</para>
</sect3>
<sect3>
<title>Dojo 1.5 and dojox</title>
<para>
The bundled custom Dojo build is upgraded to version 1.5. It now includes dojox.
</para>
<para>
Note that applications are generally encouraged to prepare their own custom
Dojo build for optimized performance depending on what parts of Dojo are
commonly used together. For examples see the
<link xl:href="https://src.springframework.org/svn/spring-webflow/branches/spring-webflow-2.2-maintenance/spring-js-resources/scripts/dojo">scripts</link>
used by Spring Web Flow to prepare its own custom Dojo build.
</para>
</sect3>
<sect3>
<title>Two Spring JS artifacts</title>
<para>
The <code>spring-js</code> artifact has been split in two -- the new artifact
(<code>spring-js-resources</code>) contains client side resource (.js, .css, etc.) while
the existing artifact (<code>spring-js</code>) contains server-side Java code only.
</para>
<para>
Applications preparing their own custom Dojo build have an option now to
avoid including <code>spring-js-resources</code> and put <code>Spring.js</code> and
<code>Spring-Dojo.js</code> directly under the root of their web application.
</para>
</sect3>
<sect3>
<title>Client resources moved into META-INF/web-resources</title>
<para>
Bundled client resources (.js, .css, etc.)
have been moved to <code>META-INF/web-resources</code> from their previous location
under <code>META-INF</code>. This change is transparent for applications but will result
in simpler and safer configuration when using the new resource handling
mechanism available in Spring 3.0.4.
</para>
</sect3>
</sect2>
<sect2 xml:id="whatsnew-jsf-portlet">
<title>JSF Portlet Support</title>
<sect3>
<title>Portlet API 2.0 and JSF 1.2 support</title>
<para>
In previous versions of Spring Web Flow support for JSF Portlets relied on
a Portlet Bridge for JSF implementation and was considered experimental.
Spring Web Flow 2.2 adds support for JSF Portlets based on its own internal
Portlet integration targeting Portlet API 2.0 and JSF 1.2 environments.
See <xref linkend="portlet-jsf"/> for more details.
The Spring Web Flow Travel JSF Portlets sample has been successfully
tested on the Apache Pluto portal container.
</para>
</sect3>
</sect2>
</sect1>
</chapter>