OpenWGA 7.3 - OpenWGA Concepts and Features
Design and developmentWebTML
WebTML is a markup language developed for OpenWGA to define dynamic templates for HTTP publishing.
From a technical viewpoint WebTML is a "JSP Tag Library", a library of XML tags which can be used to enhance "Java Server Pages" with dynamic functionalities. Java Server Pages and JSP Tag Libraries are part of the Java Enterprise Edition Standard Platform.
The basic syntax of WebTML is therefor oriented at the predefined syntax of JSP tags, which itself is derived from XML tag syntax.
Facts about the overall WebTML XML syntax
- A WebTML tag consists of a start tag <tml:tag> and an end tag </tml:tag>, used in pairs.
<tml:range> </tml:range>
- Whatever is contained between start and end tag is the tag content. The tag content can consist of text or further WebTML tags that are child tags of the containing tag.
<tml:range> This is the tag content. Additional child tags may be specified here. </tml:range>
- A special syntax <tml:tag/> describes a tag with empty content. No end tag is needed/allowed here. It is semantically equal to <tml:tag></tml:tag> (without any content).
<tml:range> This is the tag content. Here is a tag <tml:item name="xyz"/> having no content, which is a child tag of the range. </tml:range>
It depends on the concrete tag if it supports or needs tag content. Some tags do not support content at all. Other tags need content and use it for an individual purpose.
- The names of all WebTML tags have the prefix "tml:". Tags without this prefix will not be interpreted as WebTML tag but rather as text (or tags of other JSP tag libraries which are not contained in OpenWGA). So you can safely use HTML tags inside WebTML. They will not get interpreted on the serverside:
<tml:range> Here is a paragraph. <p> Inside the paragraph </p>. After the paragraph. </tml:range>
- What follows the prefix is the WebTML tag name, which determines the concretely used tag and the functionality that this tag will perform. There is a wide variety of tags available documented in the WebTML tag reference. Here a small variety of the most frequently used tags:
<tml:item name="xyz"/> <!-- Puts out data items -->
<tml:meta name="xyz"/> <!-- Puts out metadata fields, which identify and describe documents and their status -->
<tml:navigator> ... </tml:navigator> <!-- Builds navigational structures -->
<tml:query> ... </tml:query> <!-- Performs database queries, used together with <tml:collection> and <tml:foreach> -->
<tml:url/> <!-- Generates URLs for various reasons. Most times these are URLs to content documents or to perform actions -->
<tml:case> <tml:if> <tml:then> <tm:elseif> <tml:else> <!-- Various tags that put out tag content only if a certain condition is met. Differ in the way conditions are tested. -->
<tml:range> ... <tml:range> <!-- Marks a certain range of code to perform various operations on it -->
- WebTML tags have to be cascaded correctly. A child tag must be closed before its containing tag is closed. Start tags without end tags or vice versa are syntax errors.
<tml:range> ... <tml:navigator> ... </tml:range> ... </tml:navigator> <!-- A cascading error -->
- WebTML tags have predefined attributes matching the syntax rules of XML tag attributes. The available attributes vary according to the concrete tag. They may be mandatory or optional for the individual tag. The names of all WebTML tags and attributes must be specified in lowercase. The values of all of these attributes MUST be enclosed in double brackets like attribute="value". Using an attribute that is not defined for the used tag is a syntax error.
<tml:item name="xyz" style="mystyle"/> <!-- Tag "item" does not know attribute "style", so this is a syntax error -->
- WebTML code is executed "top down". Included templates (via tag <tml:include>) are executed at the place of their inclusion.
<tml:item name="xyz"> <!-- Performed first -->
<tml:include ref="footer"/> <!-- Here the code of WebTML module "footer" is loaded and executed, as if the code stood here -->
Last changed: <tml:meta name="lastmodified" format="dd.MM.yyyy"/> <!-- Performed last -->
Facts about WebTML specific behaviour:
- Every WebTML tag has a tag result which normally is put out at the position of the tag. The output however can be suppressed (attribute output) and/or redirected into a variable (attribute var and others for other var types).
<tml:item name="xyz" var="theitem"/> <!-- Loads contents of item "xyz", but does not put it out but stores it into WebTML variable "theitem", for later usage on the page -->
- Every WebTML tag may have a tag id which should be unique among the whole WebTML page and by which the tag may be referenced from other tags. It is specified by attribute id which is available for all tags.
<tml:foreach id="searchresults">
...
</tml:foreach>
<tml:url type="nextpage" sourcetag="searchresults"/>
- While and after their processing WebTML tags offer so called tag infos, which is data about their execution. A tag info field has a name, identifying the concrete data, which is used to request the info from the tag. The available names are dependent on the concretely used WebTML tag. A tag needs to have an id to retrieve tag infos from it. Tag infos are retrieved in WebTML using <tml:taginfo>:
<tml:foreach id="searchresults">
...
</tml:foreach>
The currently displayed page is <tml:taginfo source="searchresults" name="currentpage"/> <!-- Retrieves tag info field "currentpage" from tag "searchresults", identifying the current displayed page of the results -->
Facts about WebTML code organisation in OpenWGA:
- WebTML code is organized in WebTML modules. These are text files that are stored in the design of an OpenWGA application. See WebTML modules in folder "tml" for details.
- WebTML modules are (at first) organized by media keys. The media key of a WebTML module determines the content type that the module output should produce.
- The choice which WebTML module is used to render the content of the request is determined by the request URL, either by the choice of the content document to display OR by a direct choice of WebTML module to render. See Content and Layout determination on Requests for details.
- The WebTML module that is used to render a request is called the outer layout. The outer layout module may include various other WebTML modules to complete its output. The complete output of the outer layout is called the WebTML page. See Inner and outer layout for more information.