Web Application Extension Service
Author: Amaury Darsch

| Web Application Extension Service

Web Application Extension Service

This chapter covers the fundamental objects of the web application extension (wax) service. This service provides the support for low level HTTP transaction as well as high level XHTML page generation and CGI scripts execution.

Page service objects

The `XhtmlRoot` class is the primary interface to generate xhtml page. The class is derived from the `XmlRoot` class and the `Mime`object. for this reason, creating a xhtml page is equivalent to add xml nodes to the page. The xhtml version is assumed to be 1.1.

Page creation

The `XhtmlRoot` constructor takes a string argument which is the title page. When the root page is created, a head and body nodes are automatically created. Once created, it is possible to retrieve the head and body nodes from the root node. The head and body nodes are part of the html node which is automatically instantiated as a `XhtmlHtml` object. The html node can always be retrieved from the root node with the `get-child` xml method.

The head and body nodes are part of the html node which is automatically instantiated as a `XhtmlHtml` object. The html node can always be retrieved from the root node with the `get-child` xml method. The root methods `get-head` and `get-body` are convenient methods that ease the page design by eliminating the references to the html node.

Page header

The `XhtmlHead` class is the xml node that handles the xhtml head. The object is automatically created when calling the `XhtmlRoot` constructor. During the construction process, the head is automatically set with a title. Once created, the head can be filled with meta information and styles. The `add-meta` method is designed to add meta information, while the `add-style` add a link node with a style reference to the head.

The `add-meta` method adds a `XhtmlMeta` object which is a xml tag node. The first argument is the meta descriptor while the second argument is the meta content. Note that the `add-meta` method can be simulated by calling the `XhtmlMeta` constructor and then adding the node to the head node.

The `add-style` method adds a `XhtmlStyle` object which is a xml tag node. The string argument is the url style sheet path which gets automatically transformed to the form @import(url). Note that the `add-style` method can be simulated by calling the `XhtmlStyle` constructor and then adding the node to the head node.

Page body

The `XhtmlBody` class is the xml node that handles the xhtml body. The object is automatically created when calling the `XhtmlRoot` constructor. Once created, the body node can be filled with any valid xhtml node. Since the node are initially xml tag node, it is always possible to create a tag by name and set the attributes and child nodes manually.

Page emission

Since the `XhtmlRoot` object is a xml root node, the node can be used to write the complete hierarchy. The xml node node provides the `write` method that write a xml tree into a buffer of an output stream.

Another mechanism for writing the page is to use the fact that the `XhtmlRoot` class implements also the `Mime` interface. With this in mind, the `XhtmlRoot` can be used within the `HttpReply`. This method is particularly useful when writing automated page generation, such like CGI scripts.

Page design objects

The wax service module is designed to provide several object that ease the task of creating a xhtml page. Such objects range from comment to table. Most of the time, the construction is simple the resulting node only need to be added to the page tree. When it comes to add text, the problem is becoming more subtle and is discussed later in this section.

Comment node

Adding a comment is done with the `XmlComment` class which take the comment string in the constructor. Once created, the comment node can be added to the tree.

Node style class

When the xhtml page is combined with the cascaded style sheet (CSS), the xhtml node tag often uses a class name to refer to a particular style. The class style is just a node attribute which can be set with the `add-attribute` method. However, most of the time, the library provides object which have the style as the first argument in the constructor. For example, the `XhtmlDiv` constructor take 0 or one argument. With one argument, the string argument is used as the style attribute.

Adding text paragraph

Adding text to a page is not a trivial task when it comes to deal with text style. By default, a piece of text is stored in the `XmlText` node. Using this node is easy. However, in a programming context, its use can become heavy. For this reason, all xml nodes provide the `parse` method which can be used to add a xml tree to the calling node. When it comes to add text that includes rendering tag, this method is quite handy.

The `XhtmlPara` node is the preferred node for adding text to a xhtml page. The node takes optionally the style name in the constructor. A boolean flag can also be used to create an empty paragraph node.

Adding reference

