You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by cr...@apache.org on 2005/06/12 06:49:40 UTC
svn commit: r190214 - in /struts/core/trunk/doc/shale: features.xml index.xml
Author: craigmcc
Date: Sat Jun 11 21:49:40 2005
New Revision: 190214
URL: http://svn.apache.org/viewcvs?rev=190214&view=rev
Log:
Add documentation for the "Clay" reusable components feature.
PR: Bugzilla #35332
Submitted By: Gary vanMatre <gvanmatre AT comcast.net>
Modified:
struts/core/trunk/doc/shale/features.xml
struts/core/trunk/doc/shale/index.xml
Modified: struts/core/trunk/doc/shale/features.xml
URL: http://svn.apache.org/viewcvs/struts/core/trunk/doc/shale/features.xml?rev=190214&r1=190213&r2=190214&view=diff
==============================================================================
--- struts/core/trunk/doc/shale/features.xml (original)
+++ struts/core/trunk/doc/shale/features.xml Sat Jun 11 21:49:40 2005
@@ -101,8 +101,8 @@
</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>
+ 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
@@ -426,8 +426,187 @@
<section name="Shale Reusable Views" href="clay">
- <p>FIXME - Describe Clay plugin feature.</p>
+ <subsection name="Clay Introduction" href="clay-introduction">
+ <p>The <strong>Clay</strong> component is a complex JavaServer Faces
+ component that features a way to build more reusable view fragments.
+ As it's name implies, the Clay component can be shaped and molded into
+ a subtree of JSF components acting as a "stand-in"
+ for the JSP tags normally required to add components
+ to the view's component tree.</p>
+
+ </subsection>
+
+ <subsection name="Clay View Composition Options" href="clay-view-options">
+
+ <p>There are three options for creating the Clay component subtree.</p>
+
+ <ol>
+ <li>The Clay subtree can be formed by strictly using a XML configuration
+ that resembles JSF/JSP tags. The meta-data used to define a
+ component is similar to Tiles. It provides composition and allows
+ for inheritance relationships. Clay's approach is unique. The
+ granularity is targeted at the declaration of JSF components versus
+ composition of JSP fragments.
+ <blockquote><pre>
+<clay:clay id="address" jsfid="addressPanel"/>
+</pre></blockquote></li>
+ <li>The subtree can be formed using a Tapestry like HTML layout. HTML
+ elements are bound to corresponding JSF components using a
+ <code>jsfid</code> attribute. This attribute binds the HTML mock-up
+ with a component declared in the Clay view configuration files.
+ Some HTML elements, the such as the <code>FORM</code> element,
+ have an implied mapping to a JSF component. If the mapping is
+ not explicitly declared using the <code>jsfid</code> attribute and
+ there is not an assumed mapping, the default mapping is to the
+ standard <code>verbatim</code> (<code>ouputText</code>) component.
+ This combines the first option's component definitions
+ with the flexibility of using HTML for layout.<br/>
+ <blockquote><pre>
+<clay:clay id="address" jsfid="address.html"/>
+</pre></blockquote></li>
+ <li>The subtree can also be defined at runtime. The Clay component
+ provides a postback validation method event,
+ <code>shapeValidator</code>, that can be bound to the associated
+ <code>ViewController</code>. The event is fired on the
+ <code>ViewController</code> when the subtree is first created.
+ Responding to this event, the view controller will construct a
+ graph of objects used by the Clay component to build the
+ subcomponent tree. The object's graph is representative of
+ the first two declarative approaches.
+ <blockquote><pre>
+<clay:clay id="address" jsfid="RUNTIME" shapeValidator="#{fullAddress.createSubtree}"/>
+</pre></blockquote></li>
+ </ol>
+
+ </subsection>
+
+ <subsection name="Clay Key Reuse Features" href="clay-reuse-features">
+
+ <p>The Clay XML configuration data is a replacement for the JSF/JSP tags.
+ A base configuration file is provide in the META-INF directory of the
+ <code>shale-clay.jar</code> archive. The configuration document
+ type definitions have similarities to the JSP tags, but are designed
+ to be more generic. The same node structure is used to define a
+ variety of resources.</p>
+
+ <p>A <code>component</code> is a "top-level" element. In the DTD, a
+ <code>component</code> can represent a JSF component, converter,
+ validator, action listener or value change listener. Only
+ "top-level" elements can be the root of a clay subtree. The
+ <code>componentType</code> attribute defines the association
+ to the face's resource. The <code>jsfid</code> attribute is a
+ logical unique identifier.
+ <blockquote><pre>
+<component jsfid="outputText" componentType="javax.faces.HtmlOutputText"/>
+<component jsfid="validateLongRange" componentType="javax.faces.LongRange"/>
+</pre></blockquote></p>
+
+ <p>A <code>component</code> can extend another component, thereby
+ inheriting <code>attributes</code> and contained <code>element</code>
+ nodes from the parent component. This is accomplished by using
+ the <code>extends</code> attribute. The value of the
+ <code>extends</code> attribute should be a <code>jsfid</code> of
+ the parent <code>component</code> definition.
+ <blockquote><pre>
+<component jsfid="baseLabel" extends="outputLabel" allowBody="false">
+ <attributes>
+ <set name="style" value="color:blue"/>
+ </attributes>
+</component>
+<component jsfid="cityLabel" extends="baseLabel">
+ <attributes>
+ <set name="value" value="City:"/>
+ <set name="for" value="city"/>
+ </attributes>
+</component>
+</pre></blockquote></p>
+
+ <p>A <code>component</code> node has an attribute container. This is
+ a generic container to hold all <code>attributes</code> that would
+ be represented by associated JSF/JSP Tags. Attributes are added or
+ overridden in inheritance using the attribute <code>name</code> as the
+ unique identifier.
+ <blockquote><pre>
+<component jsfid="addressPanel" extends="panelGrid">
+ <attributes><br/>
+ <set name="columns" value="2" />
+ </attributes>
+ <element renderId="1" jsfid="street1Label"/>
+ <element renderId="2" jsfid="street1"/>
+</component>
+<component jsfid="addressPanelEx" extends="addressPanel">
+ <attributes>
+ <set name="columns" value="3" />
+ </attributes>
+ <element renderId="3" jsfid="street1Message"/>
+</component>
+</pre></blockquote></p>
+
+ <p>The <code>element</code> node is the composition glue. Components
+ are uniquely defined by a <code>renderId</code> attribute. This
+ integer value defines the sequential order within the outer
+ <code>component</code>. The <code>renderId</code> attribute also
+ acts as the "method signature" for the <code>element</code> when
+ resolving inheritance. This means components can extend other
+ components by overriding or extending elements based on the
+ <code>renderId</code> of the first level of child components.
+ <blockquote><pre>
+<component jsfid="ssnColumn" extends="column" id="ssn">
+ <element renderId="1" jsfid="outputText" facetName="header">
+ <attributes>
+ <set name="value" value="SSN" />
+ </attributes>
+ </element>
+ <element renderId="2" jsfid="outputText">
+ <attributes>
+ <set name="value" useValueLateBinding="true" value="#{e.ssn}" />
+ </attributes>
+ </element>
+</component>
+<component jsfid="personTable" extends="dataTable">
+ <attributes>
+ <set name="value" useValueLateBinding="true" value="#{managed-bean-name.persons}"/>
+ <set name="var" value="e"/>
+ <set name="rows" value="5"/>
+ <set name="first" value="1"/>
+ <set name="border" value="1"/>
+ <set name="cellpadding" value="3"/>
+ </attributes>
+ <element renderId="1" jsfid="firstNameColumn"/>
+ <element renderId="2" jsfid="lastNameColumn"/>
+</component>
+<component jsfid="employeeTable" extends="personTable">
+ <element renderId="0" jsfid="ssnColumn"/>
+ <element renderId="3" jsfid="birthDateColumn"/>
+</component>
+</pre></blockquote></p>
+
+ <p>Clay also allows reuse of view fragments bound to different logical
+ managed bean names. Managed bean names in Shale will most likely
+ resolve to a <code>ViewController</code> implementation. Decoupling
+ a view with the managed bean name is accomplished by using a simple
+ token replacement on the expression. This is only performed on
+ attribute values containing faces EL bindings. A token value of
+ "managed-bean-name" is replaced with the value of the Clay
+ <code>managedBeanName</code> property. This preprocessing is
+ performed prior to applying the meta attribute values to the target
+ JavaServer Faces component's properties.<br/>
+ <blockquote><pre>
+<clay:clay id="saveResidential" managedBeanName="residentialAddress" jsfid="saveCommand"/>
+<clay:clay id="saveBusiness" managedBeanName="businessAddress" jsfid="saveCommand"/>
+<component jsfid="saveCommand" extends="commandButton">
+ <attributes>
+ <set name="value" value="Save" />
+ <set name="action" useValueLateBinding="true" value="#{managed-bean-name.save}" />
+ <set name="actionListener" useMethodLateBinding="true" value="#{managed-bean-name.saveAction}"/>
+ </attributes>
+ <actionListener jsfid="logNavigationActionListener"/>
+</component>
+</pre></blockquote></p>
+
+ </subsection>
+
</section>
Modified: struts/core/trunk/doc/shale/index.xml
URL: http://svn.apache.org/viewcvs/struts/core/trunk/doc/shale/index.xml?rev=190214&r1=190213&r2=190214&view=diff
==============================================================================
--- struts/core/trunk/doc/shale/index.xml (original)
+++ struts/core/trunk/doc/shale/index.xml Sat Jun 11 21:49:40 2005
@@ -10,9 +10,56 @@
<section name="Shale Framework" href="background">
- <p>FIXME - Shale Framework background. While waiting for this section
- to be completed, the <a href="http://people.apache.org/~craigmcc/struts-shale-README.html">
- Original Shale Proposal</a> makes for interesting reading.</p>
+
+ <subsection name="Background" href="background-background">
+
+ <p>Little did anyone know, when the first few lines of code were
+ committed to the <a href="http://struts.apache.org">Struts</a>
+ CVS repository in June 2000, that a revolution was brewing. Prior
+ to that time, there were few useful models for best practices for
+ the architecture of web based applcations. The best we could do
+ was handwaving about "Model 1" and "Model 2" approaches.</p>
+
+ <p>The original implementation of Struts, which was released as a
+ 1.0 product approximately one year later, changed all that. As
+ more and more people came to understand the advantages of building
+ on top of a stable and supported framework, and as more and more
+ developers adopted it for their own application development, and
+ as more and more books helped everyone understand how to use the
+ framework correctly, and as more and more development tools provided
+ support for building Struts based applications, the word changed.
+ A small open source project became a defacto industry standard that,
+ even today, is very popular.</p>
+
+ <p>But that was then ... and this is now. In the years that Struts
+ has been around (five and counting as of this writing), vastly
+ improved technologies have become available from many talented
+ architects and designers. Moore's Law has continued its seemingly
+ inexhaustible progress. Developers have grown in their ability to
+ understand the benefits of a monolithic controller architecture ...
+ as well as increasingly developing preferences towards agility,
+ code reuse, unit tests, and building applications by composition
+ instead of inheritance.</p>
+
+ <p>One of the critical success factors for Struts has been, and
+ continues to be, an obvious commitment on the part of the Struts
+ developers towards backwards compatibility. This has led to Struts
+ being both praised (for protecting the investment of developers
+ with thousands of applications critically dependent on the framework)
+ and dissed (for being a dinosaur compared to all the "latest and
+ greatest" favorite technological approaches). History has shown,
+ in terms of its continued popularity, that this is a good
+ strategic approach.</p>
+
+ </subsection>
+
+
+ <subsection name="Foundations" href="background-foundations">
+
+ <p>FIXME - describe foundational technologies.</p>
+
+ </subsection>
+
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org