Author: rahul
Date: Wed Dec 27 14:32:26 2006
New Revision: 490579
URL: http://svn.apache.org/viewvc?view=rev&rev=490579
Log:
Catching up on documentation (alas). Added bits for shale-dialog-scxml custom
actions (redirect, view), application developer defined custom actions, DTD for
dialog-config and authoring best practices. Also fixed a botched conditional in
code. Includes docs for:
SHALE-61 SHALE-337 SHALE-347 SHALE-348 SHALE-366
The shale-dialog-scxml docs have become too bulky for one page, need to
refactor into a "true" site (post v1.0.4)
Modified:
shale/framework/trunk/shale-dialog-scxml/src/main/java/org/apache/shale/dialog/scxml/SCXMLDialogContext.java
shale/framework/trunk/shale-dialog-scxml/src/site/xdoc/index.xml
Modified:
shale/framework/trunk/shale-dialog-scxml/src/main/java/org/apache/shale/dialog/scxml/SCXMLDialogContext.java
URL:
http://svn.apache.org/viewvc/shale/framework/trunk/shale-dialog-scxml/src/main/java/org/apache/shale/dialog/scxml/SCXMLDialogContext.java?view=diff&rev=490579&r1=490578&r2=490579
==============================================================================
---
shale/framework/trunk/shale-dialog-scxml/src/main/java/org/apache/shale/dialog/scxml/SCXMLDialogContext.java
(original)
+++
shale/framework/trunk/shale-dialog-scxml/src/main/java/org/apache/shale/dialog/scxml/SCXMLDialogContext.java
Wed Dec 27 14:32:26 2006
@@ -248,7 +248,7 @@
}
// account for user agent navigation
- if (viewStateId != stateId) {
+ if (!viewStateId.equals(stateId)) {
if (log().isTraceEnabled()) {
log().trace("Dialog instance '" + getId() + "' of dialog name
'"
Modified: shale/framework/trunk/shale-dialog-scxml/src/site/xdoc/index.xml
URL:
http://svn.apache.org/viewvc/shale/framework/trunk/shale-dialog-scxml/src/site/xdoc/index.xml?view=diff&rev=490579&r1=490578&r2=490579
==============================================================================
--- shale/framework/trunk/shale-dialog-scxml/src/site/xdoc/index.xml (original)
+++ shale/framework/trunk/shale-dialog-scxml/src/site/xdoc/index.xml Wed Dec 27
14:32:26 2006
@@ -125,7 +125,12 @@
The default mapping is an identity transform i.e. the state
identifier is reused as the view identifier. See the
<a
href="apidocs/org/apache/shale/dialog/scxml/DialogStateMapper.html">DialogStateMapper
- Javadocs</a> for details.
+ Javadocs</a> for details. This mapping may be overridden by using
+ the <shale:view> custom Commons SCXML action. See the
+ <a href="#dialog-scxml-actions">Shale dialogs custom Commons SCXML
actions section</a>
+ for details. Also note the associated
+ <a href="#dialog-scxml-practices">best practices</a>
+ when authoring view <state>s.
<source>
<!-- A "view" state, the default convention maps this state to
to the JSF view identifier "/logon" -->
@@ -206,8 +211,13 @@
that comprise your dialog, using standard JavaServer Faces and
(optional) Shale <code>ViewController</code> facilities.</li>
<li>Declare your dialogs via an XML document, conventionally named
- <code>/WEB-INF/dialog-config.xml</code>:
+ <code>/WEB-INF/dialog-config.xml</code>, that conforms to the
+ required DTD:
<source>
+<!DOCTYPE dialogs PUBLIC
+ "-//Apache Software Foundation//DTD Shale SCXML Dialog Configuration 1.0//EN"
+ "http://shale.apache.org/dtds/dialog-scxml-config_1_0.dtd">
+
<dialogs>
<dialog name="FirstDialogName"
@@ -250,6 +260,132 @@
defined by the <a
href="../shale-dialog/index.html#dialog-using">
Shale Dialog Manager</a>.</li>
</ul>
+
+ </subsection>
+
+ <a name="dialog-scxml-actions"/>
+ <subsection name="Custom Commons SCXML actions">
+
+ <p>The Shale dialogs Commons SCXML implementation provides a couple
+ of custom Commons SCXML actions out of the box (
+ <a
href="http://jakarta.apache.org/commons/scxml/guide/custom-actions.html";>
+ background reading on custom actions</a>). The first one
+ allows the use of redirects while navigating to a view,
+ and the second allows overriding the
+ <a
href="apidocs/org/apache/shale/dialog/scxml/DialogStateMapper.html">DialogStateMapper</a>
+ mapping between a "view" state and the associated JSF
+ view identifier.</p>
+
+ <ul>
+
+ <li><b><shale:redirect></b> - Typically used in the
+ <onentry> section of the "view" <state> that should be
+ visited by issuing a redirect.
+<source>
+<onentry>
+ <shale:redirect/>
+</onentry>
+</source></li>
+
+ <li><b><shale:view></b> - Typically used in the
+ <onentry> section of the "view" <state>, such that the
+ "viewId" attribute contains the JSF view identifier that
+ should be rendered when in this dialog state.
+<source>
+<onentry>
+ <shale:view viewId="/faces/wizardpage3" />
+</onentry>
+</source></li>
+
+ </ul>
+
+ <p>The <i>shale</i> prefix used above is arbitrary. The
+ association is made using the namespace URI associated with
+ the prefix (the above custom actions belong to the
+ <i>http://shale.apache.org/dialog-scxml</i> URI), so the SCXML
+ document describing the above dialog would need to establish
+ that prefix to namespace URI association, for example:
+<source>
+<scxml xmlns="http://www.w3.org/2005/07/scxml"; version="1.0"
+ xmlns:shale="http://shale.apache.org/dialog-scxml";
+ initialstate="...">
+</source>
+ </p>
+
+ <p>It is possible for application developers to define additional
+ custom actions per dialog definition. For example, a developer may
+ define a custom Commons SCXML action via a class
+ <i>my.actions.Foo</i> (which must extend
+ <i>org.apache.commons.scxml.model.Action</i>, see background
+ reading link above) and make it available in the namespace URI
+ <i>http://foo.bar/actions</i> to the dialog named "wizard"
+ by defining it in the <i>dialog-config.xml</i> like so:
+<source>
+<dialog name="wizard" scxmlconfig="wizard.xml"
+ dataclassname="wizard.Data">
+
+ <scxmlaction name="foo" uri="http://foo.bar/actions";
+ actionclassname="my.actions.Foo" />
+
+</dialog>
+</source>
+
+ and further using it in the <i>wizard.xml</i> SCXML document like so:
+
+<source>
+<scxml xmlns="http://www.w3.org/2005/07/scxml"; version="1.0"
+ xmlns:shale="http://shale.apache.org/dialog-scxml";
+ xmlns:my="http://foo.bar/actions";
+ initialstate="...">
+
+ ...
+
+ <state id="state1">
+ <onentry>
+ <my:foo .../>
+ </onentry>
+
+ ...
+
+ </state>
+
+</source>
+ </p>
+
+ </subsection>
+
+
+ <a name="dialog-scxml-practices"/>
+ <subsection name="Best practices">
+
+ <p>The particular usecase of SCXML within Shale dialogs implies
+ certain restrictions on the SCXML document used to describe
+ the dialog. In particular, best practices for SCXML documents
+ used to describe Shale dialogs include:
+
+ <ul>
+
+ <li>A "view" <state> must be a simple leaf state (should not
+ contain other <state> elements and should not have a
+ <parallel> ancestor).</li>
+
+ <li>A "view" <state> must not rely on <onexit> or
+ <onentry> executable content. Such executable content can
+ be moved to a preceeding or following "action" state. This
+ is due to the possibility of browser navigation buttons
+ (back/forward) being used during the dialog execution. The
+ exception to this is the two custom actions described in the
+ previous section, when used as mentioned above.</li>
+
+ <li>All views that participate in a dialog should
+ provide for checks to guard against double
+ submits (see <token> tag in shale-core) and provide
+ "immediate" actions such as a cancel button to exit out of
+ the dialog.</li>
+
+ </ul>
+
+ </p>
</subsection>
