myfaces-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Myfaces Wiki] Update of "FacesMajor Renderers" by AdamWiner
Date Thu, 03 Aug 2006 20:24:45 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Myfaces Wiki" for change notification.

The following page has been changed by AdamWiner:
http://wiki.apache.org/myfaces/FacesMajor_Renderers

The comment on the change is:
Initial set of documentation about writing Faces-major renderers.

------------------------------------------------------------------------------
   * Subramaniam, Pavitra
   * Wessendorf, Matthias
  
+ New Renderers are being buit in org.apache.myfaces.trinidadinternal.renderkit.core.xhtml.
<code>XhtmlRenderer</code> extends <code>CoreRenderer</code> is the
base class for (most) of our renderers.
+ 
+ These renderers no longer necessarily have a pre- and post- phase.  Instead:
+ * If getRendersChildren() has been overridden to return true, do all your coding in:
+ 
+   protected void encodeAll(
+     FacesContext        context,
+     AdfRenderingContext arc,
+     UIComponent         component,
+     FacesBean           bean) throws IOException
+ 
+ * If getRendersChildren() returns false (the default, but uncommon), you do get a pre- and
post- but not a renderContent();  use these two hooks:
+ 
+   protected void encodeBegin(
+     FacesContext        context,
+     AdfRenderingContext arc,
+     UIComponent         component,
+     FacesBean           bean) throws IOException
+   protected void encodeEnd(
+     FacesContext        context,
+     AdfRenderingContext arc,
+     UIComponent         component,
+     FacesBean           bean) throws IOException
+ 
+ 
+ === Retrieving properties ===
+ 
+ Property retrieval should always go via the bean, not by the component and never, ever by
the attribute map.  Every time you want a property from a renderer, you do the following:
+ * In an override of findTypeConstants(), get the property key from the FacesBean.Type, and
save it as an instance variable.  The FacesBean.Type is hardcoded in renderers with no subclasses
(get it from the TYPE static variable on the component), and passed to the constructor in
abstract base classes.
+ * Add a getter that takes a bean.
+ 
+ <b>Example:</b>
+ 
+   protected void findTypeConstants(FacesBean.Type type)
+   {
+     super.findTypeConstants(type);
+     _shortDescKey = type.findKey("shortDesc");
+     // etc...
+   }
+ 
+   protected String getShortDesc(FacesBean bean)
+   { 
+     // toString() is a convenience function on CoreRenderer
+     return toString(bean.getProperty(_shortDescKey));
+   }
+ 
+   private PropertyKey _shortDescKey;
+ 
+ By this strategy, a property like shortDesc that is actually defined at the leaves of our
component type heirarchy can be generically referred to in a base renderer.
+ 
+ === Rules ===
+ 
+ The following rules apply:
+ * Code in core.xhtml may not import code in view.faces.ui.  No exceptions.
+ * However view.faces.ui may point at core.xhtml.
+ * Do not add functionality to view.faces.ui.
+ * Do not "implement XhtmlConstants".  Use explicit references.
+ * Do not use "partialTargets" at all in any faces-major code.  If a component needs to redraw
itself in response to a PPR event, it should do so by calling AdfFacesContext.addPartialTarget()
during decode().
+ * Never call getAttributes().  Always follow the "Retrieving properties" pattern above.
+ * Do not use _uixspu anymore. Use _adfspu (which does not have the partial or partialTargets
parameters).
+ * In protected accessors, use the protected CoreRenderer.toString(Object) to convert from
Object to
+    String;  unless its an URL, in which case use CoreRenderer.toURL(Object).
+ * Never write out URLs using ResponseWriter.writeURIAttribute().  Always use XhtmlRenderer.renderEncodedActionURI()
or XhtmlRenderer.renderEncodedResourceURI().
+ 
+ === Replacements for old UIX functionality ===
+ 
+ AdfRenderingContext replaces most of the RenderingContext functionality.
+ * AdfRenderingContext can be retrieved as a thread-local with getCurrentInstance().
+ * AdfRenderingContext.getProperties() returns a Map for rendering properties.
+ 
+ One special thing about AdfRenderingContext.getProperties():  if you store an old RenderingContext
property, using the MARLIN_NAMESPACE namespace, it actually goes into the AdfRenderingContext
properties Map!  So, as long as you use exactly the same key, old- and new-style code can
communicate.
+ 
+ Instead of providing PDA or BLAF renderers that just subclass a few things, lean on Skin
properties.  For example, when deciding whether to show the last "breadCrumb"/"menuPath" item,
we now use a Skin property.
+ 
+ Do not refer to UIConstants or XhtmlLafConstants;  use XhtmlConstants.
+ 

Mime
View raw message