3.0.4/doc/src/DevelopersGuide/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>-//Howard Lewis Ship//Tapestry Specification 1.3//EN</literal></entry>
	<entry><literal>http://tapestry.sf.net/dtd/Tapestry_1_3.dtd</literal></entry>
</row>

<row>
	<entry>Page</entry>
	<entry>page</entry>
	<entry>&spec.page-specification;</entry>
	<entry><literal>-//Howard Lewis Ship//Tapestry Specification 1.3//EN</literal></entry>
	<entry><literal>http://tapestry.sf.net/dtd/Tapestry_1_3.dtd</literal></entry>
</row>

<row>
	<entry>Component</entry>
	<entry>jwc</entry>
	<entry>&spec.component-specification;</entry>
	<entry><literal>-//Howard Lewis Ship//Tapestry Specification 1.3//EN</literal></entry>
	<entry><literal>http://tapestry.sf.net/dtd/Tapestry_1_3.dtd</literal></entry>
</row>

<row>
	<entry>Library</entry>
	<entry>library</entry>
	<entry>&spec.library-specification;</entry>
	<entry><literal>-//Howard Lewis Ship//Tapestry Specification 1.3//EN</literal></entry>
	<entry><literal>http://tapestry.sf.net/dtd/Tapestry_1_3.dtd</literal></entry>
</row>

<row>
	<entry>Script</entry>
	<entry>script</entry>
	<entry>&script-spec.script;</entry>
	<entry><literal>-//Howard Lewis Ship//Tapestry Script 1.2//EN</literal></entry>
	<entry><literal>http://tapestry.sf.net/dtd/Tapestry_1_2.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>yes</entry>
	<entry/>
	<entry>User presentable name of application.</entry>
</row>
<row>
	<entry>engine-class</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>Name of an implementation of IEngine to instantiate.</entry>
</row>
</tbody>
</tgroup>

</informaltable>
</figure>

<figure>
	<title><sgmltag class="starttag">application</sgmltag> Elements</title>
<literallayout>
  &spec.description; *, &spec.property; *,
  (&spec.page; | &spec.component-alias; | &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-string-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-string-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>


<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.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>
</tbody>
</tgroup>
</informaltable>
</figure>



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

<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>
</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.field-binding; | &spec.inherited-binding; | &spec.static-binding; | &spec.string-binding;) *
</literallayout>
</figure>

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

<section id="spec.component-alias">
	<title><sgmltag class="starttag">component-alias</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-alias</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>The complete resource path to the component's specification (including leading
	slash and file extension).</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>

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


<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>yes</entry>
	<entry/>
	<entry>The Java class to instantiate, which must implement the
	interface &IComponent;.  Typically, this is
	&BaseComponent; or a subclass of it.</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;)*
</literallayout>
</figure>


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

<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>

<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, assuming a root directory matching the servlet context
	root directory.  The path should begin with leading forward slash.
	</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>

<note>
<para>
The DTD supports multiple <sgmltag class="starttag">description</sgmltag> elements, each
localized to a different language.  In practice, a single description, in English, is typically
used.  This approach to providing a localized description is likely to change in the future, and
it is probably safest to expect just a single <sgmltag class="starttag">description</sgmltag> tag
to be allowed in the next revision of the DTD.
</para>
</note>
	
<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>

<figure>
	<title><sgmltag class="starttag">description</sgmltag> element</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>xml:lang</entry>
	<entry>string</entry>
	<entry>no</entry>
	<entry/>
	<entry>The language the message is localized to as an ISO language string.
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>
	
</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.field-binding">
	<title><sgmltag class="starttag">field-binding</sgmltag> element</title>

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

<para>
Binds a parameter of an embedded component to a public static final field.
</para>

<note>
<para>
Although the same result can be accomplished using a &spec.binding;
element and the OGNL expression
<literal>@<replaceable>class-name</replaceable>@<replaceable>field-name</replaceable></literal>,
using a <sgmltag class="starttag">field-binding</sgmltag>
is more efficient, because Tapestry knows that the value is
invariant.
</para>
</note>

<para>
The class name must be the qualified class name.  If the package
is ommitted, <literal>java.lang</literal> is assumed (this makes
it easier to reference common fields
such as <literal>Boolean.TRUE</literal>).
</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">field-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>field-name</entry>
	<entry>string</entry>
	<entry>yes</entry>
	<entry/>
	<entry>The name of a public static final field, in the form
	<literal><replaceable>class-name.field-name</replaceable></literal>.
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>


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

<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-alias; | &spec.service; | &spec.library; | &spec.extension;) *
</literallayout>
</figure>


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

<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 complete resource path to the page's 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>yes</entry>
	<entry/>
	<entry>The Java class to instantiate, which must implement the
	interface &IPage;.  Typically, this is
	&BasePage; or a subclass of it.</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;)*
</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.
</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>java-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|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>
  </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>

<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 path to the asset on the classpath.  The path should begin with leading forward slash.
	</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).  Tapestr ignores this meta-data
Any number of name/value pairs may be stored.  The value is the static text the <sgmltag class="starttag">property</sgmltag>
tag wraps around.
</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>
</tbody>
</tgroup>
</informaltable>
</figure>
</section> <!-- spec.property -->

<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-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>


<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>yes</entry>
	<entry/>
	<entry>The OGNL expression used to set the property.
	</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</figure>

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

<section id="spec.set-string-property">
	<title><sgmltag class="starttag">set-string-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-string-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-string-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 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>
</tbody>
</tgroup>
</informaltable>
</figure>


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

<section id="spec.string-binding">
	<title><sgmltag class="starttag">string-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">string-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.string-binding -->

</appendix>