Adding reference or hyperlink to a page is achieved with the `XhtmlRef` class. Most of the time, the object is built with a uri and a text. when the node has been created, the node can be added to the page tree.

Formatting elements

The `XhtmlDiv` and `XhtmlHr` classes are the basic formatting xhtml elements. The `XhtmlDiv` is a grouping element and the `XhtmlHr` is a simple horizontal ruler element. Both classes take 0 or one argument which is the style name.

Managing table

The wax service module provides an extensive support of he xhtml table element. There are basically two strategies for creating a table. One is to use the html elements or the other is to use a print table object and automatically feed the xhtml table. The first method provides a better control while the second one is easier to use.

The table element

The `XhtmlTable` class is the class that manages xhtml table. As usual, a default style name can be specified in the constructor. Eventually, a default table row and table data default style can also be specified. Such default value are used when creating a new row with the `new-row` method.

In the previous example, a table is created with a default style for the table row. When a new row is created, the default style is used for that row. If there is no default style, the row is created without a style. Note that the `new-row` method takes also a style argument that overwrites the default one.

Building the table

A table is built by adding row and data element into the rows. A row is created with the `new-row` method or the object can be constructed directly and added to the node with the `add-child` method. The `XhtmlTr` class is the table row class.

When a row has been created, the data can be added to the row. Normally, the `new-data` method is used to create a new table data element. If a default style is defined in the table row, the table data element is built with that style. The `new-head` method can also be used to create table header element. Again, if a default table header style exists in the table row, the element is built with that style. The `XhtmlTd` class is the table data class and the `XhtmlTh` class is the table header class.

When the table data node has been created, the `parse` method or the `add-child` method can be called to add other nodes. another method for building the table is to use the `add-table` method which uses a print table object. In such case, the table rows and data elements are automatically added in the table.

The table structure

The table can be designed directly with table rows with table headers and table data elements. Another method, which is more structured is to use the table head, table body and table footer elements. The `XhtmlThead` class is the table head element class. The `XhtmlTbody` class is the table body element class. The `XhtmlTfoot` class is the table footer element class. These classes behaves exactly like the `XhtmlTable` and are in fact all derived from the `XhtmlTelem` class.

A table caption node can also be set with the `set-caption` method. The method simply creates a `XhtmlCaption` node and adds it to the table. The caption text is part of the method call which is used by the caption node constructor. It is also possible to create the caption node by calling the `XhtmlCaption` constructor and adding it to the table with he `add-child` method.

The table structure can also be defined with the `XhtmlCgr` class which corresponds to the xhtml column group element. The column group element is designed to support the col element that formats the table column.

Web Application Extension service reference

This appendix is a reference of the web application extension (wax) service.

XhtmlRoot

The `XhtmlRoot` class is a xml root node used for the design of a xhtml document page. At construction, the root node is initialized with a default xml processing instruction, and xhmtl node with head and body The head and body nodes can be used to add more nodes in order to build the document. The construction argument is the page title.

Predicate

    xhtml-root-p

Inheritance

    XmlRoot
    Mime

Constructors

XhtmlRoot (String)

The XhtmlRoot constructor creates a default xhtml page with a head and a body. The head node is set with the string title argument.

Methods

get-head (→ XhtmlHead) (none)

The get-head method returns the xhtml head node.

get-body (→ XhtmlBody) (none)

The get-body method returns the xhtml body node.

XhtmlHtml

The `XhtmlHtml` class is a xhtml html node used for the design of a xhtml document page. At construction, the html node is initialized with a head node and a body node. Because a valid xhtml document must contain a title the constructor takes at least a title argument.

Predicate

    xhtml-html-p

Inheritance

    XmlTag

Constructors

XhtmlHtml (String)

The XhtmlHtml constructor creates a default xhtml html node with a head and a body. The head node is set with the string title argument.

Methods

get-head (→ XhtmlHead) (none)

The get-head method returns the xhtml head node.

get-body (→ XhtmlBody) (none)

The get-body method returns the xhtml body node.

XhtmlHead

The `XhtmlHead` class is a xhtml head node used for the design of a xhtml document page. At construction, the head node is initialized with a with a title node. The class is designed to hold as well meta nodes and style nodes.

