src/dtd/intake.dtd

<!--
    Intake XML input constraints DTD
    $Id$
-->

<!--
The input-data element is the root of the intake XML
definition file.

basePackage: Base package to use for specifing the class names of
             mapped objects.  This value will be prepended to the
             class name of the mapped object to form the
             fully qualified class name.
             Example: org.apache.turbine.om
             Default: ""

groupPrefix: Prefix to be assigned to all groups within the input-data
             element.  This is used to make group name unique if the
             same group name is used in multiple definition files.
             Default: null
-->
<!ELEMENT input-data (group+)>
<!ATTLIST input-data
  basePackage CDATA #IMPLIED
  groupPrefix CDATA #IMPLIED
>

<!--
The group element defines an intake group.

key:            A short identified for the group.  It is only used in
                query parameters so it does not have to be descriptive.
                This value must be unique across all groups in the
                enclosing input-data element.

                Default: N/A

name:           Name of the group.  This is the value used to get the
                group from the Intake Service.  It must be unique across
                all groups in the enclosing input-data element.

                Default: N/A

mapToObject:    Class name of the object that will be mapped to the
                group.  Instances of this class can be used to set
                the values of the fields within the group.  The
                Intake Service can also set the attributes of
                the object from the fields in the group.

                This class name actually used by the intake service
                will be basePackage+"."+mapToObject.

                Example:
                basePackage=org.apache.turbine.om
                mapToObject=TurbineUser
                Effective class name = org.apache.turbine.om.TurbineUser

                Default: null

poolCapacity:   Capacity of the pool used to store instances of the fields
                within this group.

                Default: 128

Used in:        input-data
-->
<!ELEMENT group (field+)>
<!ATTLIST group
  key CDATA #REQUIRED
  name CDATA #REQUIRED
  mapToObject CDATA #IMPLIED
  pool-capacity CDATA #IMPLIED
>

<!--
The field element defines a field within a group.  This will be used to
validate one HTML input field.

key:            A short identifier for the field.  It is only used in
                query parameters.  It must be unique across all fields
                within the enclosing group element.

                Default: N/A

name:           The name of the field.  This is the identifier used to
                get the field from the Intake Service.  It must be unique
                across all fields all fields within the enclosing group
                element.

                Default: N/A

displayName:    An optional name for the field that can be used for display
                on HTML forms.  This is intended to be a friendly name for

                Default: name

displaySize:    An optional size value to use when create the HTML input tag
                for this field.

type:           Type of data contained in the field.

                Default: "String"

defaultValue:   Default value to be used for the value of the field if one
                is not supplied my the mapped object.

                Default: null

emptyValue:     Value to be used for the value of the field if it is not 
                supplied by the parameters returned from an input form.

                Default: null

multiValued:    If this is true, the field will accept multiple values.
                Otherwise, the field only accepts a single vale.

                Default: false

validator:      Name of the class used for validating the value of the
                field.  This is used to have the field validated by a custom
                validator object.  If this is not set, a default validator
                will be used according to the field type.

                The the name of the class is not fully qualified, it will
                be prepended with org.apache.turbine.services.intake.validator.
                For example: a value of "NumberValidator" will be read as
                "org.apache.turbine.services.intake.validator.NumberValidator".

                Default: default validator for the field type.

mapToObject:    Class name of the mapped object.  This will override the
                mapToObject attribute of the enclosing group element.

                Default: mapToObject from the enclosing group element

mapToProperty:  Name of the property within the mapped object that
                will be mapped to the field.  This value has no meaning
                if mapToObject is not set.

                This is used to determine the names of the getter and
                setter methods in the mapped object.  The actually
                attribute within the object is never accessed directly.

                When determining the name of the getter and setter methods,
                the first character of the value of mapToProperty is made
                uppercase.  It is the prepended with either "get" or "set"
                appropriately.

                The getter method must not take any parameters.  The setter
                method must take exactly one parameter.  For more information
                of the details of determining the methods, see the javadocs
                for java.beans.PropertyDescriptor.

                Note: Specifing an empty string for the value of this attribute
                will have the effect of not mapping this field.  This is very
                useful in cases where the group has a value for mapToObject but
                there are fields in the group which should not be mapped.

                Default: The name of the field.

Used in:        group
-->
<!ELEMENT field (rule*,required-message?)>
<!ATTLIST field
  key CDATA #REQUIRED
  name CDATA #REQUIRED
  displayName CDATA #IMPLIED
  displaySize CDATA #IMPLIED
  type ( boolean | BigDecimal | int  | float | FileItem
       | String | DateString  | StringKey | NumberKey
       | ComboKey | double | short | long ) "String"
  multiValued ( true | false ) "false"
  mapToObject CDATA #IMPLIED
  mapToProperty CDATA #IMPLIED
  validator CDATA #IMPLIED
  defaultValue CDATA #IMPLIED
  emptyValue CDATA #IMPLIED
>

<!--
The rule element is used to decribe validation rules for fields.

name:       Name of the rule.  The valid rule names vary by field type.

            Default: N/A

value:      Value passed to the rule.  The meaning of this attribute
            vary by rule.

            Default: N/A

PCDATA:     Error message set for the field if the validation rule
            fails.

            Default: ""

Used in:    field
-->
<!ELEMENT rule (#PCDATA)>
<!ATTLIST rule
  name CDATA #REQUIRED
  value CDATA #REQUIRED
>

<!--
THIS ELEMENT IS DEPRECATED!!!!!!
Use the required rule instead.

The required-message element is a way of marking a field as required.

PCDATA:     Error message set for the field if a value is not specified
            for the field in the query data.

            Default: ""

Used in:    field
-->
<!ELEMENT required-message (#PCDATA)>