Overview
The Shale ViewController
functionality allows a managed bean to get callbacks on a per-view (ie per-page) basis, in contrast to the normal callbacks invoked per-component.
Configuration
The jsf configuration files included in the shale-core jarfile automatically registers the necessary shale objects with the JSF implementation, so no changes need to be made to web.xml; just placing the shale-core jarfile in the webapp's WEB-INF/lib directory is sufficient. (NOTE – as of version 1.0.4, this logic will be factored out into the new shale-view jarfile, and this refactoring exists in current nightly buids.)
The ViewViewHandler
class implements the JSF standard ViewHandler
class. It is installed as a wrapper around the ViewHandler
implementation provided by the underlying JSF implementation. It is this class that invokes the setPostBack method on the
ViewController
.
In order to tell shale's view controller framework which bean to call for each page, it is necessary to define a ViewControllerMapper
strategy which creates a managed bean name from the value returned by UIViewRoot.getViewId()
, ie from the portion of the page url between the webapp name and the query params. An instance of DefaultViewControllerMapper
is used by default; see the documentation for that class for details of the mapping. The managed bean with that name is expected to implement the ViewController
interface (but see comments on Tiger below).
It is possible to override the default ViewControllerMapper
simply by defining an application-scoped managed bean with name "org$apache$shale$view$VIEW_MAPPER" that implements the ViewControllerMapper
interface.
Subviews
In the Shale 1.0.3 release (latest at the current date) there is no support for callbacks for subviews. This means that even if a page is composed of multiple other pages (via jsp:include or other mechanism), all page-related callbacks must go through a single managed bean which introduces undesirable coupling.
The trunk code as at 2006-11-07 contains some code that appears to support a separate ViewController managed bean for each f:subview in the page by overriding the renderer for subviews to invoke preprocess on processDecodes and prerender on encodeBegin. (NOTE - as of version 1.0.4, subview lifecycle events will be fully supported, and this support exists in current nightly builds.)
Tiger
If the Shale Tiger libraries are present, then a few more features are available. Tiger is specifically for java 1.5 and allows the use of annotations on ordinary managed beans to mark the view-controller callback methods rather than requiring the managed bean to implement the ViewController
interface.
Implementation Classes
org.apache.shale.view.faces.ViewController
defines the callbacks available; the managed bean needs to implement this interface in order to get callbacks. Alternately, concrete subclassAbstractViewController
can be subclassed.org.apache.shale.view.faces.LifecycleListener
invokes the init and destroy callbacks.ViewViewHandler
wraps the standardViewHandler
and whenever a view is created (eg restore or forward) it determines which managed bean corresponds to this view and caches this in the current request.ViewPhaseListener
invokes the preprocess/prerender methods on theViewController
managed bean located earlier by theViewViewHandler
.