Forward Logo (image)       WebStringTemplates
      Previous Back Back Back Next

WebStringTemplates for the System Architect

As the System Architect, you need to specify what data will appear on each web page. This defines the interface between the Programmer and the Web Page Designer. This page defines the format for the Data Interface Definition file that is that interface. The file specifies what strings are available for inclusion in the web page, how they are to be used, what their names are and what their hierarchical structure is.

See WebStringTemplates for Web Page Designers for information on how to access these strings to include them in the web page output. See WebStringTemplates for Programmers for how to generate this data interface automatically from an existing JSP or servlet.

Data Interface Definition

The Data Interface Definition file uses standard HTML format and can be generated or edited by hand using any HTML editor that respects lists embedded within lists, as allowed by the HTML spec. Note: OpenOffice V1.1.0 does not respect lists within lists and should not be used to edit a Data Interface Definition file. Amaya V8.2 does respect lists embedded within lists.

Hierarchical Map - A Simple Example

The Data Interface Definition is defined as a hierarchical map consisting of sub-maps and lists. Each map element and each list is referenced by an attribute name.

Below is a small example of data map, displayed using the default style. (The horizontal line is not part of the map and is not mandatory). A more complex Data Interface Definition example is shown here


.comment
This is the overall comment for the data.
title.comment
The title for this web page. There are two versions available, short and long
title
short
User List
long
User List and the Currently Best Read Book
book.comment
This book attribute contains sub-attributes. It also has a string that will be returned $[book]$.
book
'WebStringTemplates for All' by Matthew Ford
description
A must read for web designers, architects and programmers.
first_name
Matthew
id
203
inventory
20
price
27.75
surname
Ford
title
WebStringTemplates for All
year
2004
users.comment
A list of users' names and ages. Lists cannot have a overall string specified for them.
users
  1. name
    John
    age
    39
  2. name
    Natasha
    age
    31
  3. name
    Fred
    age
    19
  4. name
    Mickey
    age
    51

Data Comments

You can use attributeName.comment to comment the data. These comment attributes cannot be accessed by the template but they will display in the Web Page Designers interactive development tool, RunWST. They are only for documenting the data. (No attribute with a '.' in its name can be accessed by the template.)

Data Attribute Names

Attribute names (i.e. the text inside the <dt> </dt> tags) should start with a _ (underscore) or . (dot) or letter (a..z A..Z) and then be followed by a letter or _ or . or digit (0..9). Any name that includes a '.' (dot) in it cannot be accessed by the Web Page Designer for inclusion in the output page. Hence the use of title.comment above to include a comment about the data.

Entries that contain a another definition list (<dl> </dl>) can also have an overall string defined, as shown in book above. The template referenece $[book]$ will return
'WebStringTemplates for All' by Matthew Ford
while $[book.title]$ returns
WebStringTemplates for All

View the source of this page to see where to insert this overall string. For example of a definition list in-side a list item (<li>) look at this definition file.

If the overall string is just white space, as in title above, then is it assumed to be indeterminate. That is the Web Page Designer cannot tell what charaters will be returned by the template reference $[title]$, other than that some string will be returned. Often what is returned by the server during deployment is some low level description of a Java object. So $[title]$ should not be used as an output string in the web page design. Instead use either $[title.short]$ or $[title.long]$. $[title]$ can be used an argument to as sub-template.

Ordered/unorderd list (<ol> </ol>, <ul> </ul>) cannot have an overall string defined for them.

Lists Elements should have the same structure and hold all the associated data

While not mandatory, all elements of a list usually have the same structure and attribute names. For example, in the above list of users each list item is a map containing a name and age.

Because of the way WebStringTemplates processes lists of data, all data associated with an element of a list should appear with that element in the list. For example, instead of having a list of ages and a list of names, the age data should be in the same element as the name data to form a list of person elements, as shown above. In general, WebStringTemplates cannot co-ordinate the processing of more then one list at a time.

Missing Data

The Data Interface Definition file should have all the data required for the Web Page Designer. The RunWST interactive development tool will return an error path if any data is missing. This error return string is suppressed by default when WebStringTemplates is deployed so that data need not be defined at run time, if it is not needed.