Predicate

    xhtml-head-p

Inheritance

    XmlTag

Constructors

XhtmlHead (String)

The XhtmlHead constructor creates a default xhtml head node with a title. The string argument is the head title.

Methods

add-meta (→ none) (String String)

The add-meta method adds a XhtmlMeta node to the head node. The first argument is the meta descriptor. The second argument is the meta contents.

add-style (→ none) (String)

The add-style method adds a XhtmlLink node to the head node. The string argument is the style url path. The link node is automatically configured to reference a 'text/css' mime type.

XhtmlBody

The `XhtmlBody` class is a xhtml body node used for the design of a xhtml document page. The class is designed to be filled with other xhtml nodes.

Predicate

    xhtml-body-p

Inheritance

    XmlTag

Constructors

XhtmlBody (none)

The XhtmlBody constructor creates a default xhtml body node.

XhtmlTitle

The `XhtmlTitle` class is a xhtml title node used in the head node.

Predicate

    xhtml-title-p

Inheritance

    XmlTag

Constructors

XhtmlTitle (String)

The XhtmlTitle constructor creates a xhtml title node. The string argument is the title value. The title node is designed for the XhtmlHead class.

Methods

set-title (→ none) (String)

The set-title method set the node title by value.

XhtmlMeta

The `XhtmlMeta` class is a xhtml meta node used in the head node. The meta data node is an empty node with two attributes which are the descriptor and content value. The meta data is stored internally as a xml attribute.

Predicate

    xhtml-meta-p

Inheritance

    XmlTag

Constructors

XhtmlMeta (String String)

The XhtmlMeta constructor creates a xhtml meta node with a descriptor name and content value. The first argument is he descriptor name which is used as the node attribute name. The second argument is the content vale which is the attribute value.

XhtmlLink

The `XhtmlLink` class is a xhtml link node used in the head node. The link node is an empty node with several attributes. The most important one is the 'href' attribute that specifies the link uri. Other attributes like 'type' or 'rel' can also be set at construction.

Predicate

    xhtml-link-p

Inheritance

    XmlTag

Constructors

XhtmlLink (String)

The XhtmlLink constructor creates a xhtml link node by reference. The first argument is the link reference.

XhtmlLink (String String)

The XhtmlLink constructor creates a xhtml link node by reference and type. The first argument is the link reference. The second argument is the link type. The link type is defined as a mime type.

XhtmlLink (String String String)

The XhtmlLink constructor creates a xhtml link node by reference, type and relation. The first argument is the link reference. The second argument is the link type. The link type is defined as a mime type. The third argument is the link relation.

XhtmlStyle

The `XhtmlStyle` class is a xhtml style node used in the head node. The style node is built with a xml text node that holds the formatted url string.

Predicate

    xhtml-style-p

Inheritance

    XmlTag

Constructors

XhtmlStyle (String)

The XhtmlStyle constructor creates a xhtml style node with a url path. The string argument is the url path of the style sheet file.

XhtmlScript

The `XhtmlScript` class is a xhtml script node used in the head and body node. The script node is built with a xml tag node that holds the script content. Sometimes it is recommended to place the script inside a CDATA node that is stored as a child node of the script node. A boolean flag controls this feature at construction.

Predicate

    xhtml-script-p

Inheritance

    XmlTag

Constructors

XhtmlScript (String)

The XhtmlScript constructor creates a xhtml script node with a type. The string argument is the mime type string such like 'text/javascript'.

XhtmlScript (String Boolean)

The XhtmlScript constructor creates a xhtml script node with a type and a CDATA node control flag. The first argument is the mime type string such like 'text/javascript'. The second argument is the CDATA node control flag. If the flag is true, all scripts attached to the node are placed into a 'CDATA' node.

XhtmlScript (String String)

The XhtmlScript constructor creates a xhtml script node with a type and a url. The first argument is the mime type string such like 'text/javascript'. The second argument is the script source url.

XhtmlPara

The `XhtmlPara` class is a xhtml paragraph node used in the body element of a xhtml page. The paragraph node can be created with a style name or as an empty node.

