Google Git
Sign in
apache / tapestry4 / d33c3e83908561b067f859815c313c0a7f27909d / . / tapestry / src / site / xdoc / usersguide / spec.xml
blob: 812c3222be81a759326e8c2a3cbbdfc5f804dfcb [file] [log] [blame]
<?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>
<section name="Tapestry Specification DTDs">
<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://tapestry.apache.org/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>
<span class="info">
<strong>Note:</strong>
<p>
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://hivemind.apache.org/hivemind1/">HiveMind</a>
module deployment descriptor.
</p>
</span>
<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-framework/hivedoc/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 -->
<a name="spec.property-injection"></a>
<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>
<a name="spec.application"></a>
<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="../apidocs/org/apache/tapestry/IEngine.html">
IEngine
</a>
to instantiate. Defaults to
<a
href="../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 -->
<a name="spec.asset"></a>
<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 injected.</td>
</tr>
</table>
</section><!-- spec.asset -->
<a name="spec.bean"></a>
<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 -->
<a name="spec.binding"></a>
<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 -->
<a name="spec.component"></a>
<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 -->
<a name="spec.component-specification"></a>
<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="../apidocs/org/apache/tapestry/IComponent.html">
IComponent
</a>
. If not specified,
<a
href="../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="../components/general/renderbody.html">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 -->
<a name="spec.component-type"></a>
<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 -->
<a name="spec.configure"></a>
<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 -->
<a name="spec.description"></a>
<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 -->
<a name="spec.extension"></a>
<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 -->
<a name="spec.inject"></a>
<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 -->
<a name="spec.library"></a>
<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 -->
<a name="spec.library-specification"></a>
<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 -->
<a name="spec.meta"></a>
<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 -->
<a name="spec.page"></a>
<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 -->
<a name="spec.page-specification"></a>
<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="../apidocs/org/apache/tapestry/IPage.html">
IPage
</a>
. Typically, this is
<a
href="../apidocs/org/apache/tapestry/html/BasePage.html">
BasePage
</a>
or a subclass of it.
<a
href="../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 -->
<a name="spec.parameter"></a>
<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>
<span class="info">
<strong>Note:</strong>
<p>
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>
</span>
</section><!-- spec.parameter -->
<a name="property"></a>
<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>
<span class="info">
<strong>Note:</strong>
<p>
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>
</span>
</section><!-- spec.property -->
<a name="spec.reserved-parameter"></a>
<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 -->
<a name="spec.set"></a>
<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 -->
</section>
</body>
</document>