Tapestry Specification DTDs
- Changes between releases 3.0 and 4.0
- Property Injection
- Boolean type values
- <application> element
- <asset> element
- <bean> element
- <binding> element
- <component> element
- <component-specification> element
- <component-type> element
- <configure> element
- <description> element
- <extension> element
- <inject> element
- <library> element
- <library-specification> element
- <meta> element
- <page> element
- <page-specification> element
- <parameter> element
- <property> element
- <reserved-parameter> element
- <set> element
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://jakarta.apache.org/tapestry/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> |
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 <inherited-binding> element has been removed; parameters of parent components may be accessed as properties.
- 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 `ed. |
<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. |
<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. |
<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.
<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). |
initial-value | string | no | An optional binding reference used to initialize the property. The default prefix for the refrence is "ognl:". |
<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. |