3.0.4/framework/src/org/apache/tapestry/parse/Tapestry_3_0.dtd

<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: Tapestry_1_3.dtd,v 1.18 2002/09/19 17:25:28 hship Exp $ -->
<!--

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

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

	http://jakarta.apache.org/tapestry/dtd/Tapestry_3_0.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 is backwards compatible with the 1.3 DTD, with the following exceptions:
- <field-binding> has been removed
- attribute class of <component-specification> and <page-specification is now optional
- attributes name and engine-class of <application> are now optional
- added value attribute to <static-binding>
- added value attribute to <property>
- renamed <component-alias> to <component-type>
- rename <set-string-property> to <set-message-property>
- added <listener-binding> element
- added <property-specification> element
- renamed java-type to type inside <parameter>
- allow values to be specified as attributes or wrapped character data in many elements
- allow only a single <description> per element
-->
<!-- =======================================================
Entity: attribute-flag

For entity attributes that take a boolean value, defines 'yes' and 'no'.
The default varies, so isn't included here.
-->
<!ENTITY % attribute-flag "(yes|no)">
<!-- =======================================================
Entity: static-value-type

For entity attributes that take a string but convert it to a real
type.  Defaults to String.

-->
<!ENTITY % static-value-type "(boolean|int|long|double|String) 'String'">
<!ENTITY % library-content "(description?, property*, (page|component-type|service|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: 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" the bean is retained until the end of the current page render
  	
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?, property*, (set-property | set-message-property)*)>
<!ATTLIST bean
	name CDATA #REQUIRED
	class CDATA #REQUIRED
	lifecycle (none | request | page | render) "request"
>
<!-- =======================================================
Element: binding
Appears in: component

Binds a parameter of the component to a OGNL expression, relative
to its container.  The expression may be provided as an attribute, or 
as the body of the element.  The latter case is useful when the 
expression is long, or uses problematic characters (such as a 
mix of single and double quotes).

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

Configures one JavaBean property of an extension.

Attributes:
  property-name:  The name of the property to configure.
  type: Conversion of property value.
  value: The value to be converted and applied.  If not 
    specified, the element's character data is
    used.  
 
