Author: gvanmatre Date: Sun Feb 19 10:03:05 2006 New Revision: 378934 URL: http://svn.apache.org/viewcvs?rev=378934&view=rev Log: Updated a couple sections on clay options and reuse features.
Modified: struts/shale/trunk/xdocs/features-reusable-views.xml Modified: struts/shale/trunk/xdocs/features-reusable-views.xml URL: http://svn.apache.org/viewcvs/struts/shale/trunk/xdocs/features-reusable-views.xml?rev=378934&r1=378933&r2=378934&view=diff ============================================================================== --- struts/shale/trunk/xdocs/features-reusable-views.xml (original) +++ struts/shale/trunk/xdocs/features-reusable-views.xml Sun Feb 19 10:03:05 2006 @@ -288,89 +288,200 @@ sophisticated symbol replacement than the managed bean example discussed above.</p> </subsection> - <a name="clay-view-options"/> - <subsection name="Clay View Composition 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. -<source> -<clay:clay id="address" jsfid="addressPanel"/> -</source></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, 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/> -<source> -<clay:clay id="address" jsfid="address.html"/> -</source></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. -<source> -<clay:clay id="address" jsfid="RUNTIME" shapeValidator="#{fullAddress.createSubtree}"/> -</source></li> - </ol> - - <p>Each of these options is demonstrated in the Shale Use Cases - example application. The Clay "Rolodex" is shown below:</p> - <p style="text-align: center"> - <img src="images/clay-rolodex.gif" alt="Shale Use Cases - Clay Rolodex Example"/> +<a name="clay-view-options"/> +<subsection name="Clay View Composition Options"> +<p> +There are four options for creating the Clay component subtree. +<ol> + <li><p>The Clay subtree can be formed by strictly using a XML configuration that resembles JSF/JSP + tags. The XML configuration provides the maximum reuse. The meta-data used to define a component + is similar to Tiles. There can be multiple files defined but there is always a default loaded from + within the shale clay java archive. 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. </p> - - </subsection> - - <a name="clay-reuse-features"/> - <subsection name="Clay Key Reuse Features"> - - <p>The Clay XML configuration data is a replacement for the JSF/JSP tags. - A base configuration file is provided 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 - <a href="http://struts.apache.org/dtds/shale-clay-config/1_0/" target="_blank">DTD</a>, - 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.</p> - -<source> +<p><blockquote><pre> +<clay:clay id="namePanel" jsfid="namePanel" managedBeanName="rolodex.selectedContact"/> +</pre></blockquote></p> + </li> + <li><p>The subtree can be formed using a Tapestry like HTML layout. The benefit of using HTML + layout composition is that it allows you to use standard HTML tools. It also promotes + more rapped development as an HTML prototype can evolve into a dynamic web page. The + HTML elements are bound to corresponding JSF components using a jsfid 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 FORM element, have an implied mapping to a + JSF component. + <br/> + The eleven implicitly mapped elements include: + <ol> + <li><a></a></li> + <li><form></form></li> + <li><input type=text></li> + <li><input type=checkbox></li> + <li><input type=radio></li> + <li><input type=submit></li> + <li><label></label></li> + <li><select></select></li> + <li><select multiple></select></li> + <li><option></li> + <li><textarea></textarea></li> + </ol> + </p> + <p>These implicitly mappings can be overridden with a block "ignore". This is accomplished by + surrounding the HTML that you would like to ignore with a well formed tag like the span tag + and marking it with the reserved jsfid of "ignore". The surrounding tag will not be rendered + but the child content will be rendered verbatim. + </p> + +<p><blockquote><pre> +<span jsfid="ignore"> + <form method="POST" action="j_security_check"> + Username:<input type="text" name="j_username"><br> + Password:<input type="password" name="j_password"> + <input type="submit" value="submit"> + </form> +</span> +</pre></blockquote></p> + + <p>Any HTML element that is explicitly marked with a jsfid attribute, can morph into any + type of faces component. This includes the eleven implicitly mapped elements. + If the mapping is not explicitly declared using the jsfid attribute and there is not + an assumed mapping, the default mapping is to the standard verbatim "ouputText" component. + This combines the first option's component definitions with the flexibility of using HTML + for layout. This raw text is applied to the "outputText" component using value binding. + This means that the body of the HTML can contain inline expression language (EL) similar + to JSP 2.0 + </p> +<p><blockquote><pre> + <label for=city>#{messages.cityLabel}</label> +</pre></blockquote></p> + + <p>Another similar reserved jsfid is the "void" identifier. It's purpose is to remove a HTML + markup from the target document. This is helpful if you want to create a well formed document + for mock-up but only want to include a smaller fragment. The following example shows how the + outer document markup will be removed and only the content of the html body will be considered. + </p> +<p><blockquote><pre> + <html jsfid="void"> + <head jsfid="void" allowBody="false"> + <title>Mock Title</title> + </head> + <body jsfid="void"> + <label for=city>#{messages.cityLabel}</label> + <input type="text" value="[EMAIL PROTECTED]" id="city"> + </body> + </html> +</pre></blockquote></p> + + <p>There are two types of HTML layouts, page fragment and full HTML layouts. The page fragments + can be pulled into a JSP page using the clay tag. The jsfid is used to identify the HTML page + composition. The suffix of the jsfid distinguishes a HTML layout for a normal component. + A ending suffix of ".html" is the default. + <br/>This example shows how a partial view can be used within a JSP page. + </p> + +<p><blockquote><pre> + <clay:clay id="address" jsfid="/address.html" managedBeanName="address" /> +</pre></blockquote></p> + + <p>Clay also supports full HTML views. This means that you can create a complete JavaServer Faces + view using a HTML layout. The entry point or resource that formulates the view id is a HTML page. + There are only a couple difference between partial HTML views and full HTML views. The first + difference is that the view id is used as identification verses the jsfid. Instead of invoking a + resource with a suffix of ".jsp", the target URI is a HTML layout with a file suffix of ".html". + The second difference is that the managedBeanName property is assumed and cannot be explicitly specified. + It plays by the same rules as the Shale ViewController mapping to a registered manged bean. This means + the registered "@managed-bean-name" is derived from the viewId of the page. For example, a page identifed + by "/symbols/page1.html" would have a default view controller mapping of "symbols$page1". + </p> + <p>It is also possible to create a HTML full or partial view that doesn't require additional entries + in the XML configuration files other than the defaults that are automatically loaded. The attributes + specified in the HTML element are passed on to the corresponding JSF component properties. The HTML + attributes are case insensitive but otherwise must match attributes defined for the component in the + Clay configuration file. + </p> +<p><blockquote><pre> + <input type=text [EMAIL PROTECTED] id=city size=20> + <input type=submit value=Save [EMAIL PROTECTED]> +</pre></blockquote></p> + </li> + <li><p>The subtree can also be defined at runtime. The runtime support allows the view to be defined by data + from the model tier. The Clay component provides a postback validation method event, shapeValidator, + that can be bound to the associated ViewController. The event is fired on the ViewController 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. + </p> + <p>This is an example of how the runtime option would be used within a JSP page: +<blockquote><pre> + <clay:clay id="address" jsfid="RUNTIME" + shapeValidator="#{fullAddress.createSubtree}"/> +</pre></blockquote></p> + + <p>The runtime option is supported with the other types of composition. Clay provides a registered managed + bean that provides some added runtime utilities such as "clayOut" and "clayImport". + </p> +<p><blockquote><pre> +<span jsfid="clayOut" value="&lt;br&gt;" escapeXml="false"/> +</pre></blockquote></p> + +<p><blockquote><pre> +<pre> + <span jsfid="clayImport" url="#{param['url']}" escapeXml="true"/> +</pre> +</pre></blockquote></p> + </li> + <li><p>The forth type of clay composition is full XML views. This is similar to full HTML views but the + view is completely described in a XML configuration file. The default suffix is ".xml". This option + provides for maximum reuse but is also the most complicated. + </p> +<p><blockquote><pre> +<!DOCTYPE view PUBLIC + "-//Apache Software Foundation//DTD Shale Clay View Configuration 1.0//EN" + "http://struts.apache.org/dtds/shale-clay-config-1_0.dtd"> + +<view> + <component jsfid="/rolodex/rolodex.xml" extends="clay"> + <attributes> + <set name="clayJsfid" value="/rolodex/xhrolodex.html" /> + <set name="managedBeanName" value="rolodex$xhrolodex" /> + </attributes> + </component> +</view> +</pre></blockquote></p> + </li> + + </ol> + <p>Each of these options is demonstrated in the Shale Use Cases + example application. The Clay "Rolodex" is shown below:</p> + <p style="text-align: center"><img src="images/clay-rolodex.gif" alt="Shale Use Cases - Clay Rolodex Example"/></p> +</p> + +</subsection> + +<a name="clay-reuse-features"/> +<subsection name="Clay Key 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 shale-clay.jar 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 <a href="http://struts.apache.org/dtds/shale-clay-config/1_0/" target="_blank">DTD</a>, + 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. +</p> + +<p><blockquote><pre> <component jsfid="outputText" componentType="javax.faces.HtmlOutputText"/> <component jsfid="validateLongRange" componentType="javax.faces.LongRange"/> -</source> - - <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 the <code>jsfid</code> of - the parent <code>component</code> definition.</p> +</pre></blockquote></p> -<source> +<p>A component can extend another component, thereby inheriting attributes and contained element nodes from the parent component. This is accomplished + by using the extends attribute. The value of the extends attribute should be a jsfid of the parent component definition. +</p> +<p><blockquote><pre> <component jsfid="baseLabel" extends="outputLabel" allowBody="false"> <attributes> <set name="style" value="color:blue"/> @@ -382,17 +493,15 @@ <set name="for" value="city"/> </attributes> </component> -</source> - - <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.</p> +</pre></blockquote></p> -<source> +<p>A component node has an attribute container. This is a generic container to hold all attributes that would be + represented by associated JSF/JSP Tags. Attributes are added or overridden in inheritance using the attribute + name as the unique identifier. +</p> +<p><blockquote><pre> <component jsfid="addressPanel" extends="panelGrid"> - <attributes> + <attributes><br/> <set name="columns" value="2" /> </attributes> <element renderId="1" jsfid="street1Label"/> @@ -404,18 +513,15 @@ </attributes> <element renderId="3" jsfid="street1Message"/> </component> -</source> - - <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.</p> +</pre></blockquote></p> -<source> +<p>The element node is the composition glue. Components are uniquely defined by a renderId attribute. + This integer value defines the sequential order within the outer component. The renderId attribute + also acts as the "method signature" for the element when resolving inheritance. This means components + can extend other components by overriding or extending elements based on the renderId of the first + level of child components. +</p> +<p><blockquote><pre> <component jsfid="ssnColumn" extends="column" id="ssn"> <element renderId="1" jsfid="outputText" facetName="header"> <attributes> @@ -424,13 +530,13 @@ </element> <element renderId="2" jsfid="outputText"> <attributes> - <set name="value" useValueLateBinding="true" value="#{e.ssn}" /> + <set name="value" value="#{e.ssn}" /> </attributes> </element> </component> <component jsfid="personTable" extends="dataTable"> <attributes> - <set name="value" useValueLateBinding="true" value="#{managed-bean-name.persons}"/> + <set name="value" value="[EMAIL PROTECTED]"/> <set name="var" value="e"/> <set name="rows" value="5"/> <set name="first" value="1"/> @@ -444,33 +550,183 @@ <element renderId="0" jsfid="ssnColumn"/> <element renderId="3" jsfid="birthDateColumn"/> </component> -</source> +</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.</p> - -<source> -<clay:clay id="saveResidential" managedBeanName="residentialAddress" jsfid="saveCommand"/> +<p>Clay also allows reuse of view fragments bound to different logical managed bean names. + There is limitation when using JSP fragments for constructing JSF page composition. The view + is coupled with the backing bean through a expression language (EL). The view fragment is bound + to only one managed bean. The "managedBeanName" attribute of the Clay component discussed above + is a Symbol. Symbols can be used to alter a binding expression. Managed bean names in Shale + will most likely resolve to a ViewController. Decoupling a view with the managed bean name is + accomplished by using a simple token replacement on the expression. This is performed on attribute + values containing faces EL bindings. A token value of "@managed-bean-name" is replaced with the + value of the Clay managedBeanName property. The replacement of the literal string "@managed-bean-name" + with the value of the managedBeanName property is done before creating the expression language binding. +</p> +<p>This example show how the literal string "@managed-bean-name" will be replaced with "businessAddress". +</p> +<p><blockquote><pre> +<clay:clay id="address" managedBeanName="businessAddress" jsfid="saveCommand"/> <clay:clay id="saveBusiness" managedBeanName="businessAddress" jsfid="saveCommand"/> +</pre></blockquote> +<blockquote><pre> <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}"/> + <set name="action" value="[EMAIL PROTECTED]" /> + <set name="actionListener" value="[EMAIL PROTECTED]"/> </attributes> <actionListener jsfid="logNavigationActionListener"/> </component> -</source> +</pre></blockquote></p> + +<p>Symbols are an important reuse feature in Clay. Symbols are a string substitution layer that sits on + top of a meta-data value before it is applied to the component. The meta-data can be intermixed with + any type of component property. Symbols are identified using a prefix delimiter. The delimiter is a + single @ character. +</p> +<p>What can you do with Symbols? They allow creation of dictionaries of components and component compositions + that surpasses the simple reuse of JavaServer Pages (JSP) fragments. +</p> +<p>How are Symbols defined? Symbols are always associated with component meta-data. The meta-data defines + component properties and how components are assembled within a page. There is currently a couple sources + to define symbols, XML and HTML. In the future this could be expanded to other sources. +</p> +<p>In the clay XML document type definition (<a href="http://struts.apache.org/dtds/shale-clay-config/1_0/" target="_blank">DTD</a>), + <code>symbols</code> are defined similar to <code>component</code> <code>attributes</code>. Symbols are + defined within a <code>symbols</code> node versus an <code>attributes</code> node. Both <code>symbols</code> + and <code>attributes</code> use the same <code>set</code> element definition but the symbols ignore the + <code>bindingType</code> attribute. The same inheritance rules apply to <code>symbols</code> as <code>attributes</code>. + Components that extend another component will inherit all symbols within the extended component. Symbols can be overridden + within the heritage of component meta-data inheritance. A symbol name can also be defined without a value attribute. + The significance of a missing value verses an empty value is defined by the symbols replacement rules. The @ character + symbol delimiter is added to the beginning of the name attribute if not specified. +</p> + +<p><blockquote><pre> +<!-- Base layout defintion --> +<component jsfid="basePage" extends="clay"> + <attributes> + <set name="clayJsfid" value="/symbols/layout.html" /> + </attributes> + <symbols> + <set name="@title" value="Default Title"/> + <set name="@leftContent" value="page3LeftPanel"/> + <set name="@headercontent" value="/symbols/header.html"/> + <set name="@logo" value="http://struts.apache.org/images/struts.gif"/> + <set name="@bodycontent" value="space"/> + <set name="@footercontent" value="footerPanel"/> + </symbols> +</component> +<component jsfid="page3" extends="basePage"> + <symbols> + <set name="@title" value="Page 3"/> + <set name="@bodyContent" value="page3Panel"/> + <set name="@logo" value="http://myfaces.apache.org/images/myfaces-logo.png"/> + <set name="@leftContent" value="page3LeftPanel"/> + </symbols> +</component> +</pre></blockquote></p> +<p>Symbols can be defined in HTML templates. The convention for using HTML to define JSF composition + is to associate a HTML element with a JSF component using a jsfid attribute. All attributes defined + within the HTML are passed on to the JSF component. Attributes that are not defined as component + attributes (the component XML configuration) are assumed to be symbols. These names are assumed a + beginning prefix @ character delimiter. +</p> +<p><blockquote><pre> +<html jsfid="page3" + bodycontent="/symbols/businessPerson.html" + allowBody="false"> + + <head><title>Mock Header</title></head> + <body>The entire document is replaced by the layout.</body> +</html> +</pre></blockquote></p> + +<p>Symbols can also be used in in conjunction with the <code>clay</code> JSP tag. The nested <code>symbol</code> + tag is used to add a symbol to the <code>clay</code> component.</p> +<p><blockquote><pre> +<clay:clay id="page3" jsfid="basePage"> + <clay:symbol name="bodycontent" value="/symbols/businessPerson.html"/> + <clay:symbol name="footercontent" value="/symbols/footer.html"/> +</clay:clay"> +</pre></blockquote></p> + +<p>What are the rules for Symbol replacement? Symbols are identified by a single prefix @ character delimiter + and doesn't require that you use a ending delimiter. This can be problematic if you have two symbols that + have the same prefix. For example @foo and @fooBar would have unpredictable results since there is not a + predefined precedence of evaluation. The solution to this problem is to assume beginning and ending delimiter + like @xfoox and @xfooBarx. Symbols are scoped for composition. This allows a customization defined by a + symbol to be defined at the root of a subtree and cascaded to all child components until overridden. + The literal representation of a Symbol is replaced with the value of the symbol. If the result of the + substitution is a zero length string, a null value is returned and the value is not apply to a property. + If a token is defined with an @ character but there is not a symbol defined, is left unchanged. +</p> + +<p>What are some common symbol applications? The original application of symbols was limited to aliasing managed + bean names within binding expressions. This idea grew into a more elaborate strategy for creating reuse. + Symbols can also be used for property aliasing. A good example of that is the component styleClass attribute. + This attribute really represents the HTML class attribute but due to reserved word conflicts in the java + programming language, it could not be named class. We use the symbol of class to alias the styleClass attribute + by defining symbol class and setting the default styleClass attribute to "@class". +</p> +<p><blockquote><pre> +<component jsfid="baseHtml" componentType="override"> + <attributes> + <!-- Convention mapping "class" attribute to "styleClass" property --> + <set name="styleClass" value="@class"/> + </attributes> + <symbols> + <set name="class"/> + </symbols> +</component> +</pre></blockquote></p> + +<p><blockquote><pre> +<label for=city>#{messages.cityLabel}</label> +<input type="text" value="[EMAIL PROTECTED]" id="city" class="inputText" > +</pre></blockquote></p> + +<p>Symbols can be used to create generic page layouts and plug in sections using symbol replacement. + This is a rich page composition feature that was borrowed from tiles. +</p> + +<p><blockquote><pre> +<html> + <head><title>@title</title></head> + <body> + <form> + <table border="1"> + <tr> + <td id="leftContent" rowspan="3"><span jsfid="clay" clayJsfid="@leftContent" allowBody="false">Left<br/>Content</span></td> + <td id="headerContent"><span jsfid="clay" clayJsfid="@headercontent" allowBody="false">Header<br/>Content</span></td> + </tr> + <tr> + <td id="bodyContent"><span jsfid="clay" clayJsfid="@bodycontent" allowBody="false">Body<br/>Content</span></td> + </tr> + <tr> + <td id="footerContent"><span jsfid="clay" clayJsfid="@footercontent" allowBody="false">Footer<br/>Content</span></td> + </tr> + </table> + </form> + </body> +</html> +</pre></blockquote></p> + +<p>Another form of reuse allows components to morph into other component. For example, + a outputText component can be altered into a inputText component. +</p> +<p><blockquote><pre> +<component jsfid="outCity" extends="outputText"> + <attributes> + <set name="value" value="[EMAIL PROTECTED]" /> + </attributes> +</component> + +<component jsfid="inputCity" extends="outCity" componentType="javax.faces.HtmlInputText"/> +</pre></blockquote></p> - </subsection> +</subsection> </section> --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]