Dovetail Site Document Reference

Kevin Gilpin
Last Updated...

About
Testability
Generated Site Java Code

Running DoveTail2Java
The Site Class
The Page Classes
The Query Classes

Statically Compiling your JSP Pages
Index of Elements

About

Dovetail uses 2 primary XML documents to represent a web site: the database schema document, which must conform to schema.dtd, and the site document, which must conform to site.dtd.

This page describes the site DTD. In actuality, the master document for the site schema (DTD is just one way of defining an XML schema) is site.qjml, which is a Quick 3 document. But for the purposes of writing a site XML document, that detail is not important.

Testability

The standard JSP architecture is very difficult to write test cases against. Writing GUI tests that work with HTML pages is notoriously fragile and difficult. Dovetail provides a much easier and more robust way to test the functionality (if not the actual layout of the HTML GUI) of the site. Once the site and database schema XML documents have been written, Dovetail provides a simple mechanism for writing test cases that exercise the functionality of the site.

Site tests are written as documents that conform to the test DTD. A site test can be run simply and easily by invoking the helper class agonism.dovetail.test.Suite

Generated Site Java Code

One of Dovetail's most useful features is the ability to generate Java classes that represent the web site. These Java classes enable JSP page authors to write pages which are tightly and robustly bound to the site XML document. Once a JSP page has compiled, it has as much likelihood of running correctly as a compiled Java class. Standard methodologies for working with forms, parameters, and session data are much less robust. Data values are typically accessed using a String-valued key, which is a very brittle mechanism. For example, suppose that a JSP page takes a parameter named userID. A typical fragment of JSP code might look like this:

  String userID = request.getParameter("userID");

Now, suppose it is necessary to change the name of the userID parameter to userHandle. The JSP page will still compile; only at run-time will the error be manifested. And, even more troublesome, there is no easy way to write automated tests that exercise JSP pages so it takes a lot of effort to write automated tests that will catch a problem like this one. Using Dovetail, the userID parameter would be declared in the site XML document as:

  <page name="getUserInfo">
    <parameter name="userID" required="true">
      <type><string/></type>
    </parameter>
    ...
  </page>

And it would be accessed in the JSP page like this:

  GetUserInfoPage pg = UserSite.instance(request, response, out).getUserInfoPage();
  // We know that the cast to String is safe b/c userID is declared as a string in 
  //   the site document.
  String userID = (String)pg.getUserIDParameter().getValue();

In this case, if userID is changed to userHandle, the JSP page will no longer compile! The Java compiler has caught this error for us.

There are many other similar examples that could be given. They would all serve to demonstrate the 2 primary reasons for writing JSP pages against generated Java classes:

Compile-time checking of access to all the information declared in the site document. Mismatches between the site document and the JSP pages result in compile errors, rather than run-time errors.
The Java code can automatically and robustly handle type conversion. Almost all JSP data is stored as String data, but quite frequently those Strings actually represent Integers, Dates, or other data types. Dovetail lets you declare the data types of each kind of value, and transparently handles the type conversion.

Running DoveTail2Java

The Site and Schema Java classes are generated by running the agonism.dovetail.util.DoveTail2Java utility. Here is an example:

c:\myproject> java agonism.dovetail.util.DoveTail2Java my-site.xml c:\java\dovetail\schema\site.qjml
	               my-schema.xml c:\java\dovetail\schema\schema.qjml c:\java\dovetail\xsl output

You can run DoveTail2Java with no arguments to get simple usage information.

The Site Class

Dovetail generates a single Java class named [package].[name]Site, where the [package] and [name] strings are provided by the package and name attributes of the site element in the site XML document. For the Survey Site, the Site Class is named dovetail.example.survey.site.SurveySite.

The Site class has methods for accessing each of the pages that are defined on it.

Each generated Site class is a subclass of agonism.dovetail.site.Site.

The Page Classes

Dovetail generates a Java class for each page defined in the site. The page class has methods for accessing:

Each parameter. These methods return Parameter objects.
Each link. These methods return Link objects, whose #toString method returns the URL represented by the link.
Each query. These methods return Query objects.
Each form. These methods return Form objects.

Each generated Site class is a subclass of agonism.dovetail.site.Page.

The Query Classes

Dovetail generates a Java class for each query defined in the site. The generated class includes a method to get each query-result which is defined on the query. The method is named according to the pattern get[query-result@name], and it returns the appropriate Java data type according to the data type of the query-result. For example:

**Generated methods to get query-results**
value of query-result@name attribute	Method name	Dovetail data type	Method return type
id	getId	int	int
ID	getID	int	int
name	getName	string	java.lang.String
price	getPrice	float	double
firstName	getFirstName	string	java.lang.String
first-name	getFirstName	string	java.lang.String
creationDate	getCreationDate	date	java.util.Date
data	getData	blob	byte[]

Each generated Query class is a subclass of agonism.dovetail.site.Query. Each time the Query#next() method is invoked, the underlying result set is advanced, and the values returned by the get methods are updated. The following example illustrates various behaviors of the Query class:

  SurveyAskPage pg = SurveySite.instance(request, response, out).getSurveyAskPage();
  SurveyQuery qrySurvey = pg.getSurveyQuery();
  if ( !qrySurvey.next() )
  {
    System.err.println("No survey was found");
    return;
  }
  String id = qrySurvey.getId();
  // Free the query. If a result from this query is accessed later in the code 
  //   execution, the query will be re-evaluated
  qyrSurvey.free();

  // Execute the query again
  // Here we are using the fact that the Query is automatically advanced to the first
  //   record if we call a 'get' method without first calling 'next()'
  String sameID = qrySurvey.getId();
  if ( !id.equals(sameID) )
    System.err.println("Dovetail bug! Ids should be the same");

  ResponsesQuery qryResponses = pg.getResponsesQuery();
  // The following loop will print out each 'responseText' result which was found by the
  //   'responses' query
  for ( int i = 0;qryResponses.next(); ++i )
  {
    System.out.println(i + ") " + qryResponses.getResponseText());
  }

Statically Compiling your JSP Pages

If you are using Tomcat, you can take advantage of a useful Tomcat feature to verify the correctness of your JSP pages before you upload them to your site. Tomcat includes a standalone JSP page compiler class which you can use to make sure that all our JSP pages compile correctly. To run it:

Create a temporary directory, such as c:\temp\gen-java

Run the following java command (with all the Tomcat JAR files in your classpath):

c:\temp\gen-java\> java org.apache.jasper.JspC -d . -die -uriroot path/to/your/jsp/root 
	                    -webapp path/to/your/jsp/root

Compile all the generated Java source files which are now in the gen-java directory

If you can cleanly compile all the generated Java source files, then you can be sure that your JSP pages will compile when you put them up on your production site.

Index of Elements

site
location
page
parameter
type
default
link
query
query-result
body
custom-query
query-parameter
query-value
form
form-element
submit
action
action-bean
redirect
options
parameter-value
session-value
form-value
literal-value
link-value

Element `site`

The site element is the root of any Dovetail site document (hereafter referred to as the 'site document'). The purpose of the site document is to capture as much declarative information about the web site as possible, so that the Java and JSP code for the site can be made as simple as possible, and so that the site is as robust and testable as possible.

**`site` attributes**
Name	Description	Required	Default Value
`name`	A short, simple name for the site. Typically the site and schema documents will have the same name, which would be related in some way to the name of the web site that they are part of. The Java code generator will append 'Site' to the `name`.	true
`package`	This attribute is used when generating the Java classes that represent the site. It should be in the form of a Java package name : name tokens separated by '.' characters. For example, `agonism.dovetail.example.survey`. The Java code generator will append '.site' to the `package` attribute.	true

**`site` child elements**
Name	Description	MinOccurs	MaxOccurs
`location`	The root-level locations in the site. The URL to each location defined on the site document will be /<location name>	0	*
`page`	The root-level pages in the site. The URL to each page defined on the site document will be /<page name>.<file type> Each `page` represents a page (typically a JSP or HTML page) in the web site. Each `page` should correspond to a file on the filesystem. That page, if it has dynamic content (e.g. it is a JSP page) will reference the objects defined in the corresponding `page` element in the site document.	0	*

Element `location`

The site consists of a hierarchy of locations and pages. Each location is like a directory, and each page corresponds to a web page. Locations do not have much special behavior other than organizing pages. The Java code generator appends the location to the package name of each class which is generated for the site, so grouping pages into locations helps to organize the generated Java classes and avoid naming conflicts. For example, you cannot have more than one query element with the same name, unless they are in different locations.

**`location` attributes**
Name	Description	Required	Default Value
`name`	A unique name for the location. Currently, the name of a `location` must be the same as the directory on the file system.	true

**`location` child elements**
Name	Description	MinOccurs	MaxOccurs
`location`	Locations which are located below (are sub-directories of) this location in the site. The URL to each location will be the concatenation of all the names of all its parent locations, plus its own name. For example, if there is a root-level location named users, and it has a child location named admin, the URL to that location is /users/admin.	0	*
`page`	Pages which are located below (are sub-directories of) this location in the site. The URL to each page will be the concatenation of all the names of all its parent locations, plus its own name. For example, if there is a root-level location named users, and it has a child location named admin, which has a JSP page named change-password, the URL to that location is /users/admin/change-password.jsp.	0	*

Element `page`

The site consists of a hierarchy of locations and pages. Each location is like a directory, and each page corresponds to a web page. Page elements are used to declare all the behavior and resources that the JSP page needs for its implementation. The goal is to capture as much declarative information about the page as possbile, to make pages as robust as possbile, and to make it as easy as possbile to test their behavior.

**`page` attributes**
Name	Description	Required	Default Value
`name`	A unique name for the page. Currently, the name of a `page` must be the same as the file on the file system. All the pages in the site document must have unique names. The reason for this rule is that all the links between pages are declared using `link` elements, which must be able to uniquely reference the pages.	true
`content-type`	The value of this attribute must be one of: java Java servlet or object jsp JSP (Java Server Pages) page html HTML page shtml HTML page with server-side includes The `content-type` of the page must be the same as the extension of the file on disk, otherwise the URLs generated by Dovetail will not be correct.	true

**`page` child elements**
Name	Description	MinOccurs	MaxOccurs
`title`	A descriptive title for the page	1	1
`comment`	Optional descriptive text which describes the page. This can be useful for automatic generating of documentation that describes the layout and functionality of the site	0	1
`parameter`	Lists a parameter that is used by the page in some way.	0	*
`query`	Each query element describes a data source that will be used by the form. A query can be implemented as a SQL query, a static list of choices, or any custom Java object that returns a table-like list of values.	0	*
`link`	Describes a hyperlink that the page can use to link to another page. Defining the links in the site document allows the JSP pages to be independent of the physical locations on disk of other pages, and allows Dovetail to check that all required parameters are assigned a value whenever a page is referenced.	0	*
`form`	Describes a form that can be used in the JSP page. The `form` element is used to declare all HTML `input` elements that will be part of the form, and to define where their values will come from. Dovetail makes it easy to link form inputs to database columns, and automatically handles rendering required inputs differently from optional ones, use of `type="PASSWORD"` inputs where appropriate, and saving user input when there is a form validation error and the form is presented to the user again to be corrected. Dovetail also automatically writes out `hidden` values, and warns the page author in the Dovetail log file when a form element is declared in the site document but not used on the JSP page.	0	*

Element `parameter`

Every parameter that the page uses must be declared with a parameter element. Declaring the page parameters has many benefits:

It allows Dovetail to assign default values for parameters
It allows parameters to have data types (a very useful and important feature, which is not a part of the HTTP protocol or the JSP standard)
It allows other elements on the page, such as form elements and queries, to reference parameter values
It allows Dovetail to check every link to a page includes all the parameters that are required by that page

Each of these features eliminates many problems that result from ad-hoc usage of page parameters.

A parameter may be supplied to a page either in the page request URL as a query parameter, or by an HTML form submission.

**`parameter` attributes**
Name	Description	Required	Default Value
`name`	The name of the parameter as it will be used by the site. Parameter names are usually to variable names, e.g. firstName, startDate.	true
`isRequired`	Whether a value for the parameter must always be supplied. When `isRequired` is true, Dovetail ensures that all `link`s that reference this page have provided a value for the parameter.	true

**`parameter` child elements**
Name	Description	MinOccurs	MaxOccurs
`type`	Data type of the parameter. If this element is not present, the default data type is 'string'.	0	1
`default`	Default value for the parameter. If no other value is supplied for the parameter, the default value will be used. If a value is explicitly provided, through a query parameter or form submission, that value overrides the default value.	0	1

Element `type`

A data type. The type element always has one child element, which must be one of 'int', 'float', 'string', 'date', 'boolean', 'blob', 'url'. Type elements are used to define the data type of the literal-value, session-value, form-element, and parameter elements. These values are returned as their java.lang.Object values (Integer, Double), rather than as primitive values (int, double). Some generated methods, such as for Query objects, convert them to primitive types.

**`type` child elements**
Name	Description	MaxOccurs
`int`	Java Integer	1
`float`	Java Double	1
`string`	Java String	1
`date`	Java `java.util.Date`	1
`boolean`	Java Boolean	1
`blob`	Java byte[]	1
`url`	Java String. The intention was that the `url` data type would have special behavior, but as of the time of this writing it behaves just like a `string`	1

Element `default`

Defines the default value for a parameter or query-result. One or more child elements may be included. The first one which returns a non-empty value is used as the default.

**`default` child elements**
Name	Description	MaxOccurs
`link`	A link to another page	*
`literal-value`	A literal value written in the site document.	*
`session-value`	A value stored in the user's web server session.	*
`query-value`	A value which is obtained from a `query-result` defined somewhere on the same page.	*
`parameter-value`	A value which is obtained from a page `parameter`.	*

Element `link`

Used to define a link from one page to another. Using the Dovetail site document to define links between pages ensures that all the links that are used in a site are all valid. Dovetail ensures that the pages referred to by links are valid. It also checks to ensure that the link specifies a value for each required parameter on the page.

Here's an example of a link to a page which shows the results of a survey.

  <link name="results">
    <page-ref page="survey-results"/>
    <url-parameter name="surveyID">
      <parameter-value>surveyID</parameter-value>
    </url-parameter>
  </link>

This link would be used in a JSP page according to the following example:

<%
  SurveyAskPage pg = SurveySite.instance(request, response, out).getSurveyAskPage();
%>
Click <a href="<%= pg.getResultsLink() %> to see the results of this survey.

Links can also be used along with the redirect and link-value elements to automatically redirect a user to a new page after a form has finished processing. The following fragement will automatically send the user to the survey results page.

  <form name="survey-respond">
    ... < form-element in which the user enters her choice -->
    <submit name="Submit">
      ... < the user's action should be sent to a server-side bean for processing.
      <action>
      <redirect><link-value ref="results"/></redirect></action>
    </submit>
  </form>

These examples are taken from the Survey Site example.

**`link` attributes**
Name	Description	Required	Default Value
`name`	Name by which the link will be referred to. An accessor method will be generated on the Java object which implements the link's `page` according to the pattern get<Name>Link(). For instance, the accessor for the link named results will be getResultsLink(). The name of a link must be unique to its page.	true
`toSelf`	If the value of this attribute is "true", the link is defined as a link back to the `page` on which it is declared. This is an easy way to define a link which returns the user back to the page they are already on, including all the query parameters that were passed to the page. For instance, suppose that a page requires that the user be logged in. If the user is not logged in, they should be sent to a "login" page, and after that they should return. This may be implemented by defining a `parameter` on the "login" page named "returnToURL", and passing the value of a "toSelf" link as the value of that parameter. After the user logs in, they are return to the URL as specified by the "returnToURL" parameter. Here is an example of the declaration of such a link: <link name="login"> <page-ref page="login"/> <url-parameter name="returnToURL"> <link toSelf="true"/> </url-parameter> </link>	false

Element `query`

The query element is the fundamental way of supplying data to a page. The source of the data returned by a query may currently be either a SQL query-string or a custom-query Java object.

The interface to a query is similar to a JDBC ResultSet : there are 0 or more records, each of which has a number of accessible fields. The records are accessed by scrolling a cursor through the query. The values which are accessible on each record are defined by query-results.

When Dovetail is evalutaing a query, it starts by instantiating the object which will execute the query. SQL queries are implemented with the class agonism.dovetail.site.QueryString. You may also implement your own custom-query objects. The query object is then used to instantiate a agonism.dovetail.site.IQueryStatement. Then, Dovetail iterates through each of the query-parameter elements in order. For each query-parameter, Dovetail invokes the IQueryStatement#setParameter method. Once all of the parameters have been set, the query is executed.

**`query` attributes**
Name	Description	Required	Default Value
`name`	A name which uniquely identifies the `query` within its `location`. In the context of different locations, query names may be re-used. This requirement is to ensure that the Java classes generated for the queries do not have any naming conflicts.	true
`defaultTableName`	The query typically returns one or more `query-result`s. Each `query-result` may have an explicit `type`, or it may be bound to a column in a database table. When a `query-result` is bound to a database column, its data type is the same as the data type of the column. The column to which a `query-result` is bound is determined by its tableName and columnName attributes. The defaultTableName attribute can be used to provide a default value of the tableName attribute for all the `query-result`s in the `query`.	false	empty string (no table)

**`query` child elements**
Name	Description	MinOccurs	MaxOccurs
`query-result`	Defines a result that will be returned by the `query`. Successive values for the `query-result` are made available as the cursor advances through the records.	0	*
`query-parameter`	Provides a value which is bound to a query parameter. This mechanism provides a simple way to queries which include dynamic values.	0	*
`body`	Defines the body of the query. The body of the query is the actual mechanism which will be used to obtain the query data.	1	1

Element `query-result`

Defines a result that will be returned by a query.

Each query-result may have an explicit data type, or it may be bound to a column in a database table. When it is bound to a database column, its data type is the same as the data type of that column. The column to which a query-result is bound is determined by its tableName and columnName attributes. If the tableName is not specified, the defaultTableName attribute of the query is used instead. If no type is specified, and the query-result is not bound to a table column, or the table column does not exist, Dovetail will generate an error message when the Java code for the query is being generated.

**`query-result` attributes**
Name	Description	Required
`name`	A name which is used by other elements such as `query-value` to refer to the `query-result`.	true
`tableName`	Specifies the name of the table to which this `query-result` is bound. The defaultTableName attribute on `query` can be used to specify a default table name that applies to all its `query-result`s.	false
`columnName`	Specifies the name of the column within tableName (or the `query`'s defaultTableName) to which this `query-result` is bound. If a value for this attribute is specified, then either the tableName or defaultTableName must also be specified. If the tableName is specified, and no columnName is given, then the name of the `query-result` is used as the column name. Thus, if the name of the column is the same as the name of the `query-result`, it is not necessary to specify the columnName.	false

**`query-result` child elements**
Name	Description	MinOccurs	MaxOccurs
`type`	Optional data type of the `query-result`. If this element is not present, the `query-result` should be bound to a table column with the columnName, tableName, and `query`.defaultTableName attributes.	0	1

Element `body`

Defines the body of a query. The body of the query determines how the query results will actually be obtained. Exactly one of the query-string and custom-query child elements must be specified.

**`body` child elements**
Name	Description	MinOccurs	MaxOccurs
`query-string`	Specifies that the query will be implemented by executing a parameterized SQL query. The SQL string will be used to create a JDBC PreparedStatement. The `query-parameter`s will then be used to set the values of the query parameters (if any), and the query will then be passed to the database and used to create a ResultSet. See the PreparedStatement JavaDoc for a description of how to write a SQL query with query parameters. If you do use query parameters, you must have exactly the same number of `query-parameter` elements in the `query` as there are question marks ('?') in the query string. The content of the `query-string` should be the SQL string. Be aware that you will need to use XML entities in place of characters which have special meaning in XML. In particular: Instead of '<', write '<' Instead of '&', write '&' For example, the query SELECT * FROM Employees WHERE salary < 10000 Should be written as: <body> <query-string>SELECT * FROM Employees WHERE salary < 10000</query-string> </body>	0	1
`custom-query`	Specifies that the query will be implemented by instantiating a named Java object.	0	1

Element `custom-query`

Used to implement the body of a query with a custom Java object. The Java class named in the className attribute should implement the interface agonism.dovetail.site.ICustomQuery.

**`custom-query` attributes**
Name	Description	Required	Default Value
`className`	The name of the Java class that implements agonism.dovetail.site.ICustomQuery. Each time the `query` is executed, an instance of this class will be created and used.	true

Element `query-parameter`

Used to specify the value of a query parameter. If the query is implemented with a query-string, there must be the same number of query-parameter elements as there are query parameters in the SQL string. If the query is a custom-query, the behavior of extra or undefined query-parameters is up to the implementation.

Exactly one child element which defines the value bound to the query-parameter must be specified.

**`query-parameter` child elements**
Name	Description	MaxOccurs
`literal-value`	A literal value written in the site document.	1
`session-value`	A value stored in the user's web server session.	1
`query-value`	A value which is obtained from a `query-result` defined somewhere on the same page.	1
`parameter-value`	A value which is obtained from a page `parameter`.	1

Element `query-value`

A value which is obtained from some query-result. As the page loops through a query, the query-value in bound to the current value of the query-result. For instance, suppose a page contains the following:

  <query name="ids">
    <query-result name="id"/>
    <query-result name="name"/>
    ... [ query body ] ...
  </query>

  <form name="choose-id"
    <form-element name="id">
      <options><query-value query="ids" result="id"/></options>
    </form-element>
  </form>

The following JSP page fragement would render a radio input for each id/name pair returned by the query:

<%@ taglib uri="/dovetail-taglibs" prefix="dt" %>
<%
  ChooseIdForm form = pg.getChooseIdForm();
  IdsQuery query = pg.getIdsQuery();
  while ( query.next() )
  {
%>
    <dt:radio formElement="<%= form.getIdElement() %>" /><%= query.getName() %><br>
<%
  }
%>

This example makes use of the Dovetail dt:radio JSP Tag.

**`query-value` attributes**
Name	Description	Required	Default Value
`query`	The name of the `query` which will provide the value	true
`result`	The name of the `query-result` which will provide the value	true

Element `form`

Each form that will be presented to the user in an HTML page can be modeled in the site XML document. Modeling forms in XML provides the following great benefits:

Form inputs which are mandatory can be automatically rendered as such
Form inputs can be automatically bound to database columns. This makes it much easier to correctly implement forms which gather some data and then write it into a database table.
Form data can be automatically passed to server-side beans according to declarative information in the site XML document
Dovetail will automatically return a request to the form, with the form input values preserved, if the server-side beans decide that the data is invalid (for example, if no value is entered for a required field)
A consistent way of gathering and rendering form errors
After completing the form, the user can be automatically redirected to the appropriate next page
Default (initial) values for form inputs can be declaratively specified and automatically rendered by Dovetail or custom TagLibs when the JSP is written.

A form consists of form-elements which describe the form inputs, and submit elements which are rendered as submit buttons in the HTML page. Each submit can have a different series of actions.

**`form` attributes**
Name	Description	Required	Default Value
`name`	The name by which the form is referred to by other elements on the page, such as `form-value`. The name of a form must be unique within its `location`.	true
`defaultTableName`	Like `query-result`s, each `form-element` may be bound to a database column in order to specify its data type. The defaultTableName attribute provides a default value for the tableName attribute of the `form-element`s in the form.	false

**`form` child elements**
Name	Description	MinOccurs	MaxOccurs
`form-element`	Each `form-element` is rendered into the HTML page as a FORM INPUT.	0	*
`submit`	Each form has 1 or more `submit` buttons. Each of these will typically be rendered in the JSP page as a button that the user can push.

Element `form-element`

Each form-element describes a form input that will be rendered into the HTML page. For example, an input to register a new user might be declared as:

  <form name="register" defaultTableName="RegisteredUser">
    <form-element name="firstName"/>
    ... <!-- other form-element declarations -->
  </form>

And it would be rendered by the Dovetail Text taglib as:

<input type="text" name="firstName">

The form-element may have an explicit type, or it may be bound to a column in a database table. When a form-element is bound to a database column, its data type is the same as the data type of the column. The column to which a form-element is bound is determined by its tableName and columnName attributes. The defaultTableName attribute can be used to provide a default value of the tableName attribute for all the form-elements in the form. If the tableName is specified, and no columnName is given, then the name of the form-element is used as the column name. Thus, if the name of the column is the same as the name of the form-element, it is not necessary to specify the columnName.

Only one of the link, literal-value, session-value, query-value, or parameter-value child elements may be present. If present, it specifies a default value for the form element that will be rendered to the HTML page. The combination of one of these elements with the hidden="true" attribute renders a specific value into the HTML page as a hidden form input.

**`form-element` attributes**
Name	Description	Required	Default Value
`name`	A name which is used by other elements such as `form-value` to refer to the `form-element`.	true
`hidden`	If the value of this attribute is 'true', then the form-element will be rendered as a type="hidden" input. It will not appear to the user, and the user will not be able to modify the value of the input, but it will be submitted to the server along with the rest of the form data. Hidden inputs are rendered when the Form#renderEnd method is invoked.	false	false
`password`	If the value of this attribute is 'true', the `form-element` will be rendered as type="password". The `form-element` is also rendered as a password input if it is bound to a database column whose @isPassword attribute is 'true'.	false	false
`tableName`	Specifies the name of the table to which this `form-element` is bound. The defaultTableName attribute on `form` can be used to specify a default table name that applies to all its `form-element`s.	false
`columnName`	Specifies the name of the column to which this `form-element` is bound.	false

**`form-element` child elements**
Name	Description	MaxOccurs
`type`	Specifies the data type of the form element. If the form element is not bound to a database column, `type` is required.	1
`link`	A link (URL and query string) to another page within the site.	1
`literal-value`	A literal value written in the site document.	1
`session-value`	A value stored in the user's web server session.	1
`query-value`	A value which is obtained from a `query-result` defined somewhere on the same page.	1
`parameter-value`	A value which is obtained from a page `parameter`.	1
`options`	Some form inputs, including radio buttons, list boxes, and combo boxes, require the user to select from a pre-defined list of legal values. The `options` element can be used to define a `query-value` which provides this list of options.	1

Element `submit`

Each submit element in a form will typically be rendered in the JSP page as a button that the user can push. The generated Java class for the Form will have a method named get<Name>Submit, which returns a agonism.dovetail.site.Submit object, whose render method may be used to render the HTML submit button. This process will look something like the following example:

  SurveyRespondForm form = pg.getSurveyRespondForm();
  ... // render form elements
  <% form.getSubmitSubmit().render("Submit"); %>
  <% form.renderEnd(); %>

**`submit` attributes**
Name	Description	Required	Default Value
`name`	Name by which the attribute can be accessed from its `form`.	true

**`submit` child elements**
Name	Description	MinOccurs	MaxOccurs
`action`	Each submit button should have zero or more `action`s which result when the submit button is pushed. A submit button which has no `action`s will POST back to the same JSP page which rendered the form. If there is more than one action, they are each executed sequentially as long as they are successful. Success is determined by the return value from the IAction#process method.

Element `action`

Each action element implements some action that is taken by an application when the user pushes a submit button. An action is typically a Java object which implements the IAction interface. This interface contains only one method, process, which must be implemeted by the action implementor.

Each action element must contain either a action-bean or submit element as its only child.

**`action` child elements**
Name	Description	MinOccurs	MaxOccurs
`action-bean`	An `action-bean` identifies a Java object that implements the `action`.
`redirect`	A `redirect` action is a built-in action that redirects the user to a new page. The `redirect` element is also interesting in that it suggests how additional stock actions can be built into Dovetail which can reduce the amount of Java coding necessary to build a JSP web site.

Element `action-bean`

A Java object that implements the action. The Java class identified by the class-name attribute must implement the IAction interface.

**`action-bean` attributes**
Name	Description	Required	Default Value
`class-name`	Full name of the Java class that implements this `action`.	true

Element `redirect`

Redirects the user to a new page. The redirect element must have exactly one child element which identifies the page to which the user will be redirected.

**`redirect` child elements**
Name	Description	MaxOccurs
`link-value`	A link (URL and query string) to another page within the site.	1
`literal-value`	A literal value written in the site document.	1
`session-value`	A value stored in the user's web server session.	1
`query-value`	A value which is obtained from a `query-result` defined somewhere on the same page.	1
`parameter-value`	A value which is obtained from a page `parameter`.	1

Element `options`

Used to define a list of choices that are displayed in an HTML page as radio buttons, a list box, combo box, or some other type of input which has a discrete set of valid values. Suppose a page has a query which returns a list of valid responses to a survey question. A choice element may be used for the form-element that will be used to record the user's choice.

  <query name="responses" defaultTableName="SurveyResponse">
    <query-result name="id"/>
    <query-result name="responseText"/>
    <query-parameter>
      <parameter-value>surveyID</parameter-value>
    </query-parameter>
    <body>
      <query-string>SELECT * FROM SurveyResponse WHERE surveyID = ? ORDER BY id ASC</query-string>
    </body>
  </query>

  <form name="survey-respond">
    <form-element name="responseID" tableName="SurveyResponse" columnName="id">
      <options>
        <query-value query="responses" result="id"/>
      </options>
    </form-element>
    ... <!-- submit elements and form actions -->
  </form>

Then, the JSP page would render this form element according to the following example:

<%@ taglib uri="/dovetail-taglibs" prefix="dt" %>
<%
    SurveyAskPage pg = SurveySite.instance(request, response, out).getSurveyAskPage();
    SurveyRespondForm form = pg.getSurveyRespondForm();
    ResponsesQuery qryResponses = pg.getResponsesQuery();
%>
...
<%
    while ( qryResponses.next() )
    {
%>
        <dt:radio formElement="<%= form.getResponseIDElement() %>" /><%= qryResponses.getResponseText() %><br>
<%
    }
%>

**`options` child elements**
Name	Description	MinOccurs	MaxOccurs
`query-value`	Specifies the `query-result` which will supply the valid choices for the `form-input`.	1	1

Element `parameter-value`

A value which is obtained from a page parameter. If a value for the parameter has been explicitly provided via the URL query string or a form input element, that value will be bound to the parameter-value. Otherwise, the default value of the parameter will be used.

parameter-values are very useful for:

Providing values for query-parameters
Providing values for form-elements
Providing values for url-parameters

As an example, suppose a page contains the following fragments:

  <parameter name="surveyID" required="true">
    <type><int/></type>
  </parameter>

  <query name="survey" defaultTableName="Survey">
    <query-result name="requireLogin"/>
    <query-result name="questionText"/>
    <query-parameter>
      <parameter-value>surveyID</parameter-value>
    </query-parameter>
    <body>
      <query-string>SELECT * FROM Survey Where id = ?</query-string>
    </body>
  </query>

  <link name="results">
    <page-ref page="survey-results"/>
    <url-parameter name="surveyID">
      <parameter-value>surveyID</parameter-value>
    </url-parameter>
  </link>

In this example, which is taken from the SurveySite example, the surveyID parameter serves 2 funtions: it is used as a query parameter to return the text of the survey question, and it is also used to populate the surveyID url-parameter in a link to the survey-results page.

The body content (#PCDATA, in DTD terms) should be the name of a parameter of the same page.

Element `session-value`

Used to reference a value which is stored in the user's server-side HttpSession. These values are stored in the session using the HttpSession#setAttribute method, typically by a server-side bean. An example would be a bean that performs user authentication. When the user submits a valid userID and password to the login page, the user's ID can be stored in the session under the key userID. Then a session-value can be used to retrieve this value and use it in a page. For example, the user may be using a form to store a user preference on the server database. A session-value can be used to make sure that the userID value is available to the server-side bean which processes the form:

  <form name="update-preference" defaultTableName="Preferences">
    <form-element name="key"/>
    <form-element name="value"/>
    <form-element name="userID" hidden="true">
      <session-value key="userID"/>
    </form-element>
  </form>

**`session-value` attributes**
Name	Description	Required	Default Value
`key`	The key under which the value has been stored. The key will be supplied as the argument to the HttpSession#getAttribute method.	true

**`session-value` child elements**
Name	Description	MinOccurs	MaxOccurs
`type`	Optional specification of the data type of the session value. If the `type` is ommitted, the `session-value` will be treated as a String.	0	1

Element `form-value`

A value which is obtained from a form-element. Note that the form-value element will only produce sensible results if it is not used until after the form has been submitted. The most useful scenario for using a form-value is:

The user submits a form
The form is processed by a JSP page or servlet
The page or servlet redirects the request using a link which has a url-parameter whose value is a form-value

For example, the following is a fragment of a page in which the user is selecting which survey she wants to see results for. The choices would probably be rendered as a drop-down list. The choice that she makes for the surveyID form-value is used to populate the surveyID url-parameter for the survey-results page. Assume there is a query called surveys which returns the surveyIDs.

  <link name="survey-results">
    <page-ref page="survey-results"/>
    <url-parameter name="surveyID">
      <form-value form="choose-survey" element="surveyID"/>
    </url-parameter>
  </link>

  <form name="choose-survey">
    <form-element name="surveyID">
      <options>
        <query-value query="surveys" result="surveyID"/>
      </options>
    </form-element>
    <submit name="submit">
      <action>
        <redirect>
          <link-value ref="survey-results"/>
        </redirect>
      </action>
    </submit>
  </form>

**`form-value` attributes**
Name	Description	Required	Default Value
`form`	The name of the `form` which will provide the value	true
`element`	The name of the `form-element` which will provide the value	true

Element `literal-value`

A value which is specified directly in the site document. literal-value elements are typically used to provide values for hidden form-elements, and to supply default values for page parameters.

For example, a default surveyID of '0' could be specified for the survey-ask page:

  <parameter name="surveyID" required="true">
    <type><int/></type>
    <default>
      <literal-value><literal-text>0</literal-text></literal-value>
    </default>
  </parameter>

Note that even though the default data type of the literal-value is string, the parameter will coerce the value to an int.

**`literal-value` child elements**
Name	Description	MinOccurs	MaxOccurs
`type`	Optionally, the data `type` of the value. The default type is `string`.	0	1
`literal-text`	The value specified as #PCDATA	1	1

Element `link-value`

A value element whose value is obtained from a link.

**`link-value` attributes**
Name	Description	Required	Default Value
`ref`	The value of the 'ref' attribute should be the 'name' of a `link` defined on the same `page`.	true

Dovetail Site Document Reference

Contents

About

Testability

Generated Site Java Code

Running DoveTail2Java

The Site Class

The Page Classes

The Query Classes

Statically Compiling your JSP Pages

Index of Elements

Element site

Element location

Element page

Element parameter

Element type

Element default

Element link

Element query

Element query-result

Element body

Element custom-query

Element query-parameter

Element query-value

Element form

Element form-element

Element submit

Element action

Element action-bean

Element redirect

Element options

Element parameter-value

Element session-value

Element form-value

Element literal-value

Element link-value