Tapestry Specification DTDs

This document describes the four main types of specifications used in Tapestry. In all four cases, the same DOCTYPE is used: 


<!DOCTYPE root element PUBLIC
  "-//Apache Software Foundation//Tapestry Specification 4.0//EN" 
  "http://tapestry.apache.org/dtd/Tapestry_4_0.dtd">

The root element is different for each of the four types of specification files:

Type File Extension Root Element
Application application <application>
Page page <page-specification>
Component jwc <component-specification>
Library library <library-specification>
Note:

A fifth type of specification, the script template specification, is described seperately . In addition, in Tapestry 4.0, a significant part of an application's behavior is defined by its HiveMind module deployment descriptor.

Changes between releases 3.0 and 4.0

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

The following features of the release 3.0 DTD are changed for release 4.0:

  • The <service> element (inside <application> or <library-specification> ) is no longer supported in release 4.0. 3.0 DTD specifications that use <service> will generate a warning. Use the tapestry.services.ApplicationServices configuration point instead.
  • In the 3.0 DTD, the <binding> 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 binding reference , which uses a prefix to determine which type of binding is to be used.
  • The <static-binding> and <message-binding> elements have been removed, replaced with the <binding> element and the ognl: and message: prefixes, respectively.
  • The <property> element (in 3.0) has been renamed to <meta> .
  • The <property-specification> element (in 3.0) has been renamed to <property> . 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).
  • The <inject> element has been added.
  • The <parameter> element has been simplified; the type and direction attributes have been dropped. The default-value attribute is now a binding reference , as with the <binding> element's value attribute.
  • The <property> element's initial-value attribute (or enclosed character data) is now a binding reference . In release 3.0 it was always an OGNL expression, but is now a binding reference .
  • The <context-asset>, <private-asset> and <external-asset> elements have been consolidated into the new <asset> element, and a prefixing system has been introduced.
  • The <set-property> and <set-message-property> elements have been consolidated into <set>, which now uses a (wait for it) binding reference .
  • The 4.0 DTD is more liberal about the order in which elements may be specified than the 3.0 DTD.
  • Added the property attribute to the <component> and <bean> elements.
  • Removed the type attribute from the <configure> element.
  • Added many more options for boolean attributes .
  • Added the aliases and cache attributes to the <parameter> element.
  • Added the deprecated attribute to <component-specification> and <parameter> .
  • Renamed property-name attribute to property (in several places)
  • Removed the <listener-binding> element
More detailed notes on upgrading from Tapestry 3.0 to Tapestry 4.0 are available.

Property Injection

Several of the specification elements are concerned with property injection . For <inject> , the entire element exists to describe a property injection; in others ( <component> , <bean> and <asset> ), the injection is just one piece of the behavior defined using the element. In all of these cases, Tapestry will create a new property 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 persistent page properties , you should at most declare abstract accessor methods.

Boolean type values

Several attributes are type boolean. Tapestry supports a number of common (and one humorous) values for booleans. Values considered true:
  • true
  • yes
  • on
  • 1
  • t
  • y
  • aye
Values considered false:
  • false
  • no
  • off
  • 0
  • f
  • n
  • nay

<application> element

root element 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.
Name Type Required ? Default Value Description
name string no User presentable name of application.
engine-class string no Name of an implementation of IEngine to instantiate. Defaults to BaseEngine if not specified.
<application> Elements: 
  <description> ?,
  (<meta> | <page> | <component-type> |  <library> | <extension>) *

<asset> element

Specifies the location of an asset, a file (typically an image or stylesheet) that may be exposed to the client web browser. 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. 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.
Prefix Description
context: The asset is stored in the web application context. Relative paths are compouted from the web application root context folder, not the specification file.
classpath: The asset is a file on the classpath. Relative paths are computed from the specification file.
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). Unrecognized prefixes are considered to be the scheme portion of a URL. Such paths are passed through unchanged, and not localized.
Name Type Required ? Default Value Description
name string yes The name of the asset, which must be a valid Java identifier.
path string yes The relative or absolute path to the asset.
property string no The name of a property into which the asset shoud be injected.

