3.0.4/doc/src/UsersGuide/spec.xml

<!-- $Id$ -->
<!--
   Copyright 2004 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.
-->
<appendix id="spec">
	<title>Tapestry Specification DTDs</title>
	

<para>
This appendix describes the four types of specifications
used in Tapestry.
</para>
 
<table>
	<title>Tapestry Specifications</title>
	<tgroup cols="5">
<thead>
<row>
	<entry>Type</entry>
	<entry>File Extension</entry>
	<entry>Root Element</entry>
	<entry>Public ID</entry>
	<entry>System ID</entry>
</row>
</thead>
<tbody>
<row>
	<entry>Application</entry>
	<entry>application</entry>
	<entry>&spec.application;</entry>
	<entry><literal>-//Apache Software Foundation//Tapestry Specification 3.0//EN</literal></entry>
	<entry><literal>http://jakarta.apache.org/tapestry/dtd/Tapestry_3_0.dtd</literal></entry>
</row>

<row>
	<entry>Page</entry>
	<entry>page</entry>
	<entry>&spec.page-specification;</entry>
	<entry><literal>-//Apache Software Foundation//Tapestry Specification 3.0//EN</literal></entry>
	<entry><literal>http://jakarta.apache.org/tapestry/dtd/Tapestry_3_0.dtd</literal></entry>
</row>

<row>
	<entry>Component</entry>
	<entry>jwc</entry>
	<entry>&spec.component-specification;</entry>
	<entry><literal>-//Apache Software Foundation//Tapestry Specification 3.0//EN</literal></entry>
	<entry><literal>http://jakarta.apache.org/tapestry/dtd/Tapestry_3_0.dtd</literal></entry>
</row>

<row>
	<entry>Library</entry>
	<entry>library</entry>
	<entry>&spec.library-specification;</entry>
	<entry><literal>-//Apache Software Foundation//Tapestry Specification 3.0//EN</literal></entry>
	<entry><literal>http://jakarta.apache.org/tapestry/dtd/Tapestry_3_0.dtd</literal></entry>
</row>

<row>
	<entry>Script</entry>
	<entry>script</entry>
	<entry>&script-spec.script;</entry>
	<entry><literal>-//Apache Software Foundation//Tapestry Script Specification 3.0//EN</literal></entry>
	<entry><literal>http://jakarta.apache.org/tapestry/dtd/Script_3_0.dtd</literal></entry>
</row>

</tbody>
</tgroup>
</table>

<para>
The four general Tapestry specifications (&spec.application;, &spec.component-specification;
&spec.page-specification; and &spec.library-specification;) all share the same DTD, but use different
root elements.
</para>

<section id="spec.application">
	<title><sgmltag class="starttag">application</sgmltag> element</title>
	

<para>
<emphasis>root element</emphasis>
</para>

<para>
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.
</para>

<figure>
	<title><sgmltag class="starttag">application</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>no</entry>
	<entry/>
	<entry>User presentable name of application.</entry>
</row>
<row>
	<entry>engine-class</entry>
	<entry>string</entry>
	<entry>no</entry>
	<entry/>
	<entry>Name of an implementation of &IEngine; to instantiate.  Defaults
	to &BaseEngine; if not specified.</entry>
</row>
</tbody>
</tgroup>

</informaltable>
</figure>

<figure>
	<title><sgmltag class="starttag">application</sgmltag> Elements</title>
<literallayout>
  &spec.description; ?, &spec.property; *,
  (&spec.page; | &spec.component-type; | &spec.service; | &spec.library; | &spec.extension;) *
</literallayout>
</figure>

</section>  <!-- spec.application -->

<section id="spec.bean">
	<title><sgmltag class="starttag">bean</sgmltag> element</title>
	
	
<para>
Appears in:
&spec.component-specification; and &spec.page-specification;
</para>	
	
<para>
A <sgmltag class="starttag">bean</sgmltag> is used to add behaviors to a page or component via aggregation.
Each <sgmltag class="starttag">bean</sgmltag> defines a named JavaBean that is instantiated on demand.
Beans are accessed through the OGNL expression <literal>beans.<replaceable>name</replaceable></literal>.
</para>

