tapestry/tapestry-framework/src/java/org/apache/tapestry/parse/Tapestry_4_1.dtd

<?xml version="1.0" encoding="UTF-8"?>
<!--

The DTD for Tapestry application, library, page and component specifications.
Associated with the public identifier:

	-//Apache Software Foundation//Tapestry Specification 4.1//EN
	
The canonical location for the DTD is:

	http://tapestry.apache.org/dtd/Tapestry_4_1.dtd

For application specifications, the root element is application.

For component specifications, the root element is component-specification.

For page specifications, the root element is page-specification.

For library specifiations, the root element is library-specification.

This DTD represents a significant change from (and simplification of) the 3.0 DTD. 
Tapestry 4.0 will continue to parse specifications that use the 3.0 DTD for the
forseable future.

The following changes have occured:

- <service> has been removed; it was used to define engine services, which
  is now accomplished using the HiveMind tapestry.services.ApplicationServices
  configuration point.
- <static-binding>, <inherited-binding> and <message-binding> elements have been removed.
  There is now just <binding>, whose value attribute contains a prefix to interpret how
  the remainder of the value is interpreted (no prefix meaning a literal, or static, value).
- <property> renamed to <meta> and <property-specification> renamed to <property>
- Removed the type attribute from <property>
- <property> persistent attribute is now called "persist", and is a string, not a boolean
- Added <inject>
- Removed the direction and type attributes from <parameter>
- Consolidated <context-asset>, <private-asset> and <external-asset> into <asset>
- Consolidated <set-property> and <set-message-property> into <set>
- More flexibility on the order of elements
- Added property attribute to <component>, <bean> and <asset>
- Removed the type attribute from the <configure> element
- Added many alternatives to 'yes' and 'no' for boolean attributes.
- Added aliases and cache attributes to <parameter>
- Added deprecated to <component-specification>
- Removed <listener-binding>
-->
<!-- =======================================================
Entity: attribute-flag

For entity attributes that take a boolean value.
-->
<!ENTITY % attribute-flag "(yes|no|true|false|on|off|1|0|y|n|t|f|aye|nay)">
<!ENTITY % library-content "(description?, (meta|page|component-type|library|extension)*)">
<!-- =======================================================
Element: application
Root element

Defines a Tapestry application.

Attributes:
  name: A textual name used to uniquely identify the application.
  engine-class:  The Java class to instantiate as the application engine.
-->
<!ELEMENT application %library-content;>
<!ATTLIST application
	name CDATA #IMPLIED
	engine-class CDATA #IMPLIED
>
<!-- =======================================================
Element: asset
Contained by: component-specification, page-specification

An asset that may be referenced by the component. Different prefixes
may be applied to the path indicate where the asset is stored; 
context: for the web application context folder or classpath:
for a file stored in the web applications' classpath.

Attributes:
  name: The name of the asset.
  path: The path for the resource, which may be relative or absolute.
  property: The name of a property that will be created to inject the
    asset into the component.
-->
<!ELEMENT asset (meta*)>
<!ATTLIST asset
	name CDATA #REQUIRED
	path CDATA #REQUIRED
  property CDATA #IMPLIED
>
  <!-- =======================================================
Element: bean
Appears in: component-specification, page-specification

Defines a JavaBean that will be used in some way by the component.  Beans
are accessible via the components' beans property (which contains a property
for each bean).  Beans are created as needed, and are discarded based on
the lifecycle attribute.  Beans are typically used to extend the
implementation of a component via aggregation.

Attributes:
  name: the name of the bean
  class: the Java class to instantiate
  lifecycle: when the reference to the bean should be discard
  	"none" no lifecycle, the bean is created and returned, but not stored
  	"request" the bean is retained until the end of the request cycle
  	"page" the bean is retained for the lifespan of the page
  	"render" (default) the bean is retained until the end of the current page render
  property: if specified, then a read-ony property is created in the component
    to access the bean.
    
Nothing prevents a bean for storing state; however, such state will
not be associated with any particular session (unlike persistant page
properties).  Further, because of page pooling, subsequent requests
from the same client may be serviced by different instances of a page and
(therefore) different bean instances.

Beans that have the "request" lifecycle may be stored into a pool
for later re-use (in the same or different page).

The bean may have its properties set.  Properties are set on both
newly instantiated beans, and beans that are retrieved from a pool.

-->
<!ELEMENT bean (description?, (meta|set)*)>
<!ATTLIST bean
	name CDATA #REQUIRED
	class CDATA #REQUIRED
	lifecycle (none | request | page | render) "request"
  property CDATA #IMPLIED
>
<!-- =======================================================
Element: binding
Appears in: component

Binds a parameter of the component to a value. The value may
be literal, an OGNL expression, or something else, as
determined by its prefix. The value attribute is optional,
if not provided, the enclosed character data is the value
(but it is not allowed to specify both value and character data).