<bean> element

Appears in: <component-specification> and <page-specification> A <bean> is used to add behaviors to a page or component via aggregation. Each <bean> defines a named JavaBean that is instantiated on demand. Such managed beans are accessed through the OGNL expression beans. name or via the bean: binding reference . Beans are only instantiated on demand, typically by using a bean: binding reference . 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.
none
The bean is not retained, a new bean will be created on each access.
page
The bean is retained for the lifecycle of the page itself.
render
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.
request
The bean is retained until the end of the current request.
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. Beans must be public classes with a default (no arguments) constructor. Properties of the bean may be configured nested <set> elements.
Name Type Required ? Default Value Description
name string yes The name of the bean, which must be a valid Java identifier.
class string yes The name of the class to instantiate. May optionally include lightweight initialization (see below).
lifecycle none|page|render|request no request As described above; duration that bean is retained once instantiated.
property string no 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.
Lightweight intialization: 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: 
  <bean name="validator" class="org.apache.tapestry.valid.StringValidator,required,minimumLength=10"/>
<bean> Elements: 
  <description> ?, (<meta> | <set>) *

<binding> element

Appears in: <component> Binds a parameter of an embedded component to particular value. In an instantiated component, bindings can be accessed with the OGNL expression bindings. name . 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).
Name Type Required ? Default Value Description
name string yes The name of the parameter to bind.
value string yes The value to bind to the parameter.
The value may be literal string, or a binding reference . Binding references are divided into a prefix and a locator . The prefix identifies how the locator is interpreted.
Prefix Locator Description
ognl: The locator is an OGNL 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.
message: The locator is a key used to obtain a localized message for the page or component.
Note:

More prefixes are forthcoming in release 4.0, and it is is also possible to define your own prefixes.

<component> element

Appears in: <component-specification> and <page-specification> Defines an embedded component within a container (a page or another component). In an instantiated component, embedded components can be accessed with the OGNL expression components. id .
Name Type Required ? Default Value Description
id string yes Identifier for the component here and in the component's template. Must be a valid Java identifier.
type string no A component type to instantiate.
copy-of string no The name of a previously defined component. The type and bindings of that component will be copied to this component.
inherit-informal-parameters boolean no false If true, then any informal parameters of the containing component will be copied into this component.
property string no If a name is provided, then a read-only property will be created with the given name that will allow access to the component.
Either type or copy-of must be specified. 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). 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 <library> element in the containing library or application.

<component> Elements

  (<meta> | <binding>) *

<component-specification> element

root element

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

The structure of a <component-specification> is very similar to a <page-specification> except components have additional attributes and elements related to parameters.

Name Type Required ? Default Value Description
class string no The Java class to instantiate, which must implement the interface IComponent . If not specified, BaseComponent is used (though Tapestry 4.0 will do a lookup of the class based on component type )
allow-body boolean no true

If true, then any body for this component, from its containing page or component's template, is retained and may be rendered using a RenderBody component.

If false, then any body for this component is discarded, and it is not allowed for the body to contain components.

allow-informal-parameters boolean no true

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.

If false, then informal parameters are not allowed in the specification, and discarded if in the template.

deprecated boolean no false 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.

<component-specification> Elements

  <description> ?, 
  (<parameter> | <reserved-parameter> | <meta> | <bean> | 
   <component> | <asset> | <property> | <inject>)*

<component-type> element

Appears in: <application> and <library-specification>

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

Name Type Required ? Default Value Description
type string yes A name to be used as a component type.
specification-path string yes 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.

<configure> element

Appears in: <extension>

Allows a JavaBeans property of the extension to be set from a statically defined value. The <configure> 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.

Name Type Required ? Default Value Description
property string yes The name of the extension property to configure.
value no 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.

<description> element

Appears in: many

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.

