<!--  ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::  -->
    <!--						    											                                  -->
    <!--	j2adl.dtd    			    										                            -->
    <!--																		                                    -->
    <!--	Purpose:															                                -->
    <!--	Document Type Description for Jacquard 2 Application Description	    -->
    <!--	Language. Normative for now; will be replaced by a schema.     		    -->
    <!--																		                                    -->
    <!--	Author:		Simon Brooke <simon@weft.co.uk>							                -->
    <!--	Created:	24th January 2006										                        -->
    <!--	Copyright:	(c) 2006 Simon Brooke.									                  -->
    <!--      							      									                            -->
    <!--	This program is free software; you can redistribute it and/or		      -->
    <!--	modify it under the terms of the GNU General Public License as		    -->
    <!--	published by the Free Software Foundation; either version 2 of the	  -->
    <!--	License, or (at your option) any later version.						            -->
    <!--																		                                    -->
    <!--	This program is distributed in the hope that it will be useful,		    -->
    <!--	but WITHOUT ANY WARRANTY; without even the implied warranty of		    -->
    <!--	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU	    -->
    <!--	General Public License for more details.							                -->
    <!--																		                                    -->
    <!--	You should have received a copy of the GNU General Public License	    -->
    <!--	along with this program; if not, write to the Free Software			      -->
    <!--	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA			        -->
    <!--	02111-1307 USA														                            -->
    <!--																		                                    -->
    <!--  ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::  -->
    
    <!--
        JACQUARD 2 APPLICATION DESCRIPTION LANGUAGE FRAMEWORK
        
        $Revision: 1.1 $
        
        NOTES:
        
        Needless to say this is all hugely experimental.  
        
        At this moment I have /no idea/ how to make the locale stuff work!
 	    -->

<!--  ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::  -->
<!--  Before we start: some useful definitions									                -->
<!--  ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::  -->

<!-- boolean means true or false -->
<!ENTITY % Boolean "(true|false)" >

<!-- 
	Locale is a string comprising an ISO 639 language code followed by a space
	followed by an ISO 3166 country code, or else the string 'default'. See:
	<URL:http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt>
	<URL:http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html>
-->
<!ENTITY % Locale "CDATA" >

<!-- 
	permissions a group may have on an entity, list, page, form or field
	permissions are deemed to increase as you go right. A group cannot 
	have greater permission on a field than on the form it is in, or
	greater permission on form than the entity it belongs to
	
	none:			none
	read:			select
	insert:			insert
	noedit:			select, insert
	edit:			select, insert, update
	all:			select, insert, update, delete
-->
<!ENTITY % Permissions "none|read|insert|noedit|edit|all" >

<!-- 
	data types which can be used in a definition to provide validation - 
	e.g. a string can be used with a regexp or a scalar can be used with 
	min and max values 
	string: 		  varchar		java.sql.Types.VARCHAR
	integer:		  int			  java.sql.Types.INTEGER
	real:			    double		java.sql.Types.DOUBLE
	money:			  money		  java.sql.Types.INTEGER
	date:			    date		  java.sql.Types.DATE
	time:			    time		  java.sql.Types.TIME
	timestamp:		timestamp	java.sql.Types.TIMESTAMP
-->
<!ENTITY % DefinableDataTypes "string|integer|real|money|date|time|timestamp" >

<!-- 
	data types which are fairly straightforward translations of JDBC data types
	boolean:		boolean or	java.sql.Types.BIT
					    char(1)		  java.sql.Types.CHAR
	text:			  text or		  java.sql.Types.LONGVARCHAR 
					    memo		    java.sql.Types.CLOB
-->
<!ENTITY % SimpleDataTypes "%DefinableDataTypes;|boolean|text" >

<!-- 
	data types which are more complex than SimpleDataTypes...
	entity : 		a foreign key link to another entity (i.e. the 'many' end of a 
              one-to-many link);
  list :      a list of some other entity that links to me (i.e. the 'one' end of
              a one-to-many link);
	link : 			a many to many link (via a link table);
	defined : 	a type defined by a definition.
-->
<!ENTITY % ComplexDataTypes "entity|link|list|defined" >

<!-- all data types -->
<!ENTITY % AllDataTypes "%ComplexDataTypes;|%SimpleDataTypes;" >

<!-- content, for things like pages (i.e. forms, lists, pages) -->
<!ENTITY % Content "head|top|foot" >

<!ENTITY % FieldStuff "field|fieldgroup|auxlist|verb">

<!ENTITY % PageContent "%Content;|%FieldStuff;" >

<!ENTITY % PageStuff "%PageContent;|permission|pragma" >

<!-- Properties for pages:
  name:               obviously, the name (URL stub) of the page
  properties:         the properties of the entity the page describes to be shown
                      as fields on the page
      all:            obviously, all properties (except the abstract primary key, if
                      present)
      user-distinct:  all properties which are user-distinct (NOTE: Not yet implemented)
      listed:         only those properties for which fields are explicitly listed
-->  
<!ENTITY % PageAttrs 
	"name CDATA #REQUIRED
	 properties (all|user-distict|listed) #REQUIRED" >

<!--  ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::  -->
<!--  Elements																	                                -->
<!--  ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::  -->

<!-- the application that the document describes: required top level element -->
<!ELEMENT application ( documentation?, content?, definition*,  group*, entity*)>
<!ATTLIST application 
	name 		  CDATA 						#REQUIRED
	version 	CDATA 						#IMPLIED>

    <!-- 
	the definition of a defined type. At this stage a defined type is either
	a string		in which case it must have size and pattern, or
	a scalar		in which case it must have minimum and/or maximum
	pattern must be a regular expression as interpreted by org.apache.regexp.RE
	minimum and maximum must be of appropriate format for the datatype specified.
	Validation may be done client-side and/or server-side at application layer
	and/or server side at database layer.

  name:     the name of this definition
  type:     the simple type on which this defined type is based
  size:     the data size of this defined type
  pattern:  a regular expression which values for this type must match
  minimum:  the minimum value for this type (if base type is scalar)
  maximum:  the maximum value for this type (if base type is scalar)
  -->
    <!ELEMENT definition (documentation?, help*) >

<!ATTLIST definition 
	name 		  CDATA 						#REQUIRED
	type 		  (%DefinableDataTypes;) 		#REQUIRED
	size 		  CDATA 						#IMPLIED
	pattern 	CDATA 						#IMPLIED
	minimum 	CDATA 						#IMPLIED
	maximum 	CDATA 						#IMPLIED>



<!-- 
  a group of people with similar permissions to one another 
  
  name: the name of this group
  parent: the name of a group of which this group is subset
  -->
<!ELEMENT group (documentation?)>

<!ATTLIST group 
  name      CDATA             #REQUIRED
  parent    CDATA             #IMPLIED>



<!-- 
	an entity which has properties and relationships; maps onto a database
	table or a Java serialisable class - or, of course, various other things
  
  name:         obviously, the name of this entity
  natural-key:  if present, the name of a property of this entity which forms
                a natural primary key [NOTE: Only partly implemented. NOTE: much of
                the present implementation assumes all primary keys will be 
                integers. This needs to be fixed!]
-->
<!ELEMENT entity ( documentation?, content?, property*, permission*, (form | page | list)*)>
<!ATTLIST entity 
    name      CDATA           #REQUIRED
    natural-key CDATA         #IMPLIED>

<!-- 
  contains documentation on the element which immediately contains it. TODO:
  should HTML markup within a documentation element be allowed? If so, are
  there restrictions?
-->
<!ELEMENT documentation (#PCDATA)>

<!-- 
	a property (field) of an entity (table) 
	
	name:			  the name of this property.
	type:			  the type of this property.
	default:		the default value of this property. There will probably be 
					    magic values of this!
	definition:	name of the definition to use, it type = 'defined'.
	distinct:		distinct='system' required that every value in the system 
					    will be distinct (i.e. natural primary key);
					    distinct='user' implies that the value may be used by users 
					    in distinguishing entities even if values are not formally 
					    unique; 
					    distinct='all' implies that the values are formally unique 
					    /and/ are user friendly (NOTE: not implemented).
	entity:			if type='entity', the name of the entity this property is 
					    a foreign key link to.
              if type='list', the name of the entity that has a foreign 
              key link to this entity
  farkey:     if type='list', the name of farside key in the listed 
              entity
	required:		whether this propery is required (i.e. 'not null').
	size: 			fieldwidth of the property if specified.
  concrete:   if set to 'false', this property is not stored in the 
              database but must be computed (manually written code must
              be provided to support this)
-->
<!ELEMENT property ( documentation?, permission*, option*, prompt*, help*, ifmissing*)>

<!ATTLIST property 
	name 		    CDATA 					#REQUIRED
	type 		    (%AllDataTypes;)  #REQUIRED
	default 	  CDATA 					#IMPLIED
	definition 	CDATA 					#IMPLIED
	distinct 	  (none|all|user|system) 	#IMPLIED
	entity 		  CDATA 					#IMPLIED
  farkey      CDATA           #IMPLIED
 	required 	  %Boolean; 			#IMPLIED
	size 		    CDATA 					#IMPLIED
  concrete    %Boolean;       #IMPLIED>

<!-- 
	one of an explicit list of optional values a property may have 
	NOTE: whether options get encoded at application layer or at database layer 
	is UNDEFINED; either behaviour is correct. If at database layer it's also 
	UNDEFINED whether they're encoded as a single reference data table or as 
	separate reference data tables for each property.
-->
<!ELEMENT option (documentation?, prompt*)>
<!-- if the value is different from the prompt the user sees, specify it -->
<!ATTLIST option 
  value       CDATA           #IMPLIED>


<!-- 
	permissions policy on an entity, a page, form, list or field 
	
	group: 			the group to which permission is granted
	permission:		the permission which is granted to that group
-->
<!ELEMENT permission (documentation?)>
<!ATTLIST permission 
	group 		  CDATA 					#REQUIRED
	permission 	(%Permissions;) #REQUIRED>


<!--
  pragmatic advice to generators of lists and forms, in the form of 
  name/value pairs which may contain anything. Over time some pragmas
  will become 'well known', but the whole point of having a pragma
  architecture is that it is extensible.
-->
<!ELEMENT pragma (documentation?)>
<!ATTLIST pragma
  name        CDATA           #REQUIRED
  value       CDATA           #REQUIRED>

<!-- 
	a prompt for a property or field; used as the prompt text for a widget 
	which edits it. Typically there will be only one of these per property
  per locale; if there are more than one all those matching the locale may
  be concatenated, or just one may be used.
	
	prompt:			the prompt to use
	locale:			the locale in which to prefer this prompt	
-->
<!ELEMENT prompt (documentation?)>
<!ATTLIST prompt
	prompt		  CDATA				  	#REQUIRED
	locale		  %Locale;				#REQUIRED >

<!-- 
	helptext about a property of an entity, or a field of a page, form or 
	list, or a definition. Typically there will be only one of these per property
  per locale; if there are more than one all those matching the locale may
  be concatenated, or just one may be used.

	locale:			the locale in which to prefer this prompt	
-->
<!ELEMENT help (#PCDATA)>
<!ATTLIST help
	locale		  %Locale;				#REQUIRED >

<!--
  helpful text to be shown if a property value is missing, typically when 
  a form is submitted. Typically there will be only one of these per property
  per locale; if there are more than one all those matching the locale may
  be concatenated, or just one may be used. Later there may be more sophisticated
  behaviour here.
-->
<!ELEMENT ifmissing (#PCDATA)>
<!ATTLIST ifmissing
  locale      %Locale;        #REQUIRED>

<!-- a form through which an entity may be added or edited -->
<!ELEMENT form (documentation?, ( %PageStuff;)*)>
<!ATTLIST form %PageAttrs;>


<!-- a page on which an entity may be displayed -->
<!ELEMENT page (documentation?, ( %PageStuff;)*)>
<!ATTLIST page %PageAttrs;>


<!-- 
	a list on which entities of a given type are listed

	onselect:		name of form/page/list to go to when
					    a selection is made from the list 
-->
<!ELEMENT list (documentation?, ( %PageStuff;)*)>
<!ATTLIST list %PageAttrs;
	onselect	  CDATA 					#IMPLIED >


<!--
  a subsidiary list, on which entities related to primary
  entities in the enclosing page or list are listed
  
  property:   the property of the enclosing entity that this
              list displays (obviously, must be of type='list')
  onselect:   the form or page of the listed entity to call
              when an item from the list is selected
  canadd:     true if the user should be able to add records
              to this list
  -->
<!ELEMENT auxlist (documentation?, (prompt|%FieldStuff;)*)>
<!ATTLIST auxlist
  property    CDATA           #REQUIRED
  onselect    CDATA           #IMPLIED
  canadd      %Boolean;       #IMPLIED>

<!--
  a group of fields and other controls within a form or list, which the 
  renderer might render as a single pane in a tabbed display, for example.
  -->
<!ELEMENT fieldgroup (documentation?, (prompt|%FieldStuff;)*)>
<!ATTLIST fieldgroup
  name        CDATA           #REQUIRED>


<!-- a field in a form or page

  property:   the property which this field displays/edits
  -->
<!ELEMENT field (documentation?, prompt*, help*, permission*) >
<!ATTLIST field 
  property    CDATA           #REQUIRED >

<!-- a verb is something that may be done through a form. Probably the verbs 'store' 
  and 'delete' are implied, but maybe they need to be explicitly declared. The 'verb'
  attribute of the verb is what gets returned to the controller -->
<!ELEMENT verb (documentation?, prompt*, help*, permission*) >
<!ATTLIST verb
  verb        CDATA           #REQUIRED
  dangerous   %Boolean;       #REQUIRED>


<!-- a container for global content -->
<!ELEMENT content (%Content;)*>


<!-- 
	content to place in the head of the generated document; this is #PCDATA 
	because it will almost certainly belong to a different namespace 
	(usually HTML)
-->
<!ELEMENT head (#PCDATA) >


<!-- 
	content to place in the top of the body of the generated document; 
	this is #PCDATA because it will almost certainly belong to a different 
	namespace (usually HTML)
-->
<!ELEMENT top (#PCDATA) >


<!-- 
	content to place at the foot of the body of the generated document; 
	this is #PCDATA because it will almost certainly belong to a different 
	namespace (usually HTML)
-->
<!ELEMENT foot (#PCDATA) >