<?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, page and component specifications.
Associated with the public identifier:

	-//Howard Lewis Ship//Tapestry Specification 1.3//EN
	
The canonical location for the DTD is:

	http://tapestry.sf.net/dtd/Tapestry_1_3.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.2 DTD, with the following exceptions:
- specification (in 1.1) has been split into page-specification and component-specification
- added string-value element
- added library-specification root element
- added library element
- added extension element
- added static value type 'long'
- allow <property> within <bean>, <component>, <extension>, <private-asset>, <context-asset> and <external-asset>
- add "render" to bean lifecycle value
- rename <binding>'s property-path attribute to expression
- simplify set-property to use OGNL expressions
- add "form" as parameter direction
-->

<!-- =======================================================
Entity: attribute-flag

For entity attributesthat 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-alias|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 #REQUIRED
  engine-class CDATA #REQUIRED
>

<!-- =======================================================
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-string-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 property of its container.

Attributes:
  name: The name of the component parameter to bind.
  expression: The OGNL expression.
-->
<!ELEMENT binding EMPTY>
<!ATTLIST binding
  name CDATA #REQUIRED
  expression CDATA #REQUIRED
>

<!-- =======================================================
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.
  
 
-->

<!ELEMENT configure (#PCDATA)>
<!ATTLIST configure 
  property-name CDATA #REQUIRED
  type %static-value-type;
>
  
<!-- =======================================================
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 | field-binding | inherited-binding | static-binding | string-binding)*)>
<!ATTLIST component
  id ID #REQUIRED
  type CDATA #IMPLIED
  copy-of IDREF #IMPLIED
>

<!-- =======================================================
Element: component-alias
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-alias EMPTY>
<!ATTLIST component-alias
  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)*)>
<!ATTLIST component-specification
  class CDATA #REQUIRED
  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.

Attributes:
  xml:lang the language that the description is expressed in.
-->
<!ELEMENT description (#PCDATA)>
<!ATTLIST description
  xml:lang NMTOKEN "en"
>

<!-- =======================================================
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: field-binding
Appears in: component

Binds a parameter of the component to a public static field of
some Java object.

Attributes:
  name: The name of the component parameter to bind.
  field-name:  The name of the field, of the form [package.]class.field.
    The package may be ommitted if it is "java.lang".
-->
<!ELEMENT field-binding EMPTY>
<!ATTLIST field-binding
  name CDATA #REQUIRED
  field-name 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: 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)*)>
<!ATTLIST page-specification
  class CDATA #REQUIRED
>

<!-- =======================================================
Element: parameter
Contained by: component-specification

Defines a formal parameter for the component.

Attributes:
  name: A unqiue name for the parameter.
  java-type: The name of a Java class or primitive type expected by the parameter.
    This is for documentation purposes only, it is not enforced.
  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.
-->

<!ELEMENT parameter (description*)>
<!ATTLIST parameter
  name CDATA #REQUIRED
  java-type CDATA #IMPLIED
  required %attribute-flag; "no"
  property-name CDATA #IMPLIED
  direction (in|form|custom) "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.
  
-->
<!ELEMENT property (#PCDATA)>
<!ATTLIST property
  name CDATA #REQUIRED
>

<!-- =======================================================
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.

Attributes:
  name: The name of the property to be set.
  expression: The OGNL expression that provides a value.
-->

<!ELEMENT set-property EMPTY>
<!ATTLIST set-property
  name CDATA #REQUIRED
  expression CDATA #REQUIRED
>


<!-- =======================================================
Element: set-string-property
Appears in: bean

A localized string.

Attributes:
  key:  Sets a property of a string from a localized string.

-->

<!ELEMENT set-string-property EMPTY>
<!ATTLIST set-string-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 is the PCDATA wrapped by the element
(with leading and trailing whitespace removed).

Attributes:
  name: The name of the component parameter to bind.

-->
<!ELEMENT static-binding (#PCDATA)>
<!ATTLIST static-binding
  name CDATA #REQUIRED
>

<!-- =======================================================
Element: string-binding
Appears in: component

Binds a parameter of the component to a localized string of
its container.

Attributes:
  name: The name of the component parameter to bind.
  key: The key used to access a localized string.
  
-->

<!ELEMENT string-binding EMPTY>
<!ATTLIST string-binding
  name CDATA #REQUIRED
  key CDATA #REQUIRED
>