svn commit: r1516731 - /isis/site/trunk/content/components/viewers/wicket/customizing-the-viewer.md

[da...@apache.org]

Author: danhaywood
Date: Fri Aug 23 08:09:44 2013
New Revision: 1516731

URL: http://svn.apache.org/r1516731
Log:
customizing the viewer page

Modified:
    isis/site/trunk/content/components/viewers/wicket/customizing-the-viewer.md

Modified: isis/site/trunk/content/components/viewers/wicket/customizing-the-viewer.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/components/viewers/wicket/customizing-the-viewer.md?rev=1516731&r1=1516730&r2=1516731&view=diff
==============================================================================
--- isis/site/trunk/content/components/viewers/wicket/customizing-the-viewer.md (original)
+++ isis/site/trunk/content/components/viewers/wicket/customizing-the-viewer.md Fri Aug 23 08:09:44 2013
@@ -71,10 +71,22 @@ Again, the `welcome.html` file is resolv
 The pages generated by Isis' Wicket viewer are built up of numerous elements,
 from fine-grained widgets for property/parameter fields, to much larger components that take responsibility for rendering an entire entity entity, or a collection of entities.  Under the covers these are all implementations of the the Apache Wicket `Component` API.  The larger components delegate to the smaller, of course.
 
+##### How the Wicket viewer selects components
 Components are created using Isis' `ComponentFactory` interface, which are registered in turn through the `ComponentFactoryRegistrar` interface.  Every
-component is categorizes by type (the `ComponentType` enum); Isis uses this information as well as information taken from Isis' metamodel to determine which `ComponentFactory` to use.  Generally, the first `ComponentFactory` that can render a component of a certain type is used (the chain of responsibility pattern).
+component is categorizes by type (the `ComponentType` enum).  Isis uses this to determine which `ComponentFactory` to use.  For example, the `ComponentType.BOOKMARKED_PAGES` is used to locate the `ComponentFactory` that will build the bookmarked pages panel.
 
-This design makes it quite straightforward to change the rendering of any element of the page.  For example, you might switch out Isis' sliding bookmark panel and replace it with one that presents the bookmarks in some different fashion.
+In many cases, though, additional information is needed.  For example,  is the type to render a scalar property or parameter.  But there are many different `ComponentFactory` implementations; one for a string, one for a boolean, one for a date etc.  
+
+Each factory is also handed a model (an implementation of `org.apache.wicket.IModel`) appropriate to its `ComponentType`; this holds the data to be rendered.  For example, `ComponentType.BOOKMARKED_PAGES` is given a `BookmarkedPagesModel`, while `ComponentType.SCALAR_NAME_AND_VALUE` factories are provided a model of type of type `ScalarModel` .   
+
+In some cases there are several factories for a given `ComponentType`; this is most notably the case for `ComponentType.SCALAR_NAME_AND_VALUE`.  After doing a first pass selection of candidate factories by `ComponentType`, each factory is then asked if it `appliesTo(Model)`.  This is an opportunity for the factory to check the model itself to see if the data within it is of the appropriate type.
+
+Thus, the `BooleanPanelFactory` checks that the `ScalarModel` holds a boolean, while the `JodaLocalDatePanelFactory` checks to see if it holds  `org.joda.time.LocalDate`.  
+
+There will typically be only one `ComponentFactory` capable of rendering a particular `ComponentType`/`ScalarModel` combination; at any rate, the framework stops as soon as one is found.  (*There is one exception to this design, discussed in the next section*).
+
+##### How to replace a component 
+This design (the [chain of responsibility](http://en.wikipedia.org/wiki/Chain-of-responsibility_pattern) design pattern) makes it quite straightforward to change the rendering of any element of the page.  For example, you might switch out Isis' sliding bookmark panel and replace it with one that presents the bookmarks in some different fashion.
 
 First, you need to write a `ComponentFactory` and corresponding `Component`.  The recommended approach is to start with the source of the `Component` you want to switch out.  For example: