Xport Usage: XHTML Generation

Xport's primary purpose is to generate xhtml documents. Xport does this in a very intuitive and robust way. The document object contains the complete xhtml document structure. The document object is very easy to create and manipulate. The document object can be considered a root document, in which case the document will contain the html, head, and body elements. Or the document object could contain xhtml elements which are not contained in these root elements. This would make the xhtml document mal-formed, but would be acceptable to use in documents which are used in frames, or to be included in root documents in some other manner, as in server side includes, or php includes.

As explained in the usage overview, there are only a handful of types you need to use to generate xhtml documents. In the following examples, we will be demonstrating Xport's functionality using xhtml strict document types.

The first step in creating an xhtml document is to create the document object. This is illustrated below. In the first document construction, a root document is created, and in the second line, a non-root document is created.

using namespace Xport;
// create a root document called 'doc'
document doc(root_doc);

// create a non-root document
document doc2;

Once the document object is created, it can be populated by inserting markup (elements, pcdata, comments, processing instructions, etc). The snippet below illustrates how to insert markup using the insert() operation. The insert() operation returns an iterator to the inserted object, which can be handy to use for inserting more content, or other reasons. In the examples, you'll notice that the document object contains two very handy operations, head() and body(). These two operations return a pointer to the documents head element and body element, respectively. If the document doesn't contain these elements, NULL is returned.

The links below show a code snippet for creating a simple document, and the resulting document and document source.

View code snippet

View document source

View document results

Notice in the code snippet above that the when inserting a title element into the head element, that the title enumerator was fully qualified by resolving the enumerator to it's namespace, Xport. This is necessary, because the symbol title is declared as a tag enumerator, and as a attribute enumerator, as explained in Enumerations .

When viewing the document source of the code snippet above, notice that the paragraph content is not wrapped, and extends the complete length of the content on a single line. When calling document::write(), the document uses a default formatter object, which does not wrap long lines. In our next example, we will create a formatter object to write the document, and specify a maximum line length.

There are other methods besides the insert() operation to add content to the document. The insert() method is handy to use when you need an iterator returned. If you don't really need an iterator to the newly inserted element, however, it may be more benificial to use the insertion operator to add content to the document. The code below performs the same insertions as the previous code block, but uses an insertion operator to replace many of the insert() operations used in the previous code snippet. A couple of the insert() operations will be left alone however, because it is handy to operate on the returned iterator. It is possible, however, as shown in the revised code snippet, to use the insertion operator on an iterator, which can be very handy indeed.

View revised code snippet

View revised document source

View revised document results

As shown in the revised code snippet, the most efficient method of inserting content into a document object is to use both the insert() operation and the inserter operator. Which method is used will depend on the need of a returned iterator pointing to the inserted element. Comparing the source documents of the code snippets above, also reveals that it's best to use a formatter object to format the document's output, rather than accept the default formatter object used when calling document::write(). Notice the results of the document are the same for each snippet, although the document source is formatted much nicer in the revised code snippet.

The examples above illustrate the basic methods of creating and adding content to xhtml documents. There are many more ways available in Xport, which are detailed in the examples. You can also review Xport's claas interface for details of every operation of each interface type.

To see how to add content formatting to this sample document with Xport's stylesheet features, see stylesheet generation.