Predicate

    xhtml-para-p

Inheritance

    XmlTag

Constructors

XhtmlPara (none)

The XhtmlPara constructor creates a default xhtml paragraph node.

XhtmlPara (String)

The XhtmlPara constructor creates a xhtml paragraph node with a style. The string argument is the style name.

XhtmlPara (Boolean)

The XhtmlPara constructor creates an empty xhtml paragraph if the boolean argument is true.

XhtmlEmph

The `XhtmlEmph` class is a xhtml emphasize node used in the body element of a xhtml page. The emphasize node can be created with a style name.

Predicate

    xhtml-emph-p

Inheritance

    XmlTag

Constructors

XhtmlEmph (none)

The XhtmlEmph constructor creates a default xhtml emphasize node.

XhtmlEmph (String)

The Xhtmlemph constructor creates a xhtml emphasize node with a style. The string argument is the style name.

XhtmlRef

The `XhtmlRef` class is a xhtml reference node used in the body element of a xhtml page. The node can be used to create hyperlink that references object by a uri.

Predicate

    xhtml-ref-p

Inheritance

    XmlTag

Constructors

XhtmlRef (none)

The XhtmlRef constructor creates a default xhtml reference node.

XhtmlRef (String)

The XhtmlRef constructor creates a xhtml reference node with a uri. The string argument is the uri to use.

XhtmlRef (String String)

The XhtmlRef constructor creates a xhtml reference node with a uri and a reference text. The first argument is the uri. The second argument is the reference text.

XhtmlImg

The `XhtmlImg` class is a xhtml image node used in the html body. The image node is an empty node with several attributes including the image source, the image width and height and an alternate string.

Predicate

    xhtml-img-p

Inheritance

    XmlTag

Constructors

XhtmlImg (String String)

The XhtmlImg constructor creates a xhtml image node by source and alternate name. The first argument is the image uri. The second argument is the alternate name.

Methods

set-width (→ none) (String)

The set-width method set the image width attribute.

set-height (→ none) (String)

The set-height method set the image height attribute.

set-geometry (→ none) (String)

The set-geometry method set the image width and height attribute in one call.

XhtmlDiv

The `XhtmlDiv` class is a xhtml div node used in the body element of a xhtml page. The div node is a xhtml grouping element.

Predicate

    xhtml-div-p

Inheritance

    XmlTag

Constructors

XhtmlDiv (none)

The XhtmlDiv constructor creates a default xhtml div node.

XhtmlDiv (String)

The XhtmlDiv constructor creates a xhtml div node with a style. The string argument is the style name.

XhtmlPre

The `XhtmlPre` class is a xhtml pre node used in the body element of a xhtml page. The pre node is a xhtml formatting element.

Predicate

    xhtml-pre-p

Inheritance

    XmlTag

Constructors

XhtmlPre (none)

The XhtmlPre constructor creates a default xhtml pre node.

XhtmlPre (String)

The XhtmlPre constructor creates a xhtml pre node with a style. The string argument is the style name.

XhtmlHr

The `XhtmlHr` class is a xhtml hr node used in the body element of a xhtml page. The hr node is a xhtml horizontal ruler element.

Predicate

    xhtml-hr-p

Inheritance

    XmlTag

Constructors

XhtmlHr (none)

The XhtmlHr constructor creates a default xhtml hr node.

XhtmlHr (String)

The XhtmlHr constructor creates a xhtml hr node with a style. The string argument is the style name.

XhtmlCgr

The `XhtmlCgr` class is a xhtml column group node used in the table element. The column group is designed to hold the column definition bound by the `XhtmlCol` class.

Predicate

    xhtml-cgr-p

Inheritance

    XmlTag

Constructors

XhtmlCgr (none)

The XhtmlCgr constructor creates a default xhtml colgroup node.

XhtmlCol

The `XhtmlCol` class is a xhtml column node used in the table column group element.

Predicate

    xhtml-col-p

Inheritance

    XmlTag

Constructors

XhtmlCol (none)

The XhtmlCol constructor creates a default xhtml col node.

XhtmlCol (String)

The XhtmlCol constructor creates a xhtml col node with a string width argument. The argument is the width attribute value.

XhtmlTh

The `XhtmlTh` class is a xhtml th node used in the table row. The object can be built with a style name.

Predicate

    xhtml-th-p

Inheritance

    XmlTag

Constructors

XhtmlTh (none)

The XhtmlTh constructor creates a default xhtml th node.

XhtmlTh (String)

The XhtmlTh constructor creates a xhtml th node with a style. The string argument is the style name.

XhtmlTd

The `XhtmlTd` class is a xhtml td node used in the table row. The object can be built with a style name.

Predicate

    xhtml-td-p

Inheritance

    XmlTag

Constructors

XhtmlTd (none)

The XhtmlTd constructor creates a default xhtml td node.

XhtmlTd (String)

The XhtmlTd constructor creates a xhtml td node with a style. The string argument is the style name.

XhtmlTr

The `XhtmlTr` class is a xhtml tr node used in the table node. The table row node is designed to accumulate table head or table data nodes.

Predicate

    xhtml-tr-p

Inheritance

    XmlTag

Constructors

XhtmlTr (none)

The XhtmlTr constructor creates a default xhtml tr node.

XhtmlTr (String)

The XhtmlTr constructor creates a xhtml tr node with a style. The string argument is the style name.

XhtmlTr (String String)

The XhtmlTr constructor creates a xhtml tr node with a style and a default table data style. The string argument is the table row style name. The second argument is the default table data style.

Methods

new-head (→ XhtmlTh) (none | String)

The new-head method returns a new table head data object. Without argument, a default XhtmlTh object is created. With a string argument, the XhtmlTh object is constructed with a style name.

new-data (→ XhtmlTd) (none | String)

The new-data method returns a new table data object. Without argument, a default XhtmlTd object is created. With a string argument, the XhtmlTd object is constructed with a style name.

set-head-class (→ none) (String)

The set-head-class method sets the default table head style. The default style is use with the new-head method.

set-data-class (→ none) (String)

The set-data-class method sets the default table data style. The default style is use with the new-data method.

set-xdef-class (→ none) (String)

The set-xdef-class method sets the default table head and data style. The default style is use with the new-head and new-data methods. This method combines the set-head-class and the set-head-class

XhtmlTelem

The `XhtmlTelem` class is an abstract class that implements the node behavior for the table head, body, foot and table elements. The table element node is designed to accumulate table row nodes. This class cannot be constructed directly.

Predicate

    xhtml-telem-p

Inheritance

    XmlTag

Methods

new-row (→ XhtmlTr) (none | String)

The new-row method returns a new table row object. Without argument, a default XhtmlTr object is created. With a string argument, the XhtmlTr object is constructed with a style name.

add-table (→ none) (PrintTable)

The add-table method adds a print table into the table element by adding automatically the row and the associated formatting information such like the data direction.

set-xrow-class (→ none) (String)

The set-xrow-class method sets the default table row data style. The default row style is use with the new-row method.

set-xdef-class (→ none) (String)

The set-xdef-class method sets the default table head and data style. The default style is use with the new-row method to set the table head and data default style.

XhtmlThead

The `XhtmlThead` class is a xhtml thead node. The table head node is designed to accumulate table rows nodes. The class acts almost like the xhtml table class.

Predicate

    xhtml-thead-p

Inheritance

    XhtmlTelem

Constructors

XhtmlThead (none)

The XhtmlThead constructor creates a default xhtml table head node.

XhtmlThead (String)

The XhtmlThead constructor creates a xhtml table head node with a style. The string argument is the style name.

XhtmlThead (String String)

The XhtmlThead constructor creates a xhtml table head node with a style and a default table row style. The string argument is the table head style name. The second argument is the default table row style.

XhtmlThead (String String String)

The XhtmlThead constructor creates a xhtml table head node with a style, a default table row style and a default table data style. The string argument is the table head style name. The second argument is the default table row style. The third argument is the table data style.

XhtmlTbody

