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> |
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.
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:
More detailed notes on upgrading from Tapestry 3.0 to Tapestry 4.0 are available.
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.
Several attributes are type boolean. Tapestry supports a number of common (and one humorous) values for booleans. Values considered true:
Values considered false:
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>) *
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. |
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.
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>) *
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.
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
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>)*
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. |
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. |
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.
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>) *
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. |
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>) *
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>) *
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>.
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. |
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>)*
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.
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:". |
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.
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. |
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. |