<!-- :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: --> <!-- --> <!-- 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) >