The `XhtmlTbody` class is a xhtml tbody node. The table body node is designed to accumulate table rows nodes. The class acts almost like the xhtml table class.

Predicate

    xhtml-tbody-p

Inheritance

    XhtmlTelem

Constructors

XhtmlTbody (none)

The XhtmlTbody constructor creates a default xhtml table body node.

XhtmlTbody (String)

The XhtmlTbody constructor creates a xhtml table body node with a style. The string argument is the style name.

XhtmlTbody (String String)

The XhtmlTbody constructor creates a xhtml table body node with a style and a default table row style. The string argument is the table body style name. The second argument is the default table row style.

XhtmlTbody (String String String)

The XhtmlTbody constructor creates a xhtml table body node with a style, a default table row style and a default table data style. The string argument is the table body style name. The second argument is the default table row style. The third argument is the table data style.

XhtmlTfoot

The `XhtmlTfoot` class is a xhtml tfoot node. The table foot node is designed to accumulate table rows nodes. The class acts almost like the xhtml table class.

Predicate

    xhtml-tfoot-p

Inheritance

    XhtmlTelem

Constructors

XhtmlTfoot (none)

The XhtmlTfoot constructor creates a default xhtml table foot node.

XhtmlTfoot (String)

The XhtmlTfoot constructor creates a xhtml table foot node with a style. The string argument is the style name.

XhtmlTfoot (String String)

The XhtmlTfoot constructor creates a xhtml table foot node with a style and a default table row style. The string argument is the table foot style name. The second argument is the default table row style.

XhtmlTfoot (String String String)

The XhtmlTfoot constructor creates a xhtml table foot node with a style, a default table row style and a default table data style. The string argument is the table foot style name. The second argument is the default table row style. The third argument is the table data style.

XhtmlTable

The `XhtmlTable` class is a xhtml table node. The table node is designed to accumulate table row nodes or column group nodes. The table can also be designed with a table head, body and foot nodes.

Predicate

    xhtml-table-p

Inheritance

    XhtmlTelem

Constructors

XhtmlTable (none)

The XhtmlTable constructor creates a default xhtml table foot node.

XhtmlTable (String)

The XhtmlTable constructor creates a xhtml table foot node with a style. The string argument is the style name.

XhtmlTable (String String)

The XhtmlTable constructor creates a xhtml table foot node with a style and a default table row style. The string argument is the table foot style name. The second argument is the default table row style.

XhtmlTable (String String String)

The XhtmlTable constructor creates a xhtml table foot node with a style, a default table row style and a default table data style. The string argument is the table foot style name. The second argument is the default table row style. The third argument is the table data style.

Methods

set-caption (→ none) (String)

The set-caption method sets the table caption. A new XhtmlCaption node is automatically added to the table tree during this method call.

Web application extension service reference

XmlMime

The `XmlMime` class is a generic xml mime document class. The class is used to construct a mime version of a xml document which can be obtained from a file name, or an input stream. By default, the mime type 'application/xml'.

Predicate

    xml-mime-p

Inheritance

    XmlDocument
    Mime

Constructors

XmlMime (none)

The XmlMime constructor creates a default xml mime document.

XmlMime (String)

The XmlMime constructor creates a xml mime document by parsing a file. The file name is the string argument.

XmlMime (String InputStream)

The XmlMime constructor creates a xml mime document by name and by parsing the input stream. The first argument is the xml document name. The second argument is the input stream to parse.

XhtmlMime

The `XhtmlMime` class is a generic xhtml mime document class. The class is used to construct a mime version of a xhtml document which can be obtained from a file name, or an input stream. By default, the mime type 'application/xhtml+xml'.

Predicate

    xhtml-mime-p

Inheritance

    XmlMime

Constructors

XhtmlMime (none)

The XhtmlMime constructor creates a default xhtml mime document.

XhtmlMime (String)

The XhtmlMime constructor creates a xhtml mime document by parsing a file. The file name is the string argument.

XhtmlMime (String InputStream)

The XhtmlMime constructor creates a xhtml mime document by name and by parsing the input stream. The first argument is the xhtml document name. The second argument is the input stream to parse.