polish

spring-webflow-reference/src/spring-mvc.xml

@@ -271,20 +271,38 @@ public class BookingFlowHandler extends AbstractFlowHandler {
 		</para>
 		<sect2 id="webflow-event-named-html-button">
 			<title>Using a named HTML button to signal an event</title>
+			<para>
+				The example below shows two buttons on the same form that signal <code>proceed</code> and <code>cancel</code> events when clicked, respectively.
+			</para>
 			<programlisting language="xml"><![CDATA[
 <input type="submit" name="_eventId_proceed" value="Proceed" />
 <input type="submit" name="_eventId_cancel" value="Cancel" />]]>		
 			</programlisting>
+			<para>
+				When a button is pressed Web Flow finds a request parameter name beginning with <code>_eventId_</code> and treats the remaining substring as the event id.
+				So in this example, submitting <code>_eventId_proceed</code> becomes <code>proceed</code>.
+				This style should be considered when there are several different events that can be signaled from the same form.
+			</para>
 		</sect2>
 		<sect2 id="webflow-event-hidden-parameter">
 			<title>Using a hidden HTML form parameter to signal an event</title>
+			<para>
+				The example below shows a form that signals the <code>proceed</code> event when submitted:
+			</para>
 			<programlisting language="xml"><![CDATA[
 <input type="submit" value="Proceed" />
 <input type="hidden" name="_eventId" value="proceed" />]]>	
 			</programlisting>
+			<para>
+				Here, Web Flow simply detects the special <code>_eventId</code> parameter and uses its value as the event id.
+				This style should only be considered when there is one event that can be signaled on the form.
+			</para>
 		</sect2>
 		<sect2 id="webflow-event-link">
 			<title>Using a HTML link to signal an event</title>
+			<para>
+				The example below shows a link that signals the <code>cancel</code> event when activated: 
+			</para>
 			<programlisting language="xml"><![CDATA[
 <a href="${flowExecutionUrl}&_eventId=cancel">Cancel</a>]]>		
 			</programlisting>
@@ -293,7 +311,7 @@ public class BookingFlowHandler extends AbstractFlowHandler {
 			Firing an event results in a HTTP request being sent back to the server.
 			On the server-side, the flow handles decoding the event from within its current view-state.
 			How this decoding process works is specific to the view implementation.
-			A Spring MVC view implementation simply looks for a request parameter named <code>_eventId</code>.
+			Recall a Spring MVC view implementation simply looks for a request parameter named <code>_eventId</code>.
 			If no <code>_eventId</code> parameter is found, the view will look for a parameter that
 			starts with <code>_eventId_</code> and will use the remaining substring as the event id.
 			If neither cases exist, no flow event is triggered.

spring-webflow-samples/booking-mvc/src/main/webapp/WEB-INF/hotels/booking/booking-flow.xml

@@ -35,7 +35,7 @@
 		<transition on="cancel" to="cancel" />
 	</view-state>
 	
-	<end-state id="bookingConfirmed" commit="true" view="externalRedirect:servletRelative:/hotels/index"/>
+	<end-state id="bookingConfirmed" commit="true" view="externalRedirect:servletRelative:/hotels/index" />
 
 	<end-state id="cancel" />
 			

spring-webflow/src/main/java/org/springframework/webflow/context/ExternalContext.java

@@ -69,8 +69,8 @@ public interface ExternalContext {
 	public SharedAttributeMap getSessionMap();
 
 	/**
-	 * Provides access to the <i>global</i> external session map, providing a storage for data globally accross the
-	 * user session and accessible to both internal and external SWF artifacts.
+	 * Provides access to the <i>global</i> external session map, providing a storage for data globally accross the user
+	 * session and accessible to both internal and external SWF artifacts.
 	 * <p>
 	 * Note: most external context implementations do not distinguish between the concept of a "local" user session
 	 * scope and a "global" session scope. The Portlet world does, but not the Servlet for example. In those cases
@@ -93,8 +93,8 @@ public interface ExternalContext {
 	public boolean isAjaxRequest();
 
 	/**
-	 * Get a context-relative flow execution URL for the execution with the provided key. Typically used by response
-	 * writers that write out references to the flow execution to support postback on a subsequent request.
+	 * Get a flow execution URL for the execution with the provided key. Typically used by response writers that write
+	 * out references to the flow execution to support postback on a subsequent request.
 	 * @param flowId the flow definition id
 	 * @param flowExecutionKey the flow execution key
 	 * @return the flow execution URL

spring-webflow/src/main/java/org/springframework/webflow/execution/RequestContext.java

@@ -32,8 +32,8 @@ import org.springframework.webflow.definition.TransitionDefinition;
  * <p>
  * A new instance of this object is typically created when one of the core operations supported by a flow execution is
  * invoked, either <code>start</code> to launch the flow execution, <code>signalEvent</code> to resume the flow
- * execution, or <code>refresh</code> to reconstitute the flow execution's last view selection for purposes of
- * reissuing a user response.
+ * execution, or <code>refresh</code> to reconstitute the flow execution's last view selection for purposes of reissuing
+ * a user response.
  * <p>
  * Once created this context object is passed around throughout flow execution request processing where it may be
  * accessed and reasoned upon by SWF-internal artifacts such as states, user-implemented action code, and state
@@ -190,8 +190,8 @@ public interface RequestContext {
 	public MutableAttributeMap getAttributes();
 
 	/**
-	 * Returns the context-relative URL of this flow execution. Needed by response writers that write out the URL of
-	 * this flow execution to allow calling back this execution in a subsequent request.
+	 * Returns the URL of this flow execution. Needed by response writers that write out the URL of this flow execution
+	 * to allow calling back this execution in a subsequent request.
 	 * @throws IllegalStateException if the flow execution has not yet had its key assigned
 	 * @return the flow execution URL
 	 */