Attributes:
  name: The name of the component parameter to bind.
  value The value to bind to the parameter.
-->
<!ELEMENT binding (#PCDATA)>
<!ATTLIST binding
	name CDATA #REQUIRED
	value CDATA #IMPLIED
>
<!-- =======================================================
Element: inherited-binding
Appears in: component

Binds a parameter of the component to a parameter of the container.

Attributes:
  name: The name of the component parameter to bind.
  parameter-name: The name of the container parameter to bind the
    component parameter to.
-->
<!ELEMENT inherited-binding EMPTY>
<!ATTLIST inherited-binding
	name CDATA #REQUIRED
	parameter-name CDATA #REQUIRED
>
<!-- =======================================================
Element: configure
Appears in: extension

Configures one JavaBean property of an extension.

Attributes:
  property:  The name of the property to configure.
  value: The value to be converted and applied.  If not 
    specified, the element's character data is
    used.  
 
-->
<!ELEMENT configure (#PCDATA)>
<!ATTLIST configure
	property CDATA #REQUIRED
	value CDATA #IMPLIED
>
<!-- =======================================================
Element: component
Contained by: component-specification, page-specification

Defines a component contained by the component being specified.

Attribute:
  id: A unique identifier for the component within the container.
  type: The type of component, either a well known logical name, or the complete path
    to the component's specification.
  copy-of: The id of a previously defined component; this component will be a copy
    of the other component.
  inherit-informal-parameters: If yes, then all informal parameters of the containing
    component are copied into this component.
  property: Optional property name; the component instance will be injected into this
    property.

The Tapestry page loader ensures that either type or copy-of is specified, but not both.
-->
<!ELEMENT component (meta | binding | inherited-binding )*>
<!ATTLIST component
	id ID #REQUIRED
	type CDATA #IMPLIED
	copy-of IDREF #IMPLIED
	inherit-informal-parameters %attribute-flag; "no"
  property CDATA  #IMPLIED
>
<!-- =======================================================
Element: component-type
Contained by: application

Establishes a short logic name for a particular component that is used
within the application.

Attributes:
  type: The logical name for the component.
  specification-path:  The complete path to the component's specification.
-->
<!ELEMENT component-type EMPTY>
<!ATTLIST component-type
	type CDATA #REQUIRED
	specification-path CDATA #REQUIRED
>
<!-- =======================================================
Element: component-specification
Root element

A component specification.  It's attributes define the Java class to
instantiate, whether the component may wrap other elements, and whether
informal (undeclared) parameters are allowed.  Very similar to a page-specification,
except that component-specification allows for parameters (formal and informal).

Attributes:
  class: The Java class to instantiate for the component.
  allow-body:  If yes (the default), the component may wrap other elements (have a body).
  allow-informal-parameters:  If yes (the default), informal parameters (parameters that are not
    explictily defined) are allowed.
  deprecated: If yes, then using the component will generate a warning, advising the user
    to find a different component. The default is no.
  inherit-specification: If yes (the default), all elements contained in any superclass components will be
  	directly inherited in this specification.(this includes parameters/properties/assets/etc..)
-->
<!ELEMENT component-specification (description?, (parameter | reserved-parameter | meta | bean | component | asset | property | inject )*)>
<!ATTLIST component-specification
	class CDATA #IMPLIED
	allow-body %attribute-flag; "yes"
	allow-informal-parameters %attribute-flag; "yes"
  	deprecated %attribute-flag; "no"
  	inherit-specification %attribute-flag; "yes"
>
<!-- =======================================================
Element: description
Appears in: many

Several elements may contain descriptions; these descriptions are
optional.  The eventual goal is to provide help in some form of IDE.
Currently, descriptions are optional and ignored.

-->
<!ELEMENT description (#PCDATA)>
<!-- =======================================================
Element: extension
Contained by: application, library-specification

Defines an extension, an object that is instantiated and configured
(like a helper bean) and is then accessible, by name, from the
containing library (or application).

Attributes:
  name: Name of the extension.
  class: Java class to instantiate.
  immediate: If true, the extension is instantiated early instead of as-needed.
  
-->
<!ELEMENT extension (meta | configure)* >
<!ATTLIST extension
	name CDATA #REQUIRED
	class CDATA #REQUIRED
	immediate %attribute-flag; "no"
>
<!-- =======================================================
Element: inject
Contained by: component-specification, page-specification

Defines a new property whose read-only value is an object
obtained from HiveMind.

Attributes:
  property The name of the property.
  type: The type of object to be injected, used to interpret
    the meaning of the object attribute.
  object: The locator used to obtain the value.
-->
<!ELEMENT inject EMPTY>
<!ATTLIST inject
  property CDATA #REQUIRED
  type CDATA "object"
  object CDATA #REQUIRED
>

<!-- =======================================================
Element: library
Appears in: application-specification, library-specification

Defines a library used in the construction of the container
(either another library, or the application itself).

Attributes:
  id: An identifier used to reference pages and components
    provided by the library.
  specification-path: The path to the resource that provides
    the library specification.
-->
<!ELEMENT library EMPTY>
<!ATTLIST library
	id CDATA #REQUIRED
	specification-path CDATA #REQUIRED
>
<!-- =======================================================
Element: library-specification
Root element

Defines a library that may be used in the construction 
of an application (or another library).  An application can
be thought of as a specialized kind of library.

-->
<!ELEMENT library-specification %library-content;>
<!-- =======================================================
Element: page
Contained by: application, library-specification

Defines a single page within the application.  Each application will contain
at least one of these, to define the Home page.

Attributes:
  name: A unique name for the application.
  specification-path:  The resource classpath of the component specification
    for the page.
-->
<!ELEMENT page EMPTY>
<!ATTLIST page
	name CDATA #REQUIRED
	specification-path CDATA #REQUIRED
>
<!-- =======================================================
Element: meta
Contained by: (many other elements)

Defines a key/value pair associated with the application or component specification.  Properties
are used to capture information that doesn't fit into the DTD.  The value for the property is
either the value attribute, or the PCDATA wrapped by the property tag 
(which is trimmed of leading and trailing whitespace).

This should not be confused with several other tags which are used to set JavaBeans properties
of various objects.  The <property> tag exists to allow meta-data to be stored in the specification.

Attributes:
  key: The name of the property to set.
  value: If specified, is the value of the property, otherwise, the PCDATA is used.
  
-->
<!ELEMENT meta (#PCDATA)>
<!ATTLIST meta
	key CDATA #REQUIRED
	value CDATA #IMPLIED
>
<!-- =======================================================
Element: page-specification
Root element

A page specification.  It's attributes define the Java class to
instantiate.  Pages are like components, except they always allow
a body, and never allow parameters (formal or otherwise).

Attributes:
  class: The Java class to instantiate for the component.
-->
<!ELEMENT page-specification (description?,  (meta| bean | component | asset | property | inject )*)>
<!ATTLIST page-specification
	class CDATA #IMPLIED
>
<!-- =======================================================
Element: parameter
Contained by: component-specification

Defines a formal parameter for the component.

Attributes:
  name: A unique name for the parameter.
  required: If yes, then the parameter must be bound.  If no (the default),
    then the parameter is optional.
  property: The name to use, instead of the parameter name, for the
    JavaBean property connected to this parameter.
  default-value: Specifies the default value for the parameter, if not bound,
    as a binding reference.
  cache: If true (the default), then the parameter property will cache the binding value
   If false, then each access to the property will re-acquire the the current value
   for the binding on each access (though invariant bindings may still be cached).
  aliases: An optional, comma-seperated list of aliases for the parameter. Used to allow
    compatibility when parameter names are changed.
  deprecated: If true, then using the parameter will generate a runtime warning.
-->
<!ELEMENT parameter (description?)>
<!ATTLIST parameter
	name CDATA #REQUIRED
	required %attribute-flag; "no"
	property CDATA #IMPLIED
	default-value CDATA #IMPLIED
  cache %attribute-flag; "yes"
  aliases CDATA #IMPLIED
  deprecated %attribute-flag; "no"
>
<!-- =======================================================
Element: property
Appears in: page-specification, component-specification

Identifies a transient or persistent property.

Attributes:
  name: The name of the property.
  persist: The name of the strategy for persisting the property between requests, 
   or leave blank for no persistence (that is, a transient property).  
   "session" is the most common strategy.
  initial-value:  If provided, this is an OGNL expression used
    to initialize the property.  If not specified, the
    body of the element is used as the initial value.
    
-->
<!ELEMENT property (#PCDATA)>
<!ATTLIST property
	name CDATA #REQUIRED
	persist CDATA #IMPLIED
	initial-value CDATA #IMPLIED
>
<!-- =======================================================
Element: reserved-parameter
Appears in: component-specification

Identifies a name which may not be used as an informal parameter.
Informal parameters are typically HTML attribute names; this
list identifies HTML attributes that are written exclusively
by the component and may not be affected by informal parameters.

Attributes:
  name: The parameter name to reserve.
-->
<!ELEMENT reserved-parameter EMPTY>
<!ATTLIST reserved-parameter
	name CDATA #REQUIRED
>

<!-- =======================================================
Element: set
Appears in: bean

Used to initialize a property of a managed bean.  The value
is a binding reference, and is provided as the value attribute, 
or as wrapped character data.

Attributes:
  name: The name of the property to be set.
  value: The value (as a binding reference) to set the property
    to.
-->
<!ELEMENT set (#PCDATA)>
<!ATTLIST set
	name CDATA #REQUIRED
	value CDATA #IMPLIED
>