tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jkuhn...@apache.org
Subject svn commit: r418665 [4/6] - in /tapestry/tapestry4/trunk: src/documentation/content/xdocs/ src/documentation/content/xdocs/QuickStart/ src/documentation/content/xdocs/UsersGuide/ src/documentation/content/xdocs/examples/ src/site/ src/site/resources/im...
Date Mon, 03 Jul 2006 00:17:31 GMT
Added: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/properties.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/properties.xml?rev=418665&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/properties.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/properties.xml Sun Jul  2 17:17:29 2006
@@ -0,0 +1,539 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- 
+   Copyright 2004, 2005 The Apache Software Foundation
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+<document>
+<properties>
+<title>Tapestry Object Properties</title>
+</properties>
+<body>
+<p>
+When using Tapestry, an important aspect of your work is to leverage the properties exposed
+by the various objects within Tapestry. A page has properties (inherited from base classes
+such as <a href="../tapestry/apidocs/org/apache/tapestry/AbstractComponent.html">AbstractComponent</a> and <a href="../tapestry/apidocs/org/apache/tapestry/html/BasePage.html">BasePage</a>) and contains components and other objects
+with more properties. Pages are connected to an engine, which exports its own set of properties.
+This table is a quick guide to the most common objects and their properties.	
+</p>
+
+<table>
+			<tr>
+				<th>Property name</th>
+				<th>Defining class</th>
+				<th>Property type</th>
+				<th>Description</th>
+			</tr>	
+			
+			
+<tr>
+	<td>assets</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>
+</td>
+	<td>Map of <a href="../tapestry/apidocs/org/apache/tapestry/IAsset.html">IAsset</a>
+</td>
+	<td>
+	Localized assets as defined in the component's specification.	
+	</td>
+</tr>			
+
+
+
+<tr>
+	<td>beans</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>
+</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IBeanProvider.html">IBeanProvider</a>
+</td>
+	<td>Used to access beans defined using the <a href="spec.html#spec.bean">&lt;bean&gt;</a> specification element.</td>
+</tr>
+			
+			
+<tr>
+	<td>bindingNames</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>
+</td>
+	<td>Collection of String</td>
+	<td>
+	The names of all formal and informal parameter bindings for the component.
+	</td>
+</tr>
+
+<tr>
+	<td>bindings</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>
+</td>
+	<td>Map of <a href="../tapestry/apidocs/org/apache/tapestry/IBinding.html">IBinding</a>
+</td>
+	<td>
+	All bindings (for both formal and informal parameters) for this component, keyed on
+	the parameter name.
+	</td>
+</tr>		
+
+<tr>
+	<td>body</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/AbstractComponent.html">AbstractComponent</a>
+</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IRender.html">IRender</a>[]</td>
+	<td>
+	The body of the component: the text (as <a href="../tapestry/apidocs/org/apache/tapestry/IRender.html">IRender</a>) and components (which inherit from
+	<a href="../tapestry/apidocs/org/apache/tapestry/IRender.html">IRender</a>) that the component directly encloses within its container's template.
+	</td>
+</tr>
+
+<tr>
+	<td>bodyCount</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/AbstractComponent.html">AbstractComponent</a>
+</td>
+	<td>int</td>
+	<td>
+	The active number of elements in the body property array.
+	</td>
+</tr>
+
+
+<tr>
+	<td>components</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>
+</td>
+	<td>Map of <a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>
+</td>
+	<td>
+	All components contained by this component, keyed on the component id.	
+	</td>
+</tr>
+
+
+<tr>
+	<td>changeObserver</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IPage.html">IPage</a>
+</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/event/ChangeObserver.html">ChangeObserver</a>
+</td>
+	<td>An object that recieves notifications about changes to persistent page properties.</td>
+</tr>
+
+<tr>
+<td>classResolver</td>	
+<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IEngine.html">IEngine</a>
+</td>
+<td>ClassResolver</td>
+<td>
+Object responsible for locating classes and classpath resources.	
+</td>
+</tr>
+
+<tr>
+<td>componentMessagesSource</td>	
+<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IEngine.html">IEngine</a>
+</td>
+<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/engine/IComponentMessagesSource.html">IComponentMessagesSource</a>
+</td>
+<td>
+	An object that allows components to find their set of localized messages. 
+	</td>
+</tr>
+
+<tr>
+	<td>container</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>
+</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>
+</td>
+	<td>
+	The page or component which contains this component.  Pages will return null.	
+	</td>
+</tr>	
+
+
+
+<tr>
+	<td>disabled</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/form/IFormComponent.html">IFormComponent</a>
+</td>
+	<td>boolean</td>
+	<td>
+	If true, the component should be disabled (and not respond to query parameters passed up in the request).	
+	</td>
+</tr>
+
+<tr>
+	<td>displayName</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/form/IFormComponent.html">IFormComponent</a>
+</td>
+	<td>String</td>
+	<td>
+	Localized string to be displayed as a label for the form control. Most implementations leave this
+	undefined (as null).	
+	</td>
+</tr>
+
+<tr>
+	<td>engine</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IPage.html">IPage</a>
+</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IEngine.html">IEngine</a>
+</td>
+	<td>The engine to which the page is currently attached.</td>
+</tr>
+
+<tr>
+	<td>extendedId</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>
+</td>
+	<td>String</td>
+	<td>
+	An "extended" version of the idPath	 property that
+	includes the name of the page containing the component as well.
+	</td>
+</tr>
+
+<tr>
+	<td>form</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/form/IFormComponent.html">IFormComponent</a>
+</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IForm.html">IForm</a>
+</td>
+	<td>
+	The form which encloses the form control component.	
+	</td>
+</tr>
+
+<tr>
+	<td>global</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IEngine.html">IEngine</a>, <a href="../tapestry/apidocs/org/apache/tapestry/IPage.html">IPage</a>
+</td>
+	<td>Object</td>
+	<td>
+	The Global object for the application.	
+	</td>
+</tr>
+
+<tr>
+	<td>hasVisit</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/engine/AbstractEngine.html">AbstractEngine</a>
+</td>
+	<td>boolean</td>
+	<td>
+	Returns true if the Visit object has been created, false initially.	
+	</td>
+</tr>
+
+<tr>
+	<td>id</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>
+</td>
+	<td>String</td>
+	<td>
+	The id of the component, which is unique within its container. In many cases, the framework
+	may have assigned an automatically generated id. Pages do not have an id and return null.
+	</td>
+</tr>
+
+<tr>
+	<td>idPath</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>
+</td>
+	<td>String</td>
+	<td>A sequence of id's used to locate a component within a page.  A component <code>bar</code>
+		within a component <code>foo</code> within a page will have an idPath
+		of <code>foo.bar</code>. Pages return null.
+		</td>
+</tr>
+
+<tr>
+	<td>listeners</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/AbstractComponent.html">AbstractComponent</a>, <a href="../tapestry/apidocs/org/apache/tapestry/engine/AbstractEngine.html">AbstractEngine</a>
+</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/listener/ListenerMap.html">ListenerMap</a>
+</td>
+	<td>
+	Used to map listener methods as objects that implement the <a href="../tapestry/apidocs/org/apache/tapestry/IActionListener.html">IActionListener</a> interface.
+	</td>
+</tr>
+
+<tr>
+	<td>locale</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IEngine.html">IEngine</a>
+</td>
+	<td>Locale</td>
+	<td>
+	The locale for the current client; this is used when loading pages from the page pool, or
+	when instantiating new page instances.	
+	</td>
+</tr>
+
+<tr>
+	<td>locale</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IPage.html">IPage</a>
+</td>
+	<td>Locale</td>
+	<td>
+	The locale to which the page and all components within the page is localized.	
+	</td>
+</tr>
+
+
+
+
+
+<tr>
+	<td>location</td>	
+	<td>
+<em>many</em>
+</td>
+	<td>Location</td>
+	<td>
+	The location that should be used with any error messages generated about the object. This is
+	ultimately the file, line (and even column) of the template or specification file responsible
+	for defining the object (be it a component, a page, or some other kind of object).
+	</td>
+</tr>
+
+<tr>
+	<td>messages</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>
+</td>
+	<td>Messages</td>
+	<td>
+	Localized messages for the component.	
+	</td>
+</tr>
+
+<tr>
+	<td>name</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/form/IFormComponent.html">IFormComponent</a>
+</td>
+	<td>String</td>
+	<td>
+	The name, or element id, assigned to the form control by the <a href="../tapestry/apidocs/org/apache/tapestry/IForm.html">IForm</a>. This is set as the component
+	renders (but the property can then be read after the component renders).	
+	</td>
+</tr>
+
+<tr>
+	<td>namespace</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>
+</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/INamespace.html">INamespace</a>
+</td>
+	<td>The namespace containing the component. Components are always within <em>some</em>
+		namespace, whether it is the default (application) namespace, the framework namespace,
+		or a namespace for a component library.</td>
+</tr>
+
+<tr>
+	<td>outputEncoding</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/AbstractPage.html">AbstractPage</a>
+</td>
+	<td>String</td>
+	<td>
+	Output encoding for the page.	
+	</td>
+</tr>
+
+<tr>
+	<td>page</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>
+</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IPage.html">IPage</a>
+</td>
+	<td>
+	The page which ultimately contains the component.	
+	</td>
+</tr>
+
+<tr>
+	<td>propertySource</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IEngine.html">IEngine</a>
+</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/engine/IPropertySource.html">IPropertySource</a>
+</td>
+	<td>
+	Source for configuration properties.	
+	</td>
+</tr>
+
+<tr>
+	<td>pageName</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IPage.html">IPage</a>
+</td>
+	<td>String</td>
+	<td>
+	The fully qualified page name (possibly including a namespace prefix).
+	</td>
+</tr>
+
+<tr>
+	<td>pageSource</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IEngine.html">IEngine</a>
+</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/engine/IPageSource.html">IPageSource</a>
+</td>
+	<td>
+	The object used to obtain page instances.	
+	</td>
+</tr>
+
+
+<tr>
+  <td>rendering</td>
+  <td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>
+</td>
+  <td>boolean</td>
+  <td>
+    True if the component is actively rendering (inside it's <code>render()</code> method).
+  </td>
+</tr>
+
+<tr>
+	<td>requestCycle</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IPage.html">IPage</a>
+</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IRequestCycle.html">IRequestCycle</a>
+</td>
+	<td>
+	The request cycle to which the page is currently attached.
+	</td>
+</tr>
+
+<tr>
+<td>scriptSource</td>	
+<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IEngine.html">IEngine</a>
+</td>
+<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/engine/IScriptSource.html">IScriptSource</a>
+</td>
+<td>
+Object that parses and caches script specifications.	
+</td>
+</tr>
+
+
+<tr>
+	<td>specification</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>
+</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/spec/IComponentSpecification.html">IComponentSpecification</a>
+</td>
+	<td>
+	The specification which defines this component.	Often used to access
+	meta data defined in the component's specification using the
+	<a href="spec.html#spec.meta">&lt;meta&gt;</a> element.
+	</td>
+</tr>
+
+<tr>
+	<td>specification</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IEngine.html">IEngine</a>
+</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/spec/IApplicationSpecification.html">IApplicationSpecification</a>
+</td>
+	<td>
+	The specification for the application.	
+	</td>
+</tr>
+
+<tr>
+	<td>specificationSource</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IEngine.html">IEngine</a>
+</td>
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/engine/ISpecificationSource.html">ISpecificationSource</a>
+</td>
+	<td>Object responsible for reading and caching page and component specifications.</td>
+</tr>
+
+<tr>
+		<td>visit</td>
+		<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IEngine.html">IEngine</a>
+</td>
+		<td>Object</td>
+		<td>
+		Returns the Visit object for the current client, or null if the Visit object
+		has not yet been created.	
+		</td>
+</tr>
+
+<tr>
+	<td>visit</td>	
+	<td>
+<a href="../tapestry/apidocs/org/apache/tapestry/IPage.html">IPage</a>
+</td>
+	<td>Object</td>
+	<td>
+	Returns the Visit object for the current client, creating it if necessary.	
+	</td>
+</tr>
+
+
+			
+
+</table>
+
+</body>
+</document>

Propchange: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/properties.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/script.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/script.xml?rev=418665&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/script.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/script.xml Sun Jul  2 17:17:29 2006
@@ -0,0 +1,463 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- 
+    Copyright 2005 The Apache Software Foundation
+    
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+    
+    http://www.apache.org/licenses/LICENSE-2.0
+    
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+<document>
+<properties>
+<title>Script Template Specification DTDs</title>
+</properties>
+<body> 
+  
+        <p>
+            Script template specifications are the odd man out when it comes
+            to Tapestry XML files as they don't use the same DTD as the
+            <a href="spec.html">other specifications</a>.
+        </p>  
+        
+        <p>
+            Script templates are used to dynamically generate JavaScript to
+            support client-side behaviors associated with components.  Tapestry
+            is all about dynamically renderered, customized HTML, so it makes sense
+            that dynamically rendered, customize JavaScript to complement
+            that HTML should also be supported.
+        </p>        
+        
+        <p>
+            Script template files are parsed into memory as 
+            instances of <a href="../tapestry/apidocs/org/apache/tapestry/IScript.html">IScript</a>. These script template <em>objects</em>
+            may be executed to generate the JavaScript.            
+        </p>        
+        
+        <p>
+            Many different script template objects may be executed during the course
+            of rendering a page; all the JavaScript from all the executions are
+            organized into two JavaScript blocks in the output page:
+            the <em>main body</em> at the top of the page
+            (just inside the HTML &lt;body&gt; tag), and
+            an <em>initialization block</em> at the bottom of the page,
+            (just before the HTML &lt;/body&gt; tag). 
+        </p>
+        
+        <p>
+            Executing a script template requires access to an <a href="../tapestry/apidocs/org/apache/tapestry/IScriptProcessor.html">IScriptProcessor</a> instance;
+            this is usually provided by the <a href="site:Body">Body</a> component.  The script processor
+            is responsible for managing the buffers of JavaScript, and assists
+            with generating unique ids for client-side variables and functions.            
+        </p>
+    
+        <p>
+            A script template works with <em>symbols</em>, a set of key/value pairs
+            (implements as a Map). The script operates upon the input symbols and
+            generates new output symbols along the way, while generating
+            JavaScript.  In some cases, the output symbols may be used
+            by a component when rendering HTML.
+        </p>
+
+        <p>
+            Many of the elements in a script template have a body of parsable character
+            data.  In the body of an element, you may reference symbols using
+            the Ant-like ${...} syntax.  I.e. <code>${name}</code>.  In fact, the
+         string inside the curly braces is an <a href="http://www.ognl.org">OGNL</a> expression, so you may create more
+         complex expressions, such as <code>${field.form.name}</code>.
+        </p>        
+    
+<section name="DOCTYPE">
+    
+    
+    <p>
+        The DOCTYPE for a script template specification is:
+    </p>    
+    
+<source xml:space="preserve">
+&lt;!DOCTYPE script PUBLIC
+  "-//Apache Software Foundation//Tapestry Script Specification 3.0//EN"
+  "http://jakarta.apache.org/tapestry/dtd/Script_3_0.dtd"&gt;</source>    
+</section>  <!-- DOCTYPE -->
+
+        <section name="&lt;body&gt; element">
+            
+            
+            <p>
+                Appears in: <a href="#script.script">&lt;script&gt;</a>
+            </p>            
+            
+            <p>            Allows a mix of text and control elements.  This text is added to
+            the large scripting block just inside the HTML &lt;body&gt; tag.            
+            </p>
+            
+            <p>&lt;body&gt; elements:</p>
+            
+            <source xml:space="preserve">(<em>text</em> | <a href="#script.foreach">&lt;foreach&gt;</a> | <a href="#script.if">&lt;if&gt;</a> | <a href="#script.if-not">&lt;if-not&gt;</a> | <a href="#script.unique">&lt;unique&gt;</a>)*</source>            
+        </section>
+        
+        <section name="&lt;foreach&gt; element">
+            
+            
+            <p>
+                Appears in: <em>many</em>
+            </p>
+            
+            <p>
+                Iterates over a list of items; this is modeled after the
+                For component.  No iteration occurs if the value
+                from the expression is null.
+            </p>
+            
+            <table>
+                
+                <tr>
+                    <th>Name</th>
+                    <th>Type</th>
+                    <th>Required ?</th>
+                    <th>Default Value</th>
+                    <th>Description</th>
+                </tr>
+                
+                <tr>
+<td>key</td> <td>string</td> <td>no</td> <td/>
+                    <td>
+                        Defines the symbol into which each succesive value is stored.
+                    </td>
+                </tr>       
+                
+                <tr>
+                    <td>index</td> <td>string</td> <td>no</td> <td/>
+                    <td>
+                        Defines the symbol into which the index of the value of the current iteration is stored.
+                    </td>
+                </tr>     
+                
+                <tr>
+                    <td>expression</td>
+                    <td>string</td> <td>yes</td> <td/>
+                    <td>
+                        The source of values, as an OGNL expression rooted in the symbols Map.
+                    </td>
+                </tr>
+            </table>
+            
+            <p>&lt;foreach&gt; elements:</p>
+            
+            <source xml:space="preserve">(<em>text</em> | <a href="#script.foreach">&lt;foreach&gt;</a> | <a href="#script.if">&lt;if&gt;</a> | <a href="#script.if-not">&lt;if-not&gt;</a> | <a href="#script.unique">&lt;unique&gt;</a>)*</source>                  
+        </section>
+
+        
+        <section name="&lt;if&gt; element">
+            
+            
+            <p>
+                Appears in: <em>many</em>
+            </p>            
+            
+            <p>
+                Creates a conditional portion of the script; The body of the element 
+                is only included if the expression evaulates to true.  
+            </p>
+            
+            <table>
+                
+                <tr>
+                    <th>Name</th>
+                    <th>Type</th>
+                    <th>Required ?</th>
+                    <th>Default Value</th>
+                    <th>Description</th>
+                </tr>
+                
+                <tr>
+                    <td>expression</td> <td>string</td> <td>yes</td> <td/>
+                    <td>
+                        The <a href="http://www.ognl.org">OGNL</a> expression to evaluate.
+                    </td>
+                </tr>
+                
+                
+            </table>
+            
+            <p>
+                &lt;if&gt; Elements
+            </p>
+            
+            <source xml:space="preserve">(<em>text</em> | <a href="#script.foreach">&lt;foreach&gt;</a> | <a href="#script.if">&lt;if&gt;</a> | <a href="#script.if-not">&lt;if-not&gt;</a> | <a href="#script.unique">&lt;unique&gt;</a>)*</source>                            
+            
+        </section>
+        
+        <section name="&lt;if-not&gt; element">
+            
+            
+            <p>
+                Identical to the <a href="#script.if">&lt;if&gt;</a> element, except that the body
+                is only included in the output if the expression
+                evaluates to <strong>false</strong>.
+            </p>
+        </section>            
+        
+
+        
+        <section name="&lt;include-script&gt; element">
+            
+            
+            <p>
+                Inserts a reference to a static JavaScript file stored on the
+                classpath. A particular file will only be included once per rendering
+                of a page.
+            </p>      
+            
+            <p>
+                For best performance, as much logic as possible should be shifted into
+                static JavaScript library files that are included via this element.
+                The dynamic portion of the JavaScript should really be initialization
+                of code provided by such a static JavaScript library. This optimizes
+                that amount of data that must be sent to the client web browser, as
+                it will be able to cache the content of static library files.
+            </p>
+            
+            <p>
+                Appears in: <a href="#script.script">&lt;script&gt;</a>
+            </p>      
+            
+            <table>
+                
+                <tr>
+                    <th>Name</th>
+                    <th>Type</th>
+                    <th>Required ?</th>
+                    <th>Default Value</th>
+                    <th>Description</th>
+                </tr>
+                
+                <tr>
+                    <td>resource-path</td>
+                    <td>string</td>
+                    <td>yes</td>
+                    <td/>
+                    <td>The path to the script within the classpath.</td>
+                </tr>          
+                </table>
+                
+        </section>
+                <section name="&lt;initialization&gt; element">
+            
+            
+            <p>
+                Appears in: <a href="#script.script">&lt;script&gt;</a>
+            </p>            
+            
+            <p>            Allows a mix of text and control elements.  This text is added to
+                the large scripting block just inside the HTML &lt;/body&gt; tag. It therefore
+                can refrence HTML objects within the page.            
+            </p>
+            
+            <p>&lt;initialization&gt; elements:</p>
+            
+            <source xml:space="preserve">(<em>text</em> | <a href="#script.foreach">&lt;foreach&gt;</a> | <a href="#script.if">&lt;if&gt;</a> | <a href="#script.if-not">&lt;if-not&gt;</a> | <a href="#script.unique">&lt;unique&gt;</a>)*</source>            
+        </section>
+
+        <section name="&lt;input-symbol&gt; element">
+            
+            
+            <p>
+                Appears in: <a href="#script.script">&lt;script&gt;</a>
+            </p>
+            
+            <p>
+                Defines an input symbol used by the script.  Defining input symbols
+                is optional; it merely enforces that symbols be
+                of a particular type, or enforces that a non-null value
+                be provided.  This is handy as <em>defensive programming</em>. 
+            </p>
+            
+              
+            <table>
+                
+                <tr>
+                    <th>Name</th>
+                    <th>Type</th>
+                    <th>Required ?</th>
+                    <th>Default Value</th>
+                    <th>Description</th>
+                </tr>        
+            
+                <tr>
+                    <td>key</td>
+                    <td>string</td>
+                    <td>yes</td>
+                    <td/>
+                    <td>The name of the symbol to check.</td>
+                </tr>
+                
+                <tr>
+                    <td>class</td>
+                    <td>string</td>
+                    <td>no</td>
+                    <td/>
+                    <td>
+                        If provided, then the actual value
+                        must be assignable to the given type (which may
+                        be a Java class or interface name).
+                    </td>
+                </tr>
+                
+                <tr>
+                    <td>
+                        required
+                    </td>
+                    <td>boolean</td>
+                    <td>no</td>
+                    <td>no</td>
+                    <td>
+                        If "yes", then a non-null value must be provided.
+                    </td>
+                </tr>
+            </table>
+            
+        </section>
+
+        <section name="&lt;let&gt; element">
+            
+            
+            <p>
+                Appears in: <a href="#script.script">&lt;script&gt;</a>
+            </p>
+            
+            <p>
+                Defines a new symbol in terms of a string
+                (usually with embedded expressions).                
+            </p>
+            
+            <p>
+                When a string is marked as unique, it is passed through a page-wide
+                filter; if the name conflicts with a previous unique string,
+                then a numeric suffix is appended to the string to ensure
+                its uniqueness. This is most useful when defining
+                JavaScript client-side variables and functions, to ensure
+                there are no conflicts between different script templates, or
+                successive executions of the same script template.
+            </p>
+            
+            <table>
+                
+                <tr>
+                    <th>Name</th>
+                    <th>Type</th>
+                    <th>Required ?</th>
+                    <th>Default Value</th>
+                    <th>Description</th>
+                </tr>      
+                
+                <tr>
+                    <td>key</td> <td>string</td> <td>yes</td> <td/>
+                    <td>The name of the new symbol to create.</td>
+                </tr>            
+                
+                <tr>
+                    <td>unique</td> <td>boolean</td> <td>no</td> <td>no</td>
+                    <td>
+                        If yes, then the string is made unique.
+                    </td>
+                </tr>
+            
+</table>
+
+            <p>
+                &lt;let&gt; Elements
+            </p>
+            
+            <source xml:space="preserve">(<em>text</em> | <a href="#script.foreach">&lt;foreach&gt;</a> | <a href="#script.if">&lt;if&gt;</a> | <a href="#script.if-not">&lt;if-not&gt;</a> | <a href="#script.unique">&lt;unique&gt;</a>)*</source>
+
+            
+        </section>
+
+        <section name="&lt;script&gt; element">
+            
+            
+            <p>
+                <em>root element</em>
+            </p>
+            
+            <p>
+                The &lt;script&gt; element is the root element of the document.
+                It contains no attributes.
+            </p>            
+            
+            <p>
+                &lt;script&gt; Elements
+            </p>          
+            <source xml:space="preserve">
+(<a href="#script.include-script">&lt;include-script&gt;</a>*, <a href="#script.input-symbol">&lt;input-symbol&gt;</a>*, (<a href="#script.let">&lt;let&gt;</a> | <a href="#script.set">&lt;set&gt;</a>)*, <a href="#script.body">&lt;body&gt;</a>?, <a href="#script.initialization">&lt;initialization&gt;</a>?)                  
+            </source>              
+            
+        </section> <!-- script -->
+    
+    
+        <section name="&lt;set&gt; element">
+                    
+            
+            <p>
+                Appears in: <em>many</em>
+            </p>            
+            
+            <p>
+                Creates a new symbol, or overwrites an existing symbol, in terms
+                of an <a href="http://www.ognl.org">OGNL</a> expression.
+            </p>
+            
+            <table>
+                
+                <tr>
+                    <th>Name</th>
+                    <th>Type</th>
+                    <th>Required ?</th>
+                    <th>Default Value</th>
+                    <th>Description</th>
+                </tr>
+                
+                <tr>
+                    <td>key</td> <td>string</td> <td>yes</td> <td/>
+                    <td>The key for the input symbol to be created (or overwritten).</td>
+                </tr>
+                
+                <tr>
+                    <td>expression</td> <td>string</td>
+                    <td>yes</td>
+                    <td/>
+                    <td>The <a href="http://www.ognl.org">OGNL</a> expression to evaluate and assign to the
+                    input symbol.</td>
+                </tr>
+           </table>
+            
+        </section> <!-- script.set -->    
+        
+        <section name="&lt;unique&gt; element">
+            
+            
+            <p>
+                Appears in: <em>many</em>
+            </p>            
+            
+            <p>
+                Defines a block of text that is only rendered once per page.
+                This is appropriate to certain kinds of initialization code
+                that should not be duplicated, even if the same script
+                template is executed multiple times.
+            </p>
+            
+<p>&lt;script&gt; elements:</p>
+
+<source xml:space="preserve">(<em>text</em> | <a href="#script.foreach">&lt;foreach&gt;</a> | <a href="#script.if">&lt;if&gt;</a> | <a href="#script.if-not">&lt;if-not&gt;</a> | <a href="#script.unique">&lt;unique&gt;</a>)*</source>            
+            
+        </section>        
+    </body>
+</document>

Propchange: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/script.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/spec.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/spec.xml?rev=418665&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/spec.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/spec.xml Sun Jul  2 17:17:29 2006
@@ -0,0 +1,1517 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- 
+   Copyright 2004, 2005 The Apache Software Foundation
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+<document>
+<properties>
+<title>Tapestry Specification DTDs</title>
+</properties>
+<body>
+
+<p>
+This document describes the four main types of specifications
+used in Tapestry.  In all four cases, the same DOCTYPE is used:
+</p>
+ 
+<source xml:space="preserve">
+
+&lt;!DOCTYPE <em>root element</em> PUBLIC
+  "-//Apache Software Foundation//Tapestry Specification 4.0//EN" 
+  "http://jakarta.apache.org/tapestry/dtd/Tapestry_4_0.dtd"&gt;
+</source>
+ 
+<p>
+The <em>root element</em> is different for each of the four types of specification files:
+</p>
+
+<table>
+
+<tr>
+	<th>Type</th>
+	<th>File Extension</th>
+	<th>Root Element</th>
+</tr>
+
+<tr>
+	<td>Application</td>
+	<td>application</td>
+	<td>
+<a href="spec.html#spec.application">&lt;application&gt;</a>
+</td>
+</tr>
+
+<tr>
+	<td>Page</td>
+	<td>page</td>
+	<td>
+<a href="spec.html#spec.page-specification">&lt;page-specification&gt;</a>
+</td>
+</tr>
+
+<tr>
+	<td>Component</td>
+	<td>jwc</td>
+	<td>
+<a href="spec.html#spec.component-specification">&lt;component-specification&gt;</a>
+</td>
+</tr>
+
+<tr>
+	<td>Library</td>
+	<td>library</td>
+	<td>
+<a href="spec.html#spec.library-specification">&lt;library-specification&gt;</a>
+</td>
+</tr>
+
+
+</table>
+
+<p>
+<strong>Note:</strong>
+<br/>
+A fifth type of specification, the script template specification, is 
+<a href="script.html">described seperately</a>.  In addition, in Tapestry 4.0, 
+a significant 
+part of an application's behavior is defined by its <a href="http://jakarta.apache.org/hivemind/">HiveMind</a> module deployment descriptor.
+</p>
+
+<section name="Changes between releases 3.0 and 4.0">
+   
+
+<p>
+The specifications evolve over time, with each release providing an updated DTD allowing access to new features.
+Tapestry 4.0 supports the Tapestry 3.0 DTD (just be sure to use the matching public ID), and in most cases
+existing applications coded against release 3.0 will run unchanged under release 4.0 (though
+it is expected that there will be some runtime warnings).
+</p>
+
+<p> The following features of the release 3.0 DTD are changed for release 4.0: </p>
+
+<ul>
+  <li>The &lt;service&gt; element (inside <a href="spec.html#spec.application">&lt;application&gt;</a> or <a href="spec.html#spec.library-specification">&lt;library-specification&gt;</a>) is no longer supported in 
+    release 4.0. 3.0 DTD specifications that use &lt;service&gt; will generate a warning. Use the 
+    <a href="../tapestry/hivedocs/service/tapestry.services.ApplicationServices.html">tapestry.services.ApplicationServices</a> configuration point instead.</li>
+  <li>
+    In the 3.0 DTD, the <a href="spec.html#spec.binding">&lt;binding&gt;</a> element was for specifying OGNL expressions only, and had an
+    expression attribute.  In the 4.0 DTD, it is used for setting all types of attributes, and has
+    a value attribute.  The value is a <a href="bindings.html">binding reference</a>, which
+    uses a prefix to determine which type of binding is to be used.
+  </li>
+  <li>The &lt;static-binding&gt; and &lt;message-binding&gt; elements have been removed, replaced with
+    the <a href="spec.html#spec.binding">&lt;binding&gt;</a> element and the ognl: and message: prefixes, respectively.</li>
+  <li>The &lt;property&gt; element (in 3.0) has been renamed to <a href="spec.html#spec.meta">&lt;meta&gt;</a>.</li>
+  <li>The &lt;property-specification&gt; element (in 3.0) has been renamed to <a href="spec.html#spec.property">&lt;property&gt;</a>. The type
+    attribute has been dropped. The persistent attribute has been renamed to persist, and is a string
+    (allowing a variety of persistence strategies to be applied).</li>
+  <li>The <a href="spec.html#spec.inject">&lt;inject&gt;</a> element has been added.</li>
+  <li>The <a href="spec.html#spec.parameter">&lt;parameter&gt;</a> element has been simplified; the type and direction attributes have been dropped. The
+    default-value attribute is now a <em>
+<a href="bindings.html">binding reference</a>
+</em>, as with the <a href="spec.html#spec.binding">&lt;binding&gt;</a> element's value attribute.</li>
+  <li>The <a href="spec.html#spec.property">&lt;property&gt;</a> element's initial-value attribute (or enclosed character data) is now a <a href="bindings.html">binding reference</a>. In release 3.0
+    it was always an OGNL expression, but is now a <a href="bindings.html">binding reference</a>.</li>
+  <li>The &lt;context-asset&gt;, &lt;private-asset&gt; and &lt;external-asset&gt; elements
+    have been consolidated into the new <a href="spec.html#spec.asset">&lt;asset&gt;</a> element, and a
+    prefixing system has been introduced.</li>
+  <li>The &lt;set-property&gt; and &lt;set-message-property&gt; elements
+    have been consolidated into &lt;set&gt;, which now uses a (wait for it)
+    <a href="bindings.html">binding reference</a>.</li>
+  <li>The 4.0 DTD is more liberal about the order in which elements may be specified than the 3.0 DTD.</li>
+  <li>Added the property attribute to the <a href="spec.html#spec.component">&lt;component&gt;</a> and <a href="spec.html#spec.bean">&lt;bean&gt;</a> elements.</li>
+  <li>Removed the type attribute from the <a href="spec.html#spec.configure">&lt;configure&gt;</a> element.</li>
+  <li>Added many more options for <a href="#spec.boolean-types">boolean attributes</a>.</li>
+  <li>Added the aliases and cache attributes to the <a href="spec.html#spec.parameter">&lt;parameter&gt;</a> element.</li>
+  <li>Added the deprecated attribute to <a href="spec.html#spec.component-specification">&lt;component-specification&gt;</a> and <a href="spec.html#spec.parameter">&lt;parameter&gt;</a>.</li>
+  <li>Renamed property-name attribute to property (in several places)</li>
+  <li>Removed the &lt;listener-binding&gt; element</li>
+</ul>
+
+<p>
+More detailed notes on <a href="upgrade.html">upgrading from Tapestry 3.0 to Tapestry 4.0</a> are available.
+</p>
+
+</section>  <!-- changes -->
+
+<section name="Property Injection">
+  
+  
+<p>
+Several of the specification elements are concerned with <a href="injection.html">property injection</a>.  For <a href="spec.html#spec.inject">&lt;inject&gt;</a>,
+the entire element exists to describe a property injection; in others (<a href="spec.html#spec.component">&lt;component&gt;</a>, <a href="spec.html#spec.bean">&lt;bean&gt;</a> and <a href="spec.html#spec.asset">&lt;asset&gt;</a>),
+the injection is just one piece of the behavior defined using the element.
+</p>
+
+<p>
+In all of these cases, Tapestry will create a <em>new property</em> at runtime. That is, it will create the accessor method
+(or methods), the instance variables, and any necessary setup or cleanup code automatically.  As with 
+<a href="state.html#state.page-properties">persistent page properties</a>, you should at most declare <em>abstract</em>
+accessor methods.
+</p>
+  
+</section>  <!-- spec.property-injection -->
+
+<section name="Boolean type values">
+  
+  
+<p>
+Several attributes are type boolean. Tapestry supports a number of common (and one humorous) values
+for booleans.  Values considered true:  
+</p>  
+
+<ul>
+  <li>true</li>
+  <li>yes</li>
+  <li>on</li>
+  <li>1</li>
+  <li>t</li>
+  <li>y</li>
+  <li>aye</li>
+</ul>
+
+<p>
+Values considered false:
+</p>
+
+<ul>
+  <li>false</li>
+  <li>no</li>
+  <li>off</li>
+  <li>0</li>
+  <li>f</li>
+  <li>n</li>
+  <li>nay</li>
+</ul>
+
+</section>
+
+<section name="&lt;application&gt; element">
+	
+	
+
+<p>
+<em>root element</em>
+</p>
+
+<p>
+The application specification defines the pages and components specific to a single Tapestry application.
+It also defines any libraries that are used within the application.
+</p>
+
+<table>
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>name</td>
+	<td>string</td>
+	<td>no</td>
+	<td/>
+	<td>User presentable name of application.</td>
+</tr>
+<tr>
+	<td>engine-class</td>
+	<td>string</td>
+	<td>no</td>
+	<td/>
+	<td>Name of an implementation of <a href="../tapestry/apidocs/org/apache/tapestry/IEngine.html">IEngine</a> to instantiate.  Defaults
+	to <a href="../tapestry/apidocs/org/apache/tapestry/engine/BaseEngine.html">BaseEngine</a> if not specified.</td>
+</tr>
+
+</table>
+
+<p>&lt;application&gt; Elements:</p>
+<source xml:space="preserve">
+  <a href="spec.html#spec.description">&lt;description&gt;</a> ?,
+  (<a href="spec.html#spec.meta">&lt;meta&gt;</a> | <a href="spec.html#spec.page">&lt;page&gt;</a> | <a href="spec.html#spec.component-type">&lt;component-type&gt;</a> |  <a href="spec.html#spec.library">&lt;library&gt;</a> | <a href="spec.html#spec.extension">&lt;extension&gt;</a>) *
+</source>
+
+</section>  <!-- spec.application -->
+
+
+<section name="&lt;asset&gt; element">
+	
+
+<p>
+Specifies the location of an asset, a file (typically an image or stylesheet) that may be 
+exposed to the client web browser.
+</p>
+
+<p>
+Assets may be stored in the web application (that is, within or beneath the web application root
+context folder), on the classpath (often the case for components packaged in a reusable library)
+or at an arbitrary URL.
+</p>
+
+<p>
+The path to a resource may be absolute (beginning with a leading slash), or relative (no leading slash).
+At this time, other common path sequences (".", "..", etc.) are not supported.
+</p>
+
+<table>
+  <tr>
+    <th>Prefix</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>context:</td>
+    <td>The asset is stored in the web application context.  Relative paths are compouted
+      from the web application root context folder, not the specification file.
+    </td>
+  </tr>
+  <tr>
+    <td>classpath:</td>
+    <td>
+      The asset is a file on the classpath.  Relative paths are computed from the specification file.
+    </td>
+  </tr>
+</table>
+
+<p>
+Context and classpath assets will automatically be localized.  Thus an asset with path "/images/Logo.gif" may be localized
+to "/images/Logo_fr.gif" if the active locale is French (and such a file exists).
+</p>
+
+<p>
+Unrecognized prefixes are considered to be the scheme portion of a URL.  Such paths are passed through unchanged,
+and not localized.
+</p>
+
+<table>
+
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>name</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>The name of the asset, which must be a valid Java identifier.</td>
+</tr>
+<tr>
+	<td>path</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>The relative or absolute path to the asset.
+	</td>
+</tr>
+
+<tr>
+  <td>property</td>
+  <td>string</td>
+  <td>no</td>
+  <td/>
+  <td>
+    The name of a property into which the asset shoud be `ed.
+  </td>
+</tr>
+
+</table>
+
+
+</section> <!-- spec.asset -->
+
+
+<section name="&lt;bean&gt; element">
+	
+	
+<p>
+Appears in:
+<a href="spec.html#spec.component-specification">&lt;component-specification&gt;</a> and <a href="spec.html#spec.page-specification">&lt;page-specification&gt;</a>
+</p>	
+	
+<p>
+A &lt;bean&gt; is used to add behaviors to a page or component via aggregation.
+Each &lt;bean&gt; defines a named JavaBean that is instantiated on demand.
+Such managed beans are accessed through the OGNL expression beans.<em>name</em>
+or via the bean: <a href="bindings.html">binding reference</a>.
+</p>
+
+<p>
+  Beans are only instantiated on demand, typically by using a bean: <a href="bindings.html">binding reference</a>.
+Once a bean is instantiated and initialized, it will be retained by the page or component
+for some period of time, specified by the bean's lifecycle.
+</p>
+
+<dl>
+ <dt>none</dt>
+  <dd>
+			The bean is not retained, a new bean will be created on each access.
+  </dd>
+
+  <dt>page</dt>
+  <dd>
+			The bean is retained for the lifecycle of the page itself.
+  </dd>
+	
+  <dt>render</dt>
+  <dd>
+			The bean is retained until the current render operation completes.
+			This will also discard the bean when a page or form finishes rewinding.
+      This is the default lifecycle.
+  </dd>
+		
+  <dt>request</dt>
+  <dd>The bean is retained until the end of the current request.
+	</dd>
+
+</dl>
+
+<p>
+Caution should be taken when using lifeycle page.  A bean is associated
+with a particular instance of a page within a particular JVM.  Consecutive requests
+may be processed using different instances of the page, possibly in different JVMs (if the application
+is operating in a clustered environment).  No state particular to a single client session should
+be stored in a page.
+</p>
+
+<p>
+Beans must be public classes with a default (no arguments) constructor. Properties of the bean
+may be configured nested <a href="spec.html#spec.set">&lt;set&gt;</a> elements.
+</p>
+
+<table>
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>name</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>The name of the bean, which must be a valid Java identifier.</td>
+</tr>
+<tr>
+	<td>class</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>The name of the class to instantiate.  May optionally include <em>lightweight initialization</em> (see below).</td>
+</tr>
+<tr>
+	<td>lifecycle</td>
+	<td>none|page|render|request</td>
+	<td>no</td>
+	<td>request</td>
+	<td>As described above; duration that bean is retained once instantiated.</td>
+</tr>
+<tr>
+  <td>property</td>
+  <td>string</td>
+  <td>no</td>
+  <td/>
+  <td>
+   If a property name is specified, then the name property will be
+   injected into the component; accessing the property will return the
+   bean. This makes it easier to access beans from Java code. 
+  </td>
+</tr>
+
+
+</table>
+
+
+<p>
+<em>Lightweight intialization:</em>  A concept borrowed from HiveMind where simple properties of the
+bean can be configured in-line, as a comma-separated list of property=value pairs. The values are converted to appropriate types
+automatically.  For boolean values, the value may be omitted.  Example:
+</p>
+
+<source xml:space="preserve">
+  &lt;bean name="validator" class="org.apache.tapestry.valid.StringValidator,required,minimumLength=10"/&gt;
+</source>
+
+
+<p>&lt;bean&gt; Elements:</p>
+<source xml:space="preserve">
+  <a href="spec.html#spec.description">&lt;description&gt;</a> ?, (<a href="spec.html#spec.meta">&lt;meta&gt;</a> | <a href="spec.html#spec.set">&lt;set&gt;</a>) *
+</source>
+
+
+</section> <!-- spec.bean -->	
+ 
+<section name="&lt;binding&gt; element">
+	
+
+<p>
+Appears in: <a href="spec.html#spec.component">&lt;component&gt;</a>
+</p>
+
+<p>
+Binds a parameter of an embedded component to particular value.
+</p>
+
+<p>
+In an instantiated component, bindings can be accessed with
+the OGNL expression bindings.<em>name</em>.
+</p>
+
+<p>
+If the value attribute is omitted, then
+the body of the element must contain the value.  This is useful when the
+value is long, or contains problematic characters (such as a mix
+of single and double quotes).
+</p>
+
+
+<table>
+
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>name</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>The name of the parameter to bind.</td>
+</tr>
+<tr>
+	<td>value</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>The value to bind to the parameter.</td>
+</tr>
+
+</table>
+
+<p>
+The value may be literal string, or a <a href="bindings.html">binding reference</a>.  Binding references are divided into a
+<em>prefix</em> and a <em>locator</em>.  The prefix identifies how the locator is 
+interpreted.
+</p>
+
+<table>
+  <tr>
+    <th>Prefix</th>
+    <th>Locator Description</th>
+  </tr>
+  
+  <tr>
+    <td>ognl:</td>
+    <td>The locator is an <a href="http://www.ognl.org">OGNL</a> expression.  The expression is evaluated with the page or component as its root object (this is the page
+      or component defined by the specification).  This is the only type of expression that may be writeable. </td>
+  </tr>
+  
+  <tr>
+    <td>message:</td>
+    <td>The locator is a key used to obtain a localized message for the page or component.</td>
+  </tr>
+</table>
+
+<p>
+<strong>Note:</strong>
+<br/>
+  More prefixes are forthcoming in release 4.0, and it is is also possible to define your own prefixes.
+</p>
+
+
+</section> <!-- spec.binding -->
+
+<section name="&lt;component&gt; element">
+	
+	
+<p>
+Appears in: <a href="spec.html#spec.component-specification">&lt;component-specification&gt;</a> and <a href="spec.html#spec.page-specification">&lt;page-specification&gt;</a>
+</p>
+
+<p>
+Defines an embedded component within a container (a page or another component).
+</p>
+
+<p>
+In an instantiated component, embedded components can be accessed with
+the OGNL expression components.<em>id</em>.
+</p>
+
+
+<table>
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>id</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>Identifier for the component here and in the component's template.  Must be
+	a valid Java identifier.</td>
+</tr>
+<tr>
+	<td>type</td>
+	<td>string</td>
+	<td>no</td>
+	<td/>
+	<td>A component type to instantiate.</td>
+</tr>
+<tr>
+	<td>copy-of</td>
+	<td>string</td>
+	<td>no</td>
+	<td/>
+	<td>The name of a previously defined component.  The type and bindings of that
+	component will be copied to this component.
+	</td>
+</tr>
+
+<tr>
+	<td>inherit-informal-parameters</td>	
+	<td>boolean</td>
+	<td>no</td>
+	<td>false</td>
+	<td>
+	If true, then any informal parameters of the containing
+	component will be copied into this component.
+	</td>
+</tr>
+
+<tr>
+  <td>property</td>
+  <td>string</td>
+  <td>no</td>
+  <td/>
+  <td>
+  If a name is provided, then a read-only property will be created with the given name that will
+  allow access to the component.
+  </td>
+</tr>
+
+</table>
+
+<p>
+Either type or copy-of must be specified.
+</p>
+
+<p>
+A component type is either a simple name or a qualified name.  A simple name is the name of
+an component either provided by the framework, or
+provided by the application (if the page or component is defined in an application),
+or provided by the library (if the page or component is defined in a library).
+</p>
+
+<p>
+A qualified name is a library id, a colon, and a simple name of a component provided
+by the named library (for example, contrib:Palette).  
+Library ids are defined by a <a href="spec.html#spec.library">&lt;library&gt;</a> element in the
+containing library or application.
+</p>
+	
+<p>&lt;component&gt; Elements</p>
+<source xml:space="preserve">
+  (<a href="spec.html#spec.meta">&lt;meta&gt;</a> | <a href="spec.html#spec.binding">&lt;binding&gt;</a>) *
+</source>
+
+	
+</section> <!-- spec.component -->
+
+
+
+
+<section name="&lt;component-specification&gt; element">
+	
+
+<p>
+<em>root element</em>
+</p>
+
+<p>
+Defines a new component, in terms of its API (<a href="spec.html#spec.parameter">&lt;parameter&gt;</a>s), embedded components, beans and
+assets.
+</p>
+
+<p>
+The structure of a &lt;component-specification&gt;
+is very similar to a <a href="spec.html#spec.page-specification">&lt;page-specification&gt;</a> except components have additional attributes
+and elements related to parameters.
+</p>
+
+
+
+<table>
+
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>class</td>
+	<td>string</td>
+	<td>no</td>
+	<td/>
+	<td>The Java class to instantiate, which must implement the
+	interface <a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a>.  If not specified, <a href="../tapestry/apidocs/org/apache/tapestry/BaseComponent.html">BaseComponent</a> is used
+  (though Tapestry 4.0 will do a <a href="page-class.html">lookup of the class based on component type</a>)
+	</td>
+</tr>
+<tr>
+	<td>allow-body</td>
+	<td>boolean</td>
+	<td>no</td>
+	<td>true</td>
+	<td>
+	<p>If true, then any body for this component, from its
+	containing page or component's template, is retained and may be 
+	rendered using a <a href="site:RenderBody">RenderBody</a> component.
+	</p>
+	<p>If false, then any body for this component is
+	discarded, and it is not allowed for the body to contain
+  components.
+	</p>	
+	</td>
+</tr>
+<tr>
+	<td>allow-informal-parameters</td>
+	<td>boolean</td>
+	<td>no</td>
+	<td>true</td>
+	<td>
+	<p>If true, then any informal parameters
+	(bindings that don't match a formal parameter) specified here, or in
+	the component's tag within its container's template, are retained.
+	Typically, they are converted into additional HTML attributes.
+	</p>
+	<p>If false, then informal parameters
+	are not allowed in the specification, and discarded if in the template.
+	</p>
+	</td>
+</tr>
+
+<tr>
+  <td>deprecated</td>
+  <td>boolean</td>
+  <td>no</td>
+  <td>false</td>
+  <td>
+    If true, then using the component will generate a warning. This is used
+    to mark obsolete components.  The component's documentation should indicate
+    what component replaces the deprecated component.
+  </td>
+</tr>
+
+</table>
+
+<p>&lt;component-specification&gt; Elements</p>
+<source xml:space="preserve">
+  <a href="spec.html#spec.description">&lt;description&gt;</a> ?, 
+  (<a href="spec.html#spec.parameter">&lt;parameter&gt;</a> | <a href="spec.html#spec.reserved-parameter">&lt;reserved-parameter&gt;</a> | <a href="spec.html#spec.meta">&lt;meta&gt;</a> | <a href="spec.html#spec.bean">&lt;bean&gt;</a> | 
+   <a href="spec.html#spec.component">&lt;component&gt;</a> | <a href="spec.html#spec.asset">&lt;asset&gt;</a> | <a href="spec.html#spec.property">&lt;property&gt;</a> | <a href="spec.html#spec.inject">&lt;inject&gt;</a>)*
+</source>
+
+
+</section> <!-- spec.component-specification -->
+
+
+<section name="&lt;component-type&gt; element">
+	
+	
+<p>
+Appears in: <a href="spec.html#spec.application">&lt;application&gt;</a> and 	<a href="spec.html#spec.library-specification">&lt;library-specification&gt;</a>
+</p>
+
+<p>
+Defines a component type that may latter be used in a <a href="spec.html#spec.component">&lt;component&gt;</a> element
+(for pages and components also defined by this application or library).
+</p>
+
+<table>
+
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>type</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>A name to be used as a component type.</td>
+</tr>
+<tr>
+	<td>specification-path</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>An absolute or relative resource path to the component's specification (including leading
+	slash and file extension).  Relative resources are evaluated relative to
+	 the location of the containing application or library specfication.</td>
+</tr>
+
+</table>
+
+
+</section> <!-- spec.component-type -->
+
+<section name="&lt;configure&gt; element">
+	
+
+<p>
+Appears in: <a href="spec.html#spec.extension">&lt;extension&gt;</a>
+</p>
+
+<p>
+Allows a JavaBeans property of the extension to be set from a statically defined value.  The
+&lt;configure&gt; element
+wraps around the static value.  The value is trimmed of leading and trailing
+whitespace and optionally converted to a specified type before being assigned
+to the property.
+</p>
+
+
+<table>
+
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>property</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>The name of the extension property to configure.</td>
+</tr>
+
+<tr>
+	<td>value</td>
+	<td/>
+	<td>no</td>
+	<td/>
+	<td>The value to configure, which will be converted before being assigned
+	to the property.  If not provided, the character data wrapped by the element
+	is used instead.
+	</td>
+</tr>
+
+</table>
+
+
+
+
+</section> <!-- spec.configure -->
+
+
+
+<section name="&lt;description&gt; element">
+	
+	
+<p>
+Appears in: <em>many</em>
+</p>
+
+<p>
+A description may be attached to a many different elements.  Descriptions are used
+by an intelligent IDE to provide help.  The Tapestry Inspector may also display a description.
+</p>
+	
+<p>
+The descriptive text appears inside the &lt;description&gt; tags.  Leading
+and trailing whitespace is removed and interior whitespace may be altered or removed.  Descriptions
+should be short; external documentation can provide greater details.
+</p>
+	
+<p>
+The 	&lt;description&gt;
+element has no attributes.
+</p>
+
+</section> <!-- spec.description -->
+
+<section name="&lt;extension&gt; element">
+	
+
+<p>
+Appears in: <a href="spec.html#spec.application">&lt;application&gt;</a> and <a href="spec.html#spec.library-specification">&lt;library-specification&gt;</a>
+</p>
+
+<p>
+Defines an extension, a JavaBean that is instantiated as needed to provide
+a global service to the application.
+</p>
+
+
+<table>
+
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>name</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>A name for the extension, which can (and should) look like
+	a qualified class name, but may also include the dash character.
+	</td>
+</tr>
+<tr>
+	<td>class</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>The Java class to instantiate.  The class must have a zero-arguments
+	constructor.</td>
+</tr>
+<tr>
+	<td>immediate</td>
+	<td>boolean</td>
+	<td>no</td>
+	<td>false</td>
+	<td>If true, the extension is instantiated when the specification is read.  If 
+	false, then the extension is not created until first needed.
+	</td>
+</tr>
+
+</table>
+
+
+<p>&lt;extension&gt; Elements</p>
+<source xml:space="preserve">
+  (<a href="spec.html#spec.meta">&lt;meta&gt;</a> | <a href="spec.html#spec.configure">&lt;configure&gt;</a>) *
+</source>
+
+
+</section> <!-- spec.extension -->
+
+<section name="&lt;inject&gt; element">
+  
+  
+  <p>
+    Appears in: <a href="spec.html#spec.component-specification">&lt;component-specification&gt;</a> and <a href="spec.html#spec.page-specification">&lt;page-specification&gt;</a>.
+  </p>
+  
+  <p>
+  <a href="injection.html">Injects</a> an object into the page or component as a
+  property.  Frequently used to inject <a href="hivemind.xml">HiveMind services</a>
+  into a page or component, but has other uses as well.
+  </p>
+  
+  <table>
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+  <td>property</td>
+  <td>string</td>
+  <td>yes</td>
+  <td/>
+  <td>
+    The name of the property to be created.  If the class provides an abstract accessor method, then that method defines
+    the type of the property; otherwise java.lang.Object will be used.
+  </td>
+</tr>
+
+<tr>
+  <td>type</td>
+  <td>string</td>
+  <td>no</td>
+  <td>object</td>
+  <td>
+    The type of injection, which determines how the object attribute is interpreted.
+  </td>
+</tr>
+
+<tr>
+  <td>object</td>
+  <td>string</td>
+  <td>yes</td>
+  <td/>
+  <td>
+    The <em>object reference</em> for the object to be injected.  
+    
+  </td>
+</tr>
+
+  </table>
+  
+</section>  <!-- spec.inject -->
+
+
+<section name="&lt;library&gt; element">
+	
+	
+<p>
+Appears in: <a href="spec.html#spec.application">&lt;application&gt;</a> and <a href="spec.html#spec.library-specification">&lt;library-specification&gt;</a>
+</p>
+
+<p>
+Establishes that the containing application or library uses components defined in
+another library, and sets the prefix used to reference those components.
+</p>
+
+<table>
+
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>id</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>The id associated with the library.  Components within the library
+	can be referenced with the component type
+	<em>id</em>:<em>name</em>.
+	</td>
+</tr>
+<tr>
+	<td>specification-path</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>The complete resource path for the library specification.
+	</td>
+</tr>
+
+</table>
+
+<p>&lt;library&gt; Elements:</p>
+<source xml:space="preserve">
+  <a href="spec.html#spec.description">&lt;description&gt;</a> ?,
+  (<a href="spec.html#spec.meta">&lt;meta&gt;</a> | <a href="spec.html#spec.page">&lt;page&gt;</a> | <a href="spec.html#spec.component-type">&lt;component-type&gt;</a> |  <a href="spec.html#spec.library">&lt;library&gt;</a> | <a href="spec.html#spec.extension">&lt;extension&gt;</a>) *
+</source>
+
+</section> <!-- spec.library -->
+
+<section name="&lt;library-specification&gt; element">
+	
+	
+<p>
+<em>root element</em>
+</p>
+
+<p>
+Defines the pages, components, services and libraries used by a library.  Very similar
+to <a href="spec.html#spec.application">&lt;application&gt;</a>, but without attributes related application name or engine class.
+</p>
+
+<p>
+The 	&lt;library-specification&gt;
+element has no attributes.
+</p>
+	
+
+<p>&lt;library-specification&gt; Elements</p>
+<source xml:space="preserve">
+  <a href="spec.html#spec.description">&lt;description&gt;</a> ?, <a href="spec.html#spec.meta">&lt;meta&gt;</a> *,
+  (<a href="spec.html#spec.page">&lt;page&gt;</a> | <a href="spec.html#spec.component-type">&lt;component-type&gt;</a> | <a href="spec.html#spec.library">&lt;library&gt;</a> | <a href="spec.html#spec.extension">&lt;extension&gt;</a>) *
+</source>
+
+</section> <!-- spec.library-specification -->
+
+
+<section name="&lt;meta&gt; element">
+	
+	
+<p>
+Appears in: <em>many</em>
+</p>
+
+<p>
+The &lt;meta&gt; element is used to store meta-data
+about some other element (it is contained within).  Tapestry ignores this meta-data.
+Any number of key/value pairs may be stored.  The value is provided with
+the value attribute, or the 
+character data for the &lt;meta&gt; element.
+</p>
+
+<table>
+
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>key</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>The name of the property.</td>
+</tr>
+<tr>
+	<td>value</td>
+	<td>string</td>
+	<td>no</td>
+	<td/>
+	<td>The value for the property.  If omitted, the value is taken
+	from the character data (the text the tag wraps around).  If specified,
+	the character data is ignored.</td>
+</tr>
+
+</table>
+
+<p>
+<strong>Note:</strong>
+<br/>
+  In the Tapestry 3.0 DTD, this element was named &lt;property&gt;.
+</p>
+
+</section> <!-- spec.meta -->
+
+
+<section name="&lt;page&gt; element">
+	
+
+<p>
+Appears in: <a href="spec.html#spec.application">&lt;application&gt;</a> and <a href="spec.html#spec.library-specification">&lt;library-specification&gt;</a>
+</p>
+
+<p>
+Defines a page within an application (or contributed by a library).
+Relates a logical name for the page to the path to the page's specification file.
+</p>
+
+
+<table>
+
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>name</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>The name for the page, which must start with a letter,
+	and may contain letters, numbers, underscores and the dash
+	character.
+	</td>
+</tr>
+<tr>
+	<td>specification-path</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>
+	The path to the page's specification, which may be absolute
+	 (start with a leading slash), or relative to the application or library
+	 specification.
+	</td>
+</tr>
+
+</table>
+
+
+</section> <!-- spec.page -->
+
+<section name="&lt;page-specification&gt; element">
+	
+
+<p>
+<em>root element</em>
+</p>
+
+<p>
+Defines a page within an application (or a library).  The 
+&lt;page-specification&gt;
+is a subset of <a href="spec.html#spec.component-specification">&lt;component-specification&gt;</a>
+with attributes and entities related to parameters removed.
+</p>
+
+
+<table>
+
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>class</td>
+	<td>string</td>
+	<td>no</td>
+	<td/>
+	<td>The Java class to instantiate, which must implement the
+	interface <a href="../tapestry/apidocs/org/apache/tapestry/IPage.html">IPage</a>.  Typically, this is
+	<a href="../tapestry/apidocs/org/apache/tapestry/html/BasePage.html">BasePage</a> or a subclass of it.  <a href="../tapestry/apidocs/org/apache/tapestry/html/BasePage.html">BasePage</a> is the default if not otherwise
+	 specified (though Tapestry 4.0 will do a <a href="page-class.html">lookup of the class based on page name</a>).</td>
+</tr>
+
+</table>
+
+
+<p>&lt;page-specification&gt; Elements</p>
+<source xml:space="preserve">
+  <a href="spec.html#spec.description">&lt;description&gt;</a> ?, 
+  (<a href="spec.html#spec.meta">&lt;meta&gt;</a> | <a href="spec.html#spec.bean">&lt;bean&gt;</a> | <a href="spec.html#spec.component">&lt;component&gt;</a> | <a href="spec.html#spec.asset">&lt;asset&gt;</a> | <a href="spec.html#spec.property">&lt;property&gt;</a> | <a href="spec.html#spec.inject">&lt;inject&gt;</a>)*
+</source>
+
+
+</section> <!-- spec.page-specification -->
+
+<section name="&lt;parameter&gt; element">
+	
+
+<p>
+Appears in: <a href="spec.html#spec.component-specification">&lt;component-specification&gt;</a>
+</p>
+
+
+
+<table>
+
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>name</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>The name of the parameter, which must be 
+	a valid Java identifier.</td>
+</tr>
+
+  
+<tr>
+  <td>required</td>
+  <td>boolean</td>
+  <td>no</td>
+  <td>false</td>
+  <td>If true, then the parameter must be
+  bound (though it is possible that the binding's value
+  will still be null).
+ </td>
+</tr>
+
+<tr>
+  <td>property</td>
+  <td>string</td>
+  <td>no</td>
+  <td/>
+  <td>Allows the name of the property
+  to differ from the name of the parameter.  If not specified,
+  the property name will be the same as the parameter name.
+  </td>
+</tr>
+
+<tr>
+	<td>default-value</td>	
+	<td>string</td>
+	<td>no</td>
+	<td/>
+	<td>
+	Specifies the default value for the parameter, if the parameter is not bound.	This value
+  is a <em>
+<a href="bindings.html">binding reference</a>
+</em>, exactly like
+  a <a href="spec.html#spec.binding">&lt;binding&gt;</a> element's value attribute.
+	</td>
+</tr>
+
+<tr>
+  <td>cache</td>
+  <td>boolean</td>
+  <td>no</td>
+  <td>true</td>
+  <td>
+    If true (the default), then the parameter property will cache the parameter property for the
+    duration of the components' render.  if false, then the parameter property will not cache the value, and each 
+    access to the property will result in re-obtaining the value via the binding object.
+    Note that invariant bindings (most bindings except for "ognl") will always be accessed just once
+    and cached.
+  </td>
+</tr>
+  
+<tr>
+  <td>aliases</td>
+  <td>string</td>
+  <td>no</td>
+  <td/>
+  <td>
+    An optional, comma-seperated list of alises for the parameter.  Aliases are used to maintain
+    backwards compatibility when a parameter name is changed. A parameter may be bound using 
+    an aliased name, but a warning will be logged.
+  </td>
+</tr>
+
+<tr>
+  <td>deprecated</td>
+  <td>boolean</td>
+  <td>no</td>
+  <td>false</td>
+  <td>If true, then binding the parameter will generate a runtime warning.  This is used when a parameter is being
+    removed entirely in a later release.</td>
+</tr>
+
+</table>
+
+<p>
+To a component, component parameters appear as new properties that can be read and updated (in Java code, or using OGNL).
+As with specified properties, you may define abstract accessor methods in you Java code, to allow type-safe access to the parameter values.
+</p>
+
+<p>
+<strong>Note:</strong>
+<br/>
+In Tapestry 3.0 and earlier, it was necesary to specify a <em>parameter direction</em>, which informed Tapestry about how the
+parameter was used by the component. This allowed Tapestry to properly control when values moved between a component and its
+container ... but was an awkward solution.  Tapestry 4.0 adds much more sophisticated runtime code generation for parameters so
+they <em>just work</em>, regardless of whether you access a parameter property while the component is rendering, in a listener method,
+or at some other time entirely.
+</p>
+
+</section> <!-- spec.parameter -->
+<section name="&lt;property&gt; element">
+	
+	
+<p>
+Appears in: <a href="spec.html#spec.component-specification">&lt;component-specification&gt;</a>, <a href="spec.html#spec.page-specification">&lt;page-specification&gt;</a>
+</p>
+
+<p>
+Defines a transient or persistent property to be added to the page or component.
+Tapestry will create a subclass of the page or component class (at runtime)
+and add the necessary fields and accessor methods, as well as end-of-request
+cleanup.
+</p>
+
+<p>
+It is acceptible for a page (or component) to be abstract, and have abstract accessor methods
+matching the names that Tapestry will generate for the subclass.  This can be
+useful when setting properties of the page (or component) from a <a href="listenermethods.html">listener method</a>.
+</p>
+
+<p>
+A connected parameter specified in a <a href="spec.html#spec.parameter">&lt;parameter&gt;</a> element may also cause an enhanced subclass
+to be created.
+</p>
+
+<p>
+An initial value may be specified as either the initial-value
+attribute, or as the body of the &lt;property&gt; element
+itself.
+</p>
+
+
+<table>
+
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>name</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>The name of the property to create.</td>
+</tr>
+<tr>
+	<td>persist</td>
+	<td>string</td>
+	<td>no</td>
+	<td>no</td>
+	<td>
+	If blank (the default), then the property is transient (i.e., not persistent).  Otherwise, the
+  name of a persistence strategy must be supplied. The most common persistence
+  strategy is "session" (the property is stored into an HttpSession attribute) - see
+		<a href="state.html#state.page-properties.types">Managing server-side state</a> for 
+		more details.
+	</td>
+</tr>
+<tr>
+	<td>initial-value</td>
+	<td>string</td>
+	<td>no</td>
+	<td/>
+	<td>
+	An optional <a href="bindings.html">binding reference</a> used to initialize the property.  The default
+  prefix for the refrence is "ognl:".
+	</td>
+</tr>
+
+</table>
+
+<p>
+<strong>Note:</strong>
+<br/> In the Tapestry 3.0 DTD, this element was named &lt;property-specification&gt; and had an additional attribute, 
+  type. In Tapestry 4.0, the type of the implemented property will simply match the type of any existing (abstract) 
+  property, or will default to Object. In addition, Tapestry 3.0 only had persistent or not persistent; Tapestry 4.0
+  has different kinds of persistence, denoted by the different strategies.  Tapestry 3.0 persistence is equivalent
+  to Tapestry 4.0 "session" persistence.
+  </p>
+
+</section> <!-- spec.property -->
+
+<section name="&lt;reserved-parameter&gt; element">
+	
+	
+<p>
+Appears in: <a href="spec.html#spec.component-specification">&lt;component-specification&gt;</a>
+</p>
+
+<p>
+Used in components that allow informal parameters to limit the possible
+informal parameters (so that there aren't conflicts with HTML attributes
+generated by the component).
+</p>
+
+<p>
+All formal parameters are automatically reserved.
+</p>
+
+<p>
+Comparisons are caseless, so an informal parameter of "SRC", "sRc", etc., will match
+a reserved parameter named "src" (or any variation), and be excluded.
+</p>
+
+
+
+<table>
+
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>name</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>The name of the reserved parameter.</td>
+</tr>
+
+</table>
+
+
+
+</section> <!-- spec.reserved-parameter -->
+
+
+<section name="&lt;set&gt; element">
+	
+	
+<p>
+Appears in: <a href="spec.html#spec.bean">&lt;bean&gt;</a>
+</p>
+
+<p>
+Allows a property of a managed bean to be set to a value
+obtained via a <a href="bindings.html">binding reference</a>.
+</p>
+
+<table>
+
+<tr>
+  <th>Name</th>
+  <th>Type</th>
+  <th>Required ?</th>
+  <th>Default Value</th>
+  <th>Description</th>
+</tr>
+
+<tr>
+	<td>name</td>
+	<td>string</td>
+	<td>yes</td>
+	<td/>
+	<td>The name of the helper bean property to set.</td>
+</tr>
+<tr>
+	<td>value</td>
+	<td>string</td>
+	<td>no</td>
+	<td/>
+	<td>A <a href="bindings.html">binding reference</a> that provides the value to assign to the bean property.
+	</td>
+</tr>
+
+</table>
+
+
+</section> <!-- spec.set -->
+
+</body>
+</document>

Propchange: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/spec.xml
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message