-->
<!ELEMENT configure (#PCDATA)>
<!ATTLIST configure
	property-name CDATA #REQUIRED
	type %static-value-type;
	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.

The Tapestry page loader ensures that either type or copy-of is specified, but not both.
-->
<!ELEMENT component (property*, (binding | inherited-binding | listener-binding | static-binding | message-binding)*)>
<!ATTLIST component
	id ID #REQUIRED
	type CDATA #IMPLIED
	copy-of IDREF #IMPLIED
	inherit-informal-parameters %attribute-flag; "no"
>
<!-- =======================================================
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.
-->
<!ELEMENT component-specification (description?, parameter*, reserved-parameter*, property*, (bean | component | external-asset | context-asset | private-asset | property-specification)*)>
<!ATTLIST component-specification
	class CDATA #IMPLIED
	allow-body %attribute-flag; "yes"
	allow-informal-parameters %attribute-flag; "yes"
>
<!-- =======================================================
Element: context-asset
Contained by: component-specification, page-specification

An asset located in the same web application context as the running
application.

Attributes:
  name: The name of the asset.
  path: The path, relative to the web application context, of the resource.
-->
<!ELEMENT context-asset (property*)>
<!ATTLIST context-asset
	name CDATA #REQUIRED
	path CDATA #REQUIRED
>
<!-- =======================================================
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 (property*, configure*)>
<!ATTLIST extension
	name CDATA #REQUIRED
	class CDATA #REQUIRED
	immediate %attribute-flag; "no"
>
<!-- =======================================================
Element: external-asset
Contained by: component-specification, page-specification

Defines an asset at some external source.

Attributes:
  name: The name of the asset.
  URL: The URL used to reference the asset.
-->
<!ELEMENT external-asset (property*)>
<!ATTLIST external-asset
	name CDATA #REQUIRED
	URL CDATA #REQUIRED
>
<!-- =======================================================
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: 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: listener-binding
Appears in: component

Defines an in-place script using the scripting language
supported by Bean Scripting Framework (http://jakarta.apache.org/bsf).
The script itself is the element's character data (often, inside
a CDATA block).

The default language is jython, though this can be overridden.

Attributes:
  name: The name of the component parameter to bind.
  language: The language the script is written in.
-->
<!ELEMENT listener-binding (#PCDATA)>
<!ATTLIST listener-binding
	name CDATA #REQUIRED
	language 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?, property*, (bean | component | external-asset | context-asset | private-asset | property-specification)*)>
<!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.
  type: The name of a Java class or primitive type expected by the parameter.
  required: If yes, then the parameter must be bound.  If no (the default),
    then the parameter is optional.
  property-name: The name to use, instead of the parameter name, for the
    JavaBean property connected to this parameter.
  direction: The normal flow of data through the component 
  			(in, form, custom, auto).
  default-value: Specifies the default value for the parameter, 
  				if the parameter is not bound.
-->
<!ELEMENT parameter (description?)>
<!ATTLIST parameter
	name CDATA #REQUIRED
	type CDATA #IMPLIED
	required %attribute-flag; "no"
	property-name CDATA #IMPLIED
	default-value CDATA #IMPLIED
	direction (in | form | custom | auto) "custom"
>
<!-- =======================================================
Element: private-asset
Contained by: component-specification, page-specification

An asset available within the Java classpath (i.e., bundled inside a JAR or WAR).

Attributes:
  name: The name of the asset.
  resource-path: The complete pathname of the resource.
-->
<!ELEMENT private-asset (property*)>
<!ATTLIST private-asset
	name CDATA #REQUIRED
	resource-path CDATA #REQUIRED
>
<!-- =======================================================
Element: property
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
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:
  name: The name of the property to set.
  value: If specified, is the value of the property, otherwise, the PCDATA is used.
  
-->
<!ELEMENT property (#PCDATA)>
<!ATTLIST property
	name CDATA #REQUIRED
	value CDATA #IMPLIED
>
<!-- =======================================================
Element: property-specification
Appears in: page-specification, component-specification

Identifies a transient or persistent property.

Attributes:
  name: The name of the property.
  type: The type of the value, either the name of a scalar type,
    or the fully qualified name of a class.  If omitted,
    java.lang.Object is used.
  persistent: If "yes", the value will be made persistant.  Default
    is "no".
  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-specification (#PCDATA)>
<!ATTLIST property-specification
	name CDATA #REQUIRED
	type CDATA #IMPLIED
	persistent %attribute-flag; "no"
	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: service
Appears in: application

Defines an engine service.  You may override the default
set of engine services or provide completely new services.

Attributes:
  name: The name of the service.
  class: The Java class to instantiate for the service.

-->
<!ELEMENT service EMPTY>
<!ATTLIST service
	name CDATA #REQUIRED
	class CDATA #REQUIRED
>
<!-- =======================================================
Element: set-property
Appears in: bean

Used to initialize a property of a helper bean.  An OGNL expression
is provided as the expression attribute, or as wrapped
character data.

Attributes:
  name: The name of the property to be set.
  expression: The OGNL expression that provides a value.
-->
<!ELEMENT set-property (#PCDATA)>
<!ATTLIST set-property
	name CDATA #REQUIRED
	expression CDATA #IMPLIED
>
<!-- =======================================================
Element: set-message-property
Appears in: bean

A localized string.

Attributes:
  key:  Sets a property of a string from a localized string.

-->
<!ELEMENT set-message-property EMPTY>
<!ATTLIST set-message-property
	name CDATA #REQUIRED
	key CDATA #REQUIRED
>
<!-- =======================================================
Element: static-binding
Appears in: component

Binds a parameter of the component to a static value defined directly
within this specification. The value either the value ttribute, or
the PCDATA wrapped by the element (with leading and trailing whitespace removed).

Attributes:
  name: The name of the component parameter to bind.
  value: The value of the binding.  If not specied, the PCDATA wrapped
    by the element is the binding.
-->
<!ELEMENT static-binding (#PCDATA)>
<!ATTLIST static-binding
	name CDATA #REQUIRED
	value CDATA #IMPLIED
>
<!-- =======================================================
Element: message-binding
Appears in: component

Binds a parameter of the component to a localized message of
its container.

Attributes:
  name: The name of the component parameter to bind.
  key: The key used to access a localized string.
  
-->
<!ELEMENT message-binding EMPTY>
<!ATTLIST message-binding
	name CDATA #REQUIRED
	key CDATA #REQUIRED
>