<para>
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.
</para>

<variablelist>
	<title>bean lifecycle</title>
	<varlistentry>
		<term>none</term>
		<listitem>
			<para>
			The bean is not retained, a new bean will be created on each access.
			</para>
		</listitem>
	</varlistentry>

	<varlistentry>
		<term>page</term>
		<listitem>
			<para>
			The bean is retained for the lifecycle of the page itself.
			</para>
		</listitem>
	</varlistentry>
	
	<varlistentry>
		<term>render</term>
		<listitem> 
			<para>
			The bean is retained until the current render operation completes.
			This will discard the bean when a page or form finishes rewinding.
			</para>
		</listitem>
	</varlistentry>
		
	<varlistentry>
		<term>request</term>
		<listitem>
			<para>
			The bean is retained until the end of the current request.
			</para>
		</listitem>
	</varlistentry>
	

</variablelist>

<para>
Caution should be taken when using lifeycle <literal>page</literal>.  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.
</para>

<para>
Beans must be public classes with a default (no arguments) constructor. Properties of the bean
may be configured using the &spec.set-property; and &spec.set-message-property; elements.
</para>

<figure>
	<title><sgmltag class="starttag">bean</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the bean, which must be a valid Java identifier.</entry>
</row>
<row>
	<entry>class</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the class to instantiate.</entry>
</row>
<row>
	<entry>lifecycle</entry>
	<entry><literal>none|page|render|request</literal></entry>
	<entry>no</entry>
	<entry><literal>request</literal></entry>
	<entry>As described above; duration that bean is retained.</entry>
</row>
</tbody>
</tgroup>

</informaltable>
</figure>


<figure>
	<title><sgmltag class="starttag">bean</sgmltag> Elements</title>
<literallayout>
  &spec.description; ?, &spec.property; *,
  (&spec.set-property; | &spec.set-message-property;) *
</literallayout>
</figure>


</section> <!-- spec.bean -->	
 
<section id="spec.binding">
	<title><sgmltag class="starttag">binding</sgmltag> element</title>

<para>
Appears in: &spec.component;
</para>

<para>
Binds a parameter of an embedded component to an OGNL expression rooted
in its container.
</para>

<para>
In an instantiated component, bindings can be accessed with
the OGNL expression <literal>bindings.<replaceable>name</replaceable></literal>.
</para>

<para>
If the <literal>expression</literal> attribute is omitted, then
the body of the element is used.  This is useful when the
expression is long, or contains problematic characters (such as a mix
of single and double quotes).
</para>


<figure>
	<title><sgmltag class="starttag">binding</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the parameter to bind.</entry>
</row>
<row>
	<entry>expression</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The OGNL expression, relative to the container, to be bound to the parameter.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>

</section> <!-- spec.binding -->

<section id="spec.component">
	<title><sgmltag class="starttag">component</sgmltag> element</title>
	
<para>
Appears in: &spec.component-specification; and &spec.page-specification;
</para>

<para>
Defines an embedded component within a container (a page or another component).
</para>

<para>
In an instantiated component, embedded components can be accessed with
the OGNL expression <literal>components.<replaceable>id</replaceable></literal>.
</para>


<figure>
	<title><sgmltag class="starttag">component</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>id</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>Identifier for the component here and in the component's template.  Must be
	a valid Java identifier.</entry>
</row>
<row>
	<entry>type</entry>
	<entry>string</entry>
	<entry>no</entry>
	<entry/>
	<entry>A component type to instantiate.</entry>
</row>
<row>
	<entry>copy-of</entry>
	<entry>string</entry>
	<entry>no</entry>
	<entry/>
	<entry>The name of a previously defined component.  The type and bindings of that
	component will be copied to this component.
	</entry>
</row>

