Author: craigmcc
Date: Fri Sep 29 21:55:47 2006
New Revision: 451540
URL: http://svn.apache.org/viewvc?view=rev&rev=451540
Log:
Add the home page for the shale-view module, based on the corresponding
feature page.
TODO: Fix all the site.xml files to include a link to shale-site.
TODO: Update content of this file to reflect all of the functionality.
TODO: Deal with the relevant checkstyle/PMD/etc reports.
Added:
shale/framework/trunk/shale-view/src/site/
shale/framework/trunk/shale-view/src/site/site.xml (with props)
shale/framework/trunk/shale-view/src/site/xdoc/
shale/framework/trunk/shale-view/src/site/xdoc/index.xml (with props)
Added: shale/framework/trunk/shale-view/src/site/site.xml
URL:
http://svn.apache.org/viewvc/shale/framework/trunk/shale-view/src/site/site.xml?view=auto&rev=451540
==============================================================================
--- shale/framework/trunk/shale-view/src/site/site.xml (added)
+++ shale/framework/trunk/shale-view/src/site/site.xml Fri Sep 29 21:55:47 2006
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<project name="Apache Shale Framework - View Controller Support">
+
+ <body>
+
+ <menu name="Shale Taglib Resources">
+ <item name="Tag Reference" href="/tagreference.html"/>
+ <item name="Taglibdoc" href="/tlddoc/index.html"/>
+ </menu>
+
+ <menu name="Quick Links">
+ <item name="JavaServer Faces"
+ href="http://java.sun.com/javaee/javaserverfaces/"/>
+ <item name="MyFaces"
+ href="http://myfaces.apache.org"/>
+ <item name="Shale"
+ href="http://shale.apache.org"/>
+ <item name="Shale Sandbox"
+ href="http://shale.apache.org/sandbox"/>
+ <item name="Struts"
+ href="http://struts.apache.org"/>
+ <item name="Struts-Faces Integration Library"
+ href="http://struts.apache.org/1.x/struts-faces"/>
+ </menu>
+
+ <menu name="Sub-Project Documentation">
+ <item name="Clay Plug-In" href="../shale-clay/index.html"/>
+ <item name="Core Library" href="../shale-core/index.html"/>
+ <item name="Spring Integration" href="../shale-spring/index.html"/>
+ <item name="Test Framework" href="../shale-test/index.html"/>
+ <item name="Tiles Integration" href="../shale-tiles/index.html"/>
+ <item name="Tiger Extensions" href="../shale-tiger/index.html"/>
+ <item name="View Controller" href="../shale-view/index.html"/>
+ </menu>
+
+ <menu name="Sample Apps Documentation">
+ <item name="Blank Starter"
href="../shale-apps/shale-blank/index.html"/>
+ <item name="Clay Use Cases"
href="../shale-apps/shale-clay-usecases/index.html"/>
+ <item name="Mail Reader"
href="../shale-apps/shale-mailreader/index.html"/>
+ <item name="SQL Browser"
href="../shale-apps/shale-sql-browser/index.html"/>
+ <item name="Use Cases"
href="../shale-apps/shale-usecases/index.html"/>
+ </menu>
+
+ ${reports}
+
+ </body>
+
+</project>
+
+
+
+
+
Propchange: shale/framework/trunk/shale-view/src/site/site.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: shale/framework/trunk/shale-view/src/site/site.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Added: shale/framework/trunk/shale-view/src/site/xdoc/index.xml
URL:
http://svn.apache.org/viewvc/shale/framework/trunk/shale-view/src/site/xdoc/index.xml?view=auto&rev=451540
==============================================================================
--- shale/framework/trunk/shale-view/src/site/xdoc/index.xml (added)
+++ shale/framework/trunk/shale-view/src/site/xdoc/index.xml Fri Sep 29
21:55:47 2006
@@ -0,0 +1,208 @@
+<?xml version="1.0"?>
+<document>
+
+ <properties>
+ <title>Shale View Controller</title>
+ </properties>
+
+ <body>
+
+ <section name="Shale View Controller">
+ <a name="view"/>
+
+ <a name="view-introduction"/>
+ <subsection name="Introduction">
+
+ <p>Shale supports a mechanism that provides a 1:1 relationship between
+ a view tier presentation technology, which is responsible for creating
+ an HTTP response (such as a JSP page), and a corresponding JavaBean
class
+ containing event handling logic, (optionally) values used in the
dynamic
+ rendering of the response, and (optionally) bindings to the individual
+ user interface components included in the response page. Such a
JavaBean
+ class is known (in JavaServer Faces terminology) as a <em>backing
bean</em>.
+ In most circumstances, such a bean will be registered as a managed bean
+ (configured for creation in request scope).</p>
+
+ <p>JavaServer Faces does not require that a backing bean implement any
+ particular interface, or extend any particular base class. Therefore,
+ Shale does not impose any such restriction either. Instead, it
promises
+ that <em>if</em> an application's backing bean implements the
+ <code>ViewController</code> interface, then certain extra services will
+ be provided "for free."</p>
+
+ </subsection>
+
+ <a name="view-services"/>
+ <subsection name="Provided Services">
+
+ <p>Each backing bean that implements <code>ViewController</code> will
+ support a boolean property <code>postback</code>, which will be set to
+ <code>true</code> if this view is the one that is processing a form
+ submit previously rendered by the same page, or <code>false</code> if
+ this view was newly navigated to. The property will be set before any
+ of the lifecycle methods described below are called, so that
application
+ logic may perform conditional tasks based on this state.</p>
+
+ <p>As part of the standard JavaServer Faces managed beans processing,
any
+ <code><managed-property></code> elements in the configuration
+ file, that are nested inside the <code><managed-bean></code>
+ element for this backing bean, will also be processed when a new bean
+ instance is created. You can use either literal values or value
binding
+ expressions to customize properties on your backing bean class. Fans
+ of <em>Dependency Injection</em> will see that the managed beans
facility
+ provides support for such a framework, using Setter Injection as the
+ mechanism for injecting dependencies.</p>
+
+ <p>In addition, the following lifecycle events are called, by the
+ framework, at certain points in the JavaServer Faces request processing
+ lifecycle:</p>
+
+ <ul>
+ <li><strong>init()</strong> - Called immediately after the view that
+ this backing bean is associated with is created. (Technically, it
+ happens when <code>ViewManager.createView()</code> is called.)
+ For a postback, this happens during the <em>Restore View</em>
+ phase of the request processing lifecycle, once it has been
+ determined which view should be restored. If your application
+ navigates from one page to another, the <code>init()</code> method
+ of the second page will be called as part of the
+ <code>NavigationHandler.handleNavigation()</code> processing.
+ <blockquote>
+ Use this method to acquire resources that you will need, no
+ matter whether this is a postback request, a rendering request,
+ or both.
+ </blockquote></li>
+ <li><strong>preprocess()</strong> - Called after the <em>Restore
View</em>
+ phase has been completed, but before <em>Apply Request Values</em>
+ phase starts, <strong>only</strong> for the view that will be
+ processing the postback.
+ <blockquote>
+ Use this method to acquire resources (such as database
connections)
+ that you will need to process the postback.
+ </blockquote></li>
+ <li><strong>prerender()</strong> - Called immediately before the
+ <em>Render Response</em> phase that actually causes the view to
+ be rendered. This method will <strong>only</strong> be called for
+ the view that is actually rendered (the current view if you are
+ redisplaying, or the new view if you perform navigation).
+ <blockquote>
+ Use this method to acquire resources (such as database
connections,
+ or performing queries) that you will need if this view is the one
+ to be rendered. NOTE - when portlet support is integrated, all
of
+ the portlets on the current page will receive this event.
+ </blockquote></li>
+ <li><strong>destroy()</strong> - If <code>init()</code> was ever called
+ for a <code>ViewController</code>, then it is guaranteed that
+ <code>destroy()</code> will be called as well.
+ <blockquote>
+ Use this method to release any resources acquired during an
earlier
+ event handler.
+ </blockquote></li>
+ </ul>
+
+ <p>It can be difficult initially to visualize the order that events
will
+ occur, based solely on the descriptions above. Let's look at some
+ common scenarios and see what happens when:</p>
+
+ <ul>
+ <li><em>Initial navigation to welcome page, or a page directly accessed
+ via a URL</em>:
+ <ul>
+ <li>Backing bean is instantiated during <em>Restore View</em>
phase,
+ which notices that there is no previous state to restore.</li>
+ <li>The <code>setPostback(false)</code> and <code>init()</code>
methods
+ on your backing bean are called.</li>
+ <li>Because there is no previous state to restore, there will be no
+ form submit processing.</li>
+ <li>The <code>prerender()</code> method is called.</li>
+ <li>Standard <em>Render Response</em> phase processing occurs,
+ which causes the view to be rendered.</li>
+ <li>The <code>destroy()</code> method is called.</li>
+ </ul></li>
+ <li><em>Postback processed by a page that then redisplays itself (by
+ returning <code>null</code> from the action handler.)</em>:
+ <ul>
+ <li>Backing bean is instantiated during <em>Restore View</em>
phase,
+ which notices that there is previous state to restore.</li>
+ <li>The <code>setPostback(true)</code> and <code>init()</code>
methods
+ on your backing bean are called.</li>
+ <li>Standard <em>Apply Request Values</em> through <em>Invoke
+ Application</em> phase processing occurs, which includes
calling
+ your action and value change event handlers.</li>
+ <li>The <code>prerender()</code> method is called.</li>
+ <li>Standard <em>Render Response</em> phase processing occurs,
+ which causes the view to be rendered.</li>
+ <li>The <code>destroy()</code> method is called.</li>
+ </ul></li>
+ <li><em>Postback processed by page A, which then navigates to page
B</em>:
+ <ul>
+ <li>Backing bean for page A is instantiated during <em>Restore
View</em>
+ phase, which notices that there is previous state to
restore.</li>
+ <li>The <code>setPostback(true)</code> and <code>init()</code>
methods
+ on your backing bean for page A are called.</li>
+ <li>Standard <em>Apply Request Values</em> through <em>Invoke
+ Application</em> phase processing occurs for page A, which
+ includes calling your action and value change event
handlers.</li>
+ <li>As part of the navigation process, the backing bean for
+ page B is created.</li>
+ <li>The <code>prerender()</code> method for page B is called.</li>
+ <li>Standard <em>Render Response</em> phase processing occurs,
+ which causes the view to be rendered.</li>
+ <li>The <code>destroy()</code> method is called for both page B
+ and page A (since two backing beans were instantiated).</li>
+ </ul></li>
+ </ul>
+
+ </subsection>
+
+ <a name="view-using"/>
+ <subsection name="Using View Controller">
+
+ <p>For each JavaServer Faces <em>view</em> that you wish to associate
+ with a <code>ViewController</code> backing bean, you must:</p>
+
+ <ul>
+ <li>Implement the
+ <a
href="shale-core/apidocs/org/apache/shale/view/ViewController.html"
target="_blank">
+ <code>ViewController</code></a>
+ interface. The
+ most convenient way to do this is likely to be extending the
+ convenience base class
(<code>org.apache.shale.view.AbstractViewController</code>).</li>
+ <li>As required by the
+ <a href="http://java.sun.com/products/javabeans/";
target="_blank">JavaBeans</a>
+ specification, provide a no-args public constructor.</li>
+ <li>Declare your backing bean as a
<code><managed-bean></code>,
+ using a <code><managed-bean-name></code> value that can be
+ mapped from the view identifier. (See
+ <a
href="shale-core/apidocs/org/apache/shale/view/impl/DefaultViewControllerMapper.html"
target="_blank">
+ <code>DefaultViewControllerMapper</code></a> for the details of
+ the default mapping.)
+ In nearly all circumstances, you will want the bean to be placed
+ in request scope.</li>
+ <li>(Optional) Provide public JavaBean properties that may be set
+ to customize the functionality provided by this bean. Typically,
+ such properties will be configured based on the managed beans
+ configuration defined in the JavaServer Faces configuration
+ resources for your application.</li>
+ <li>Ensure that the functionality of your backing bean is
+ <strong>not</strong> dependent upon the order in which property
+ setters are called, since managed beans are configured via
+ the "setter injection" pattern.</li>
+ <li>Create event handlers for the lifecycle events of interest,
+ plus standard JavaServer Faces event handlers for things like
+ actions and value changes.</li>
+ <li>(Optional but recommended) Write a corresponding JUnit test
+ case using the Shale <a href="features-test-framework.html">Test
Framework</a>.
+ Because nearly all of your property and event handling methods
+ have no JavaServer Faces API dependencies for their parameter
+ signatures, it is generally quite easy to write such tests.</li>
+ </ul>
+
+ </subsection>
+
+
+ </section>
+
+ </body>
+
+</document>
Propchange: shale/framework/trunk/shale-view/src/site/xdoc/index.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: shale/framework/trunk/shale-view/src/site/xdoc/index.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