The descriptive text appears inside the <description> 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.

The <description> element has no attributes.

<extension> element

Appears in: <application> and <library-specification>

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

Name Type Required ? Default Value Description
name string yes A name for the extension, which can (and should) look like a qualified class name, but may also include the dash character.
class string yes The Java class to instantiate. The class must have a zero-arguments constructor.
immediate boolean no false If true, the extension is instantiated when the specification is read. If false, then the extension is not created until first needed.

<extension> Elements

  (<meta> | <configure>) *

<inject> element

Appears in: <component-specification> and <page-specification> .

Injects an object into the page or component as a property. Frequently used to inject HiveMind services into a page or component, but has other uses as well.

Name Type Required ? Default Value Description
property string yes 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.
type string no object The type of injection, which determines how the object attribute is interpreted.
object string yes The object reference for the object to be injected.

<library> element

Appears in: <application> and <library-specification>

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

Name Type Required ? Default Value Description
id string yes The id associated with the library. Components within the library can be referenced with the component type id : name .
specification-path string yes The complete resource path for the library specification.

<library> Elements:

  <description> ?,
  (<meta> | <page> | <component-type> |  <library> | <extension>) *

<library-specification> element

root element

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

The <library-specification> element has no attributes.

<library-specification> Elements

  <description> ?, <meta> *,
  (<page> | <component-type> | <library> | <extension>) *

<meta> element

Appears in: many

The <meta> 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 <meta> element.

Name Type Required ? Default Value Description
key string yes The name of the property.
value string no 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.

Note:

In the Tapestry 3.0 DTD, this element was named <property>.

<page> element

Appears in: <application> and <library-specification>

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.

Name Type Required ? Default Value Description
name string yes The name for the page, which must start with a letter, and may contain letters, numbers, underscores and the dash character.
specification-path string yes The path to the page's specification, which may be absolute (start with a leading slash), or relative to the application or library specification.

<page-specification> element

root element

Defines a page within an application (or a library). The <page-specification> is a subset of <component-specification> with attributes and entities related to parameters removed.

Name Type Required ? Default Value Description
class string no 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 (though Tapestry 4.0 will do a lookup of the class based on page name ).

<page-specification> Elements

  <description> ?, 
  (<meta> | <bean> | <component> | <asset> | <property> | <inject>)*

<parameter> element

Appears in: <component-specification>

Name Type Required ? Default Value Description
name string yes The name of the parameter, which must be a valid Java identifier.
required boolean no false If true, then the parameter must be bound (though it is possible that the binding's value will still be null).
property string no 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.
default-value string no Specifies the default value for the parameter, if the parameter is not bound. This value is a binding reference , exactly like a <binding> element's value attribute.
cache boolean no true 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.
aliases string no 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.
deprecated boolean no false 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.

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.

Note:

In Tapestry 3.0 and earlier, it was necesary to specify a parameter direction , 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 just work , regardless of whether you access a parameter property while the component is rendering, in a listener method, or at some other time entirely.

<property> element

Appears in: <component-specification> , <page-specification>

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.

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 .

A connected parameter specified in a <parameter> element may also cause an enhanced subclass to be created.

An initial value may be specified as either the initial-value attribute, or as the body of the <property> element itself.

Name Type Required ? Default Value Description
name string yes The name of the property to create.
persist string no no 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 Managing server-side state for more details.
initial-value string no An optional binding reference used to initialize the property. The default prefix for the refrence is "ognl:".
Note:

In the Tapestry 3.0 DTD, this element was named <property-specification> 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.

<reserved-parameter> element

Appears in: <component-specification>

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

All formal parameters are automatically reserved.

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

Name Type Required ? Default Value Description
name string yes The name of the reserved parameter.

<set> element

Appears in: <bean>

Allows a property of a managed bean to be set to a value obtained via a binding reference .

Name Type Required ? Default Value Description
name string yes The name of the helper bean property to set.
value string no A binding reference that provides the value to assign to the bean property.