Previous
Next |
WebStringTemplates Previous Next |
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.
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.
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
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.)
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.
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.
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.
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.
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).
The data has leading and trailing whitespace trimmed before handing it to the page template. If you want leading or trailing space use
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 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.
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.
|
WebStringTemplates Previous Next |