<row>
	<entry>inherit-informal-parameters</entry>	
	<entry><literal>yes|no</literal></entry>
	<entry>no</entry>
	<entry><literal>no</literal></entry>
	<entry>
	If <literal>yes</literal>, then any informal parameters of the containing
	component will be copied into this component.
	</entry>
</row>

</tbody>
</tgroup>
</informaltable>
</figure>

<para>
Either <literal>type</literal> or <literal>copy-of</literal> must be specified.
</para>

<para>
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).
</para>

<para>
A qualified name is a library id, a colon, and a simple name of a component provided
by the named library (for example, <literal>contrib:Palette</literal>).  
Library ids are defined by a &spec.library; element in the
containing library or application.
</para>
	
<figure>
	<title><sgmltag class="starttag">component</sgmltag> Elements</title>
<literallayout>
  &spec.property; *,
  (&spec.binding; | &spec.inherited-binding; | &spec.listener-binding; | &spec.static-binding; | &spec.message-binding;) *
</literallayout>
</figure>

	
</section> <!-- spec.component -->

<section id="spec.component-type">
	<title><sgmltag class="starttag">component-type</sgmltag> element</title>
	
<para>
Appears in: &spec.application; and 	&spec.library-specification;
</para>

<para>
Defines a component type that may latter be used in a &spec.component; element
(for pages and components also defined by this application or library).
</para>

<figure>
	<title><sgmltag class="starttag">component-type</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>type</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>A name to be used as a component type.</entry>
</row>
<row>
	<entry>specification-path</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>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.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>

</section> <!-- spec.component-type -->


<section id="spec.component-specification">
	<title><sgmltag class="starttag">component-specification</sgmltag> element</title>

<para>
<emphasis>root element</emphasis>
</para>

<para>
Defines a new component, in terms of its API (&spec.parameter;s), embedded components, beans and
assets.
</para>

<para>
The structure of a <sgmltag class="starttag">component-specification</sgmltag>
is very similar to a &spec.page-specification; except components have additional attributes
and elements related to parameters.
</para>


<figure>
	<title><sgmltag class="starttag">component-specification</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>class</entry>
	<entry>string</entry>
	<entry>no</entry>
	<entry/>
	<entry>The Java class to instantiate, which must implement the
	interface &IComponent;.  If not specified, &BaseComponent; is used.
	</entry>
</row>
<row>
	<entry>allow-body</entry>
	<entry><literal>yes|no</literal></entry>
	<entry>no</entry>
	<entry><literal>yes</literal></entry>
	<entry>
	<para>If <literal>yes</literal>, then any body for this component, from its
	containing page or component's template, is retained and may be 
	produced using a &RenderBody; component.
	</para>
	<para>If <literal>no</literal>, then any body for this component is
	discarded.
	</para>	
	</entry>
</row>
<row>
	<entry>allow-informal-parameters</entry>
	<entry><literal>yes|no </literal></entry>
	<entry>no</entry>
	<entry><literal>yes</literal></entry>
	<entry>
	<para>If <literal>yes</literal>, 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.
	</para>
	<para>If <literal>no</literal>, then informal parameters
	are not allowed in the specification, and discarded if in the template.
	</para>
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>

<figure>
	<title><sgmltag class="starttag">component-specification</sgmltag> Elements</title>
<literallayout>
  &spec.description; ?, &spec.parameter; *, &spec.reserved-parameter; *, &spec.property; *,
  (&spec.bean; | &spec.component; | &spec.external-asset; | &spec.context-asset; | &spec.private-asset; | &spec.property-specification;)*
</literallayout>
</figure>


</section> <!-- spec.component-specification -->

<section id="spec.configure">
	<title><sgmltag class="starttag">configure</sgmltag> element</title>

<para>
Appears in: &spec.extension;
</para>

<para>
Allows a JavaBeans property of the extension to be set from a statically defined value.  The
<sgmltag class="starttag">configure</sgmltag> 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.
</para>

<figure>
	<title><sgmltag class="starttag">configure</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>property-name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the extension property to configure.</entry>
</row>
<row>
	<entry>type</entry>
	<entry><literal>boolean|int|long|double|String</literal></entry>
	<entry>no</entry>
	<entry><literal>String</literal></entry>
	<entry>The conversion to apply to the value.</entry>
</row>
<row>
	<entry>value</entry>
	<entry/>
	<entry>no</entry>
	<entry/>
	<entry>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.
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>



</section> <!-- spec.configure -->



<section id="spec.context-asset">
	<title><sgmltag class="starttag">context-asset</sgmltag> element</title>

<para>
Specifies an asset located relative to the web application context root folder.
Context assets may be localized.
</para>

<para>
Assets for an instantiated component (or page) 
may be accessed using the OGNL expression <literal>assets.<replaceable>name</replaceable></literal>.
</para>

<para>
The path may be either absolute or relative.  Absolute paths start with a leading slash, and are evalulated
relative to the context root.  Relative paths are evaluated relative to the application root, which
is typically the same as the context root (the exception being a WAR that contains multiple
Tapestry applications, within multiple subfolders).
</para>

<figure>
	<title><sgmltag class="starttag">context-asset</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the asset, which must be a valid Java identifier.</entry>
</row>
<row>
	<entry>path</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The path to the asset.
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>

</section> <!-- spec.context-asset -->

<section id="spec.description">
	<title><sgmltag class="starttag">description</sgmltag> element</title>
	
<para>
Appears in: <emphasis>many</emphasis>
</para>

<para>
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.
</para>
	
<para>
The descriptive text appears inside the <sgmltag class="starttag">description</sgmltag> 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.
</para>
	
<para>
The 	<sgmltag class="starttag">description</sgmltag>
element has no attributes.
</para>

</section> <!-- spec.description -->

<section id="spec.extension">
	<title><sgmltag class="starttag">extension</sgmltag> element</title>

<para>
Appears in: &spec.application; and &spec.library-specification;
</para>

<para>
Defines an extension, a JavaBean that is instantiated as needed to provide
a global service to the application.
</para>

<figure>
	<title><sgmltag class="starttag">extension</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>

</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>A name for the extension, which can (and should) look like
	a qualified class name, but may also include the dash character.
	</entry>
</row>
<row>
	<entry>class</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The Java class to instantiate.  The class must have a zero-arguments
	constructor.</entry>
</row>
<row>
	<entry>immediate</entry>
	<entry><literal>yes|no</literal></entry>
	<entry>no</entry>
	<entry><literal>no</literal></entry>
	<entry>If <literal>yes</literal>, the extension is instantiated when the specification is read.  If 
	<literal>no</literal>, then the extension is not created until first needed.
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>


<figure>
	<title><sgmltag class="starttag">component-specification</sgmltag> Elements</title>
<literallayout>
  &spec.property; *, &spec.configure; *
</literallayout>
</figure>

</section> <!-- spec.extension -->

<section id="spec.external-asset">
	<title><sgmltag class="starttag">external-asset</sgmltag> element</title>

<para>
Appears in: &spec.component-specification; and &spec.page-specification;
</para>

<para>
Defines an asset at an arbitrary URL.  The URL may begin with a slash to indicate an asset on the same
web server as the application, or may be a complete URL to an arbitrary location on the Internet.
</para>

<para>
External assets may be accessed at runtime with the OGNL expression
<literal>assets.<replaceable>name</replaceable></literal>.
</para>

<figure>
	<title><sgmltag class="starttag">external-asset</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>

</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>A name for the asset. Asset names must be valid Java identifiers.
	</entry>
</row>
<row>
	<entry>URL</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The URL used to access the asset.</entry>
</row>
per</tbody>
</tgroup>
</informaltable>
</figure>


</section> <!-- spec.external-asset -->


<section id="spec.inherited-binding">
	<title><sgmltag class="starttag">inherited-binding</sgmltag> element</title>

<para>
Appears in: &spec.component;
</para>

<para>
Binds a parameter of an embedded component to a parameter
of its container.
</para>


<para>
In an instantiated component, bindings can be accessed with
the OGNL expression <literal>bindings.<replaceable>name</replaceable></literal>.
</para>


<figure>
	<title><sgmltag class="starttag">inherited-binding</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the parameter to bind.</entry>
</row>
<row>
	<entry>parameter-name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of a parameter of the containing component.
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>




</section> <!-- spec.inherited-binding -->

<section id="spec.library">
	<title><sgmltag class="starttag">library</sgmltag> element</title>
	
<para>
Appears in: &spec.application; and &spec.library-specification;
</para>

<para>
Establishes that the containing application or library uses components defined in
another library, and sets the prefix used to reference those components.
</para>

<figure>
	<title><sgmltag class="starttag">library</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>id</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The id associated with the library.  Components within the library
	can be referenced with the component type
	<literal><replaceable>id</replaceable>:<replaceable>name</replaceable></literal>.
	</entry>
</row>
<row>
	<entry>specification-path</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The complete resource path for the library specification.
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>





</section> <!-- spec.library -->

<section id="spec.library-specification">
	<title><sgmltag class="starttag">library-specification</sgmltag> element</title>
	
<para>
<emphasis>root element</emphasis>
</para>

<para>
Defines the pages, components, services and libraries used by a library.  Very similar
to &spec.application;, but without attributes related application name or engine class.
</para>

<para>
The 	<sgmltag class="starttag">library-specification</sgmltag>
element has no attributes.
</para>
	

<figure>
	<title><sgmltag class="starttag">library-specification</sgmltag> Elements</title>
<literallayout>
  &spec.description; ?, &spec.property; *,
  (&spec.page; | &spec.component-type; | &spec.service; | &spec.library; | &spec.extension;) *
</literallayout>
</figure>


</section> <!-- spec.library-specification -->



<section id="spec.listener-binding">
	<title><sgmltag class="starttag">listener-binding</sgmltag> element</title>

<para>
Appears in: &spec.component;
</para>


<para>
A listener binding is used to create application logic, in the form
of a listener (for a &DirectLink;, &ActionLink;, &Form;, etc.)
in place within the specification, in 
a scripting language (such as &Jython; or JavaScript).  The script itself
is the wrapped character data for the <sgmltag class="starttag">listener-binding</sgmltag> 
element.
</para>

<para>
When the listener is triggered, the script is executed.  Three beans,
<varname>page</varname>, <varname>component</varname> and <varname>cycle</varname>
are pre-declared.
</para>

<para>
The <varname>page</varname> is the page activated by the request.  Usually, this is
the same as the page which contains the <varname>component</varname> ... in fact,
usually <varname>page</varname> and <varname>compoment</varname> are identical.
</para>

<para>
The <varname>component</varname> is the component from whose specification
the binding was created (that is, not the &DirectLink;, but the page or component
which embeds the &DirectLink;).
</para>

<para>
The <varname>cycle</varname> is the active request cycle, from which service parameters
may be obtained.
</para>


<figure>
	<title><sgmltag class="starttag">listener-binding</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the listener parameter to bind.</entry>
</row>
<row>
	<entry>language</entry>
	<entry>string</entry>
	<entry>no</entry>
	<entry/>
	<entry>The name of a &BSF;-supported language that the script is written in.  The default,
	if not specified, is <literal>jython</literal>.
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>

</section> <!-- spec.listener-binding -->


<section id="spec.message-binding">
	<title><sgmltag class="starttag">message-binding</sgmltag> element</title>

<para>
Appears in: &spec.component;
</para>

<para>
Binds a parameter of an embedded component to a localized
string of its containing page or component.
</para>

<para>
In an instantiated component, bindings can be accessed with
the OGNL expression <literal>bindings.<replaceable>name</replaceable></literal>.
</para>


<figure>
	<title><sgmltag class="starttag">message-binding</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the parameter to bind.</entry>
</row>
<row>
	<entry>key</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The localized property key to retrieve.
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>
</section> <!-- spec.message-binding -->

<section id="spec.page">
	<title><sgmltag class="starttag">page</sgmltag> element</title>

<para>
Appears in: &spec.application; and &spec.library-specification;
</para>

<para>
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.
</para>

<figure>
	<title><sgmltag class="starttag">page</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name for the page, which must start with a letter,
	and may contain letters, numbers, underscores and the dash
	character.
	</entry>
</row>
<row>
	<entry>specification-path</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>
	The path to the page's specification, which may be absolute
	 (start with a leading slash), or relative to the application or library
	 specification.
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>

</section> <!-- spec.page -->

<section id="spec.page-specification">
	<title><sgmltag class="starttag">page-specification</sgmltag> element</title>

<para>
<emphasis>root element</emphasis>
</para>

<para>
Defines a page within an application (or a library).  The 
<sgmltag class="starttag">page-specification</sgmltag>
is a subset of &spec.component-specification;
with attributes and entities related to parameters removed.
</para>


<figure>
	<title><sgmltag class="starttag">page-specification</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>class</entry>
	<entry>string</entry>
	<entry>no</entry>
	<entry/>
	<entry>The Java class to instantiate, which must implement the
	interface &IPage;.  Typically, this is
	&BasePage; or a subclass of it.  &BasePage; is the default if not otherwise
	 specified.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>

<figure>
	<title><sgmltag class="starttag">page-specification</sgmltag> Elements</title>
<literallayout>
  &spec.description; ?, &spec.property; *,
  (&spec.bean; | &spec.component; | &spec.external-asset; | &spec.context-asset; | &spec.private-asset; | &spec.property-specification;)*
</literallayout>
</figure>


</section> <!-- spec.page-specification -->

<section id="spec.parameter">
	<title><sgmltag class="starttag">parameter</sgmltag> element</title>

<para>
Appears in: &spec.component-specification;
</para>

<para>
Defines a formal parameter of a component.  Parameters may be connected 
(<literal>in</literal>, <literal>form</literal> or <literal>auto</literal>)
or unconnected (<literal>custom</literal>).  If a parameter is
connected, but the class does not provide the property (or does, but
the accessors are abstract), then the framework
will create and use a subclass that contains the implementation
of the necessary property.
</para>

<para>
For <literal>auto</literal> parameters, the framework will create a synthetic property
as a wrapper around the binding.  Reading the property will read the value from
the binding and updating the property will update the binding value.  <literal>auto</literal>
may only be used with required parameters.  <literal>auto</literal> is less
efficient than <literal>in</literal>, but can be used even when the component
is not rendering.
</para>

<figure>
	<title><sgmltag class="starttag">parameter</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the parameter, which must be 
	a valid Java identifier.</entry>
</row>
<row>
  <entry>type</entry>
  <entry>scalar name, or class name</entry>
  <entry>no</entry>
  <entry/>
  <entry>Required for connected parameters.  Specifies
   the type of the JavaBean property that a connected
   parameter writes and reads.  The property must
    match this exact value, which can be a fully specified class name,
    or the name of a scalar Java type.  
   </entry>
  </row>
  
<row>
  <entry>required</entry>
  <entry><literal>yes|no</literal></entry>
  <entry>no</entry>
  <entry><literal>no</literal></entry>
  <entry>If <literal>yes</literal>, then the parameter must be
  bound (though it is possible that the binding's value
  will still be null).
 </entry>
</row>

<row>
  <entry>property-name</entry>
  <entry>string</entry>
  <entry>no</entry>
  <entry/>
  <entry>For connected parameters only; 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.
  </entry>
</row>

<row>
  <entry>direction</entry>
  <entry><literal>in|form|auto|custom</literal></entry>
  <entry>no</entry>
  <entry><literal>custom</literal></entry>
  <entry>
  <para>
  Identifies the semantics of how the parameter is used by the
  component.  <literal>custom</literal>, the default, means the
  component explicitly controls reading and writing values through
  the binding.
  </para>
  
  <para>
  <literal>in</literal> means the property is set from the parameter
  before the component renders, and is reset back to default value
  after the component renders.
  </para>
  
  <para>
  <literal>form</literal> means that the property is set from the
  parameter when the component renders (as with <literal>in</literal>).
  When the form is submitted, the value is read from the property
  and used to set the binding value after the component rewinds.
  </para>
  
  <para>
  <literal>auto</literal> creates a synthetic property that works
  with the binding to read and update.  <literal>auto</literal>
  parameters must be required, but can be used even when the
  component is not rendering.
  </para>
  </entry>
</row>

<row>
	<entry>default-value</entry>	
	<entry>OGNL expression</entry>
	<entry>no</entry>
	<entry/>
	<entry>
	Specifies the default value for the parameter, if the parameter is not bound.	
	</entry>
</row>

</tbody>
</tgroup>
</informaltable>
</figure>



</section> <!-- spec.parameter -->

<section id="spec.private-asset">
	<title><sgmltag class="starttag">private-asset</sgmltag> element</title>

<para>
Specifies located from the classpath.  These exist to support
reusable components packages (as part of a &spec.library-specification;)
packaged in a JAR.  Private assets will be localized.
</para>

<para>
Assets for an instantiated component (or page) 
may be accessed using the OGNL expression <literal>assets.<replaceable>name</replaceable></literal>.
</para>

<para>
The resource path may either be complete and absolute, and start with a leading slash,
or be relative.  Relative paths are evaluated relative to the location of the
containing specification.
</para>


<figure>
	<title><sgmltag class="starttag">private-asset</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the asset, which must be a valid Java identifier.</entry>
</row>
<row>
	<entry>resource-path</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The absolute or relative path to the asset on the classpath. 
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>

</section> <!-- spec.private-asset -->

<section id="spec.property">
	<title><sgmltag class="starttag">property</sgmltag> element</title>
	
<para>
Appears in: <emphasis>many</emphasis>
</para>

<para>
The <sgmltag class="starttag">property</sgmltag> element is used to store meta-data
about some other element (it is contained within).  Tapestry ignores this meta-data
Any number of name/value pairs may be stored.  The value is provided with
the <varname>value</varname> attribute, or the 
character data for the <sgmltag class="starttag">property</sgmltag> element.
</para>

<figure>
	<title><sgmltag class="starttag">property</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the property.</entry>
</row>
<row>
	<entry>value</entry>
	<entry>string</entry>
	<entry>no</entry>
	<entry/>
	<entry>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.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>
</section> <!-- spec.property -->


<section id="spec.property-specification">
	<title><sgmltag class="starttag">property-specification</sgmltag> element</title>
	
<para>
Appears in: &spec.component-specification;, &spec.page-specification;
</para>

<para>
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.
</para>

<para>
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 &listener-method;.
</para>

<para>
A connected parameter specified in a &spec.parameter; element may also cause an enhanced subclass
to be created.
</para>

<para>
An initial value may be specified as either the <literal>initial-value</literal>
attribute, or as the body of the <sgmltag class="starttag">property-specification</sgmltag> element
itself.
</para>

<figure>
	<title><sgmltag class="starttag">property-specification</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the property to create.</entry>
</row>
<row>
	<entry>type</entry>
	<entry>string</entry>
	<entry>no</entry>
	<entry>java.lang.Object</entry>
	<entry>
	The type of the property.  If abstract accessors exist, they must exactly match
	this type.  The type may be either a fully qualified class name, or the name
	of one of the basic scalar types (int, boolean, etc.). It may be suffixed with
	<literal>[]</literal> to indicate an array of the indicated type.
	</entry>
</row>
<row>
	<entry>persistent</entry>
	<entry><literal>yes|no</literal></entry>
	<entry>no</entry>
	<entry><literal>no</literal></entry>
	<entry>
	If true, the generated property will be persistent, firing change notifications
	when it is updated.
	</entry>
</row>
<row>
	<entry>initial-value</entry>
	<entry>string</entry>
	<entry>no</entry>
	<entry/>
	<entry>
	An optional OGNL expression used to initialize the property.  The expression is evaluated
	only when the page is first constructed.
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>
</section> <!-- spec.property-specification -->

<section id="spec.reserved-parameter">
	<title><sgmltag class="starttag">reserved-parameter</sgmltag> element</title>
	
<para>
Appears in: &spec.component-specification;
</para>

<para>
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).
</para>

<para>
All formal parameters are automatically reserved.
</para>

<para>
Comparisons are caseless, so an informal parameter of "SRC", "sRc", etc., will match
a reserved parameter named "src" (or any variation), and be excluded.
</para>


<figure>
	<title><sgmltag class="starttag">reserved-parameter</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the reserved parameter.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>


</section> <!-- spec.reserved-parameter -->

<section id="spec.service">
	<title><sgmltag class="starttag">service</sgmltag> element</title>

<para>
Appears in: &spec.application; and &spec.library-specification;
</para>

<para>
Defines an &IEngineService; provided by the application or by a library.
</para>

<para>
The framework provides several services (home, direct, action, external, etc.).
Applications may override these services by defining different
services with the same names.
</para>

<para>
Libraries that provide services should use a qualified name (that is, put
a package prefix in front of the name) to avoid name collisions.
</para>


<figure>
	<title><sgmltag class="starttag">service</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the service.</entry>
</row>
<row>
	<entry>class</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The complete class name to instantiate.  The class must have
	a zero-arguments constructor and implement the interface
	&IEngineService;
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>

</section> <!-- spec.service -->

<section id="spec.set-message-property">
	<title><sgmltag class="starttag">set-message-property</sgmltag> element</title>

<para>
Appears in: &spec.bean;
</para>

<para>
Allows a property of a helper bean to be set to a localized string
value of its containing page or component.
</para>


<figure>
	<title><sgmltag class="starttag">set-message-property</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the helper bean property to set.</entry>
</row>
<row>
	<entry>key</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>A string property key of the containing page or component.
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>

</section> <!-- spec.set-message-property -->

<section id="spec.set-property">
	<title><sgmltag class="starttag">set-property</sgmltag> element</title>
	
<para>
Appears in: &spec.bean;
</para>

<para>
Allows a property of a helper bean to be set to an OGNL expression (evaluated
on the containing component or page).
</para>


<para>
The value to be assigned to the bean property can be specified
using the <literal>expression</literal> attribute, or as
the content of the <sgmltag class="starttag">set-property</sgmltag> element
itself.
</para>

<figure>
	<title><sgmltag class="starttag">set-property</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the helper bean property to set.</entry>
</row>
<row>
	<entry>expression</entry>
	<entry>string</entry>
	<entry>no</entry>
	<entry/>
	<entry>The OGNL expression used to set the property.
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>

</section> <!-- spec.set-property -->



<section id="spec.static-binding">
	<title><sgmltag class="starttag">static-binding</sgmltag> element</title>

<para>
Appears in: &spec.component;
</para>

<para>
Binds a parameter of an embedded component to a static value.  The value,
which is stored as a string, is specified
as the <literal>value</literal> attribute, or as
the wrapped contents
of the <sgmltag class="starttag">static-binding</sgmltag> tag.  Leading
and trailing whitespace is removed.
</para>

<para>
In an instantiated component, bindings can be accessed with
the OGNL expression <literal>bindings.<replaceable>name</replaceable></literal>.
</para>


<figure>
	<title><sgmltag class="starttag">static-binding</sgmltag> Attributes</title>
<informaltable>
<tgroup cols="5">
<thead>
<row>
  <entry>Name</entry>
  <entry>Type</entry>
  <entry>Required ?</entry>
  <entry>Default Value</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
	<entry>name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of the parameter to bind.</entry>
</row>
<row>
	<entry>value</entry>
	<entry>string</entry>
	<entry>no</entry>
	<entry/>
	<entry>The string value to be used.  If omitted, the wrapped character data
	is used instead (which is more convienient if the value is large, or
	contains problematic punctuation).</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>


</section> <!-- spec.static-binding -->

</appendix>