In any case, an $[if( )]$ statement should be used in the template to test if data is available.

In the Data Interface Definition file you need to specify what the data is and under what conditions it will be available. This can be handled by supplying two or more Data Interface Definition files to cover the various cases. In those files where the data is missing, just include an empty entry for the data attribute that will be used in the $[if( )]$ test. This will evaluate as false. In deployment, the missing data will also evaluate as false.

See secondAttribute.firstEntry element No 2 blankItem in the example definition file for an example of an empty data entry. Because leading and trailing white space is trimmed from the data before use, a blank entry of spaces is the same as an empty entry, both evaluate to false in an $[if( )]$ statement.

Internationalization (i18n)

All Data Interface Definition files (and templates) are read in assuming the ISO-8859-1 (ISO-Latin-1) character set, with any character not in this character set needs to be represented as an escaped Unicode (i.e. \udddd) sequence. Data Interface Definition files written out by an existing servlet or JSP will be written assuming the ISO-8859-1 character set with any character not in this character set be written out in escaped Unicode. The native2ascii tool that is supplied with Java Software Development Kit can be used to translate between native encodings and this encoding scheme.

In deployment, the template output is passed to the web server output stream as Unicode characters (not \udddd escaped) and it is left to the output stream to encode the characters in a suitable form for the client browser. This encoding is normally automatic, if the client encoding has been set correctly.

Tags used for defining the data map

The Data Interface Definition data maps can only use the following tags to define the structure. Any other tags found inside the data map are passed though unchanged as part of the data (but see below for the escape sequence). Outside the data map all tags may be used.

A Definition List, <dl> </dl>, defines a map, Ordered and Unordered Lists define a list. You can nest maps and lists inside each other. The top level must be a map (Definition List).

Only the first Definition List is processed

Only the first top level definition list in a Data Interface Definition file is processed. Any later top level definition lists will be ignored (but a warning will be given).

Data Definition Files for Default Data

WebStringTemplates will load data definition files at the server side to pre-load default data for the template. This allows you to put large chunks of pre-formatted and/or foreign language text into data attributes without having to clutter up the server code.

Leading and trailing white space trimmed

The data has leading and trailing whitespace trimmed before handing it to the page template. If you want leading or trailing space use &nbsp;

No translations performed

No HTML Entity translations are performed on the data read from the data interface definition. That means &nbsp; inside the data map will be read in as the 6 characters &nbsp; and supplied to the Web Page Designer or server template as 6 characters. It is up to the Programmer to do any translations necessary before passing the data on to the Web Page Designer or server template. However any Unicode escape sequences (\udddd) are automatically transformed back into their respective Unicode character when data read in is stored internally.

How to escape lists in data

If you want to load data which includes a definition list (<dl> </dl>) or an ordered (<ol> </ol> or unorder list (<ul> </ul>), you need to escape the data using the tags <wst> </wst> to prevent these list tags from interfering with parsing of the data structure.

Any text between the <wst> </wst> tags will be passed through to the template unchanged (except for transforming Unicode escape sequences). See the sample.data.html fourthAttribute for an example.

When the Programmer uses WebStringTemplate to output a Data Interface Definition file, <wst> </wst> are automatically inserted around every data item so that the data strings will be read back in exactly as output.

When editing the Data Interface Definition file by hand, if you ever need to put the character sequence </wst> into a data item then use the character sequence \u003C/wst> instead. Due to the Unicode escape encoding used for non ISO-8859-1 characters, you need to escape any \ characters by replacing them with \\ when editing by hand. Both the </wst> and the \ escaping is done automatically when WebStringTemplates is used to output a Data Interface Definition file.

See the Web Page Designer Escape Sequences for escape sequences used in template statements.

All text outside the map is ignored

All the text in the Data Interface Definition file that is outside the data map is ignored. Typically you would put explanatory notes about the data here. Although you are encouraged to use .comment in the data to document the data.

Data Definition Stylesheet

By default this style is used to display the Data Definition map. Although you can use any style you wish or none as you please.



Forward Logo (image)       WebStringTemplates
      Previous Back Back Back Next

Contact Forward Computing and Control by
ęCopyright 2004 Forward Computing and Control Pty. Ltd. ACN 003 669 994