Author: craigmcc
Date: Wed Oct 18 20:02:45 2006
New Revision: 465455
URL: http://svn.apache.org/viewvc?view=rev&rev=465455
Log:
Finish up the documentation for the overall Dialog Manager functionality.
SHALE-300
Modified:
shale/framework/trunk/shale-dialog/src/site/xdoc/index.xml
Modified: shale/framework/trunk/shale-dialog/src/site/xdoc/index.xml
URL:
http://svn.apache.org/viewvc/shale/framework/trunk/shale-dialog/src/site/xdoc/index.xml?view=diff&rev=465455&r1=465454&r2=465455
==============================================================================
--- shale/framework/trunk/shale-dialog/src/site/xdoc/index.xml (original)
+++ shale/framework/trunk/shale-dialog/src/site/xdoc/index.xml Wed Oct 18
20:02:45 2006
@@ -195,16 +195,167 @@
<code>DialogContextManager</code> instance for this user.</li>
</ul>
- <p>FIXME - document the events stuff.</p>
+ <p><a href="apidocs/org/apache/shale/dialog/DialogListener.html">
+ DialogListener</a> is an event listener interface that follows
+ standard JavaBean design patterns. Interested objects can register
+ themselves as a listener on a <code>DialogContext</code> instance,
+ and be notified of the occurrence of the following events:</p>
+ <ul>
+ <li>This <code>DialogContext</code> instance was started.</li>
+ <li>This <code>DialogContext</code> instance was stopped.</li>
+ <li>An exception was thrown by this <code>DialogContext</code>
+ instance.</li>
+ <li>A named "state" was entered (details are specific to the
+ selected implementation).</li>
+ <li>A named "state" was exited (details are specific to the
+ selected implementation).</li>
+ <li>A transition from one named "state" to another was performed
+ (details are specific to the selected implemenation).</li>
+ </ul>
+
+ <p>Applications that wish to implement listeners are encouraged to
+ subclass <a
href="apidocs/org/apache/shale/dialog/base/AbstractDialogListener.html">
+ AbstractDialogListener</a> instead of implementing the interface
+ described above. In addition to only needing to implement event
+ handling methods you are interested in, this protects the ability
+ to compile your application against future versions of the listener
+ interface, if more event handling methods are added in the future.</p>
</subsection>
<a name="dialog-using"/>
<subsection name="Using Dialog Manager">
- <p>FIXME - document idioms for using Dialog Manager.</p>
+ <p>The following paragraphs describe functionality that works no matter
+ which specific Dialog Manager implementation you have selected. Be
+ sure to consult the page for your selected implementation for
additional
+ features and capabilities.</p>
- </subsection>
+ <h4>Starting A New DialogContext Instance</h4>
+
+ <p>At most one <code>DialogContext</code> instance can be active, in a
+ particular window or frame, at one time. There are several ways in
which
+ an application can cause such a <code>DialogContext</code> instance can
+ be activated and associated with the current window or frame. Each
+ technique is described below.</p>
+
+ <h5>Starting A DialogContext Via Navigation</h5>
+
+ <p>This technique is very useful if your application contains a mixture
+ of pages managed by standard JavaServer Faces navigation, and pages
+ managed by the Shale Dialog Manager. To enter a dialog whose logical
+ name is <strong>foo</strong>, simply have one of your application
actions
+ return a logical outcome string of <code>dialog:foo</code>, and a new
+ <code>DialogContext</code> instance will be started for you.</p>
+
+ <h5>Starting A DialogContext Programmatically</h5>
+
+ <p>Under some circumstances, it may be preferable for your
application's
+ event handler to decide programmatically which dialog to use, and start
+ it programmatically. To start a dialog named <strong>foo</strong>
+ programmatically, code something like this in your action method:</p>
+
+<source>
+ FacesContext context = FacesContext.getCurrentInstance();
+ DialogContextManager manager = (DialogContextManager)
+ context.getApplication().getVariableResolver().
+ resolveVariable(context, Constants.MANAGER_BEAN);
+ DialogContext dcontext = manager.create(context, "foo");
+ dcontext.start(context);
+ return null;
+</source>
+
+ <h5>Starting A DialogContext Via URL Parameters</h5>
+
+ <p>In a use case like a pop-up window, the first request served by the
+ application will be to a new window that is not currently associated
+ with a current dialog. In order for such a window to immediately
+ become associated with a <code>DialogContext</code> instance, the
+ Dialog Manager also recognizes the following request parameters, if
+ they are present, and if there is no active DialogContext already:</p>
+
+ <ul>
+ <li><strong>org.apache.shale.dialog.DIALOG_NAME</strong> - The
+ logical name of the dialog to be created and started.</li>
+ <li><strong>org.apache.shale.dialog.PARENT_ID</strong> -
+ (Optional) the logical dialog identifier of a parent
+ <code>DialogContext</code> instance that should become the
+ parent of the newly created one. This allows, for example,
+ a popup window to be associated with the <code>data</code>
+ element for the <code>DialogContext</code> instance associated
+ with the parent window.</li>
+ </ul>
+
+ <h4>Request Processing for an Active DialogContext Instance</h4>
+
+ <p>Once a <code>DialogContext</code> instance has been associated with
+ the current window, the Dialog Manager performs the following tasks
+ automatically, with no need for application interaction:</p>
+
+ <ul>
+ <li>Cause a <em>dialog identifier</em> for this
<code>DialogContext</code>
+ instance to be saved and restored as part of the JSF compoennt
+ tree and associated state.</li>
+ <li>When a POST request for this window is processed, the active
+ <code>DialogContext</code> instance for the logical dialog
+ identifier for this window will be retrieved from the
+ <code>DialogContextFactory</code> for this user, and stored
+ as a request scope attribute under key <code>dialog</code>
+ for easy reference in expressions.</li>
+ <li>During <em>Invoke Application</em> phase of the request
+ processing lifecycle, the logical outcome returned by the
+ action method will be intercepted by the Dialog Manager,
+ rather than being fed into the standard JSF navigation handler.
+ Instead, the outcome will be passed in as a parameter to the
+ <code>advance()</code> method on the current
<code>DialogContext</code>
+ instance, which will advance the state of the computation until
+ a further interaction with the user is required. Then, the
+ Dialog Manager will create the requested JSF view, and forward
+ to Render Response phase so that this view may be
rendered.</li>
+ </ul>
+
+ <h4>Accessing Per-DialogContext State Information</h4>
+
+ <p>The Dialog Manager provides a convenient place for an active
+ <code>DialogContext</code> instance to maintain state information
+ that lasts only for the lifetime of the instance. This is the
+ <code>data</code> property of the <code>DialogContext</code> instance
+ for the currently active dialog. Each Dialog Manager implementation
+ will provide a default data structure (typically an instance of
+ <code>java.util.Map</code>) for this purpose, but you may also provide
+ a JavaBean class that is application specific if you wish.</p>
+
+ <p>Note that, due to the combination of the current
<code>DialogContext</code>
+ instance being exposed as a request scoped attribute under key
+ <code>dialog</code>, and the fact that <code>data</code> is a standard
+ Java Bean property on this instance, you can conveniently use JSF
+ value binding expressions to bind component values to state
information.
+ For example, assume you have provided an application specific Java Bean
+ class for the state information, and it has a <code>name</code>
property
+ to contain a customer name. You can easily bind an input component to
+ that name, like this:</p>
+
+<source>
+ <h:inputText id="name" ... value="#{dialog.data.name}"/>
+</source>
+
+ <h4>Stopping An Active DialogContext Instance</h4>
+
+ <p>There are two general approaches to stopping the processing of an
+ active <code>DialogContext</code> instance:</p>
+
+ <ul>
+ <li>Each Dialog Manager implementation will typically define a
+ particular state as an "exit" or "end" state. When a
transition
+ to such a state occurs, the Dialog Manager implementation will
+ call <code>stop()</code> on the active
<code>DialogContext</code>
+ instance, which will take it out of service.</li>
+ <li>You can also cause the current <code>DialogContext</code>
+ instance to be aborted by calling <code>stop()</code> on it
+ yourself.</li>
+ </ul>
+
+ </subsection>
</section>
