XHTML module

Generate XHTML constructs easily

Page Contents

Basic usage
Setting attributes
Complex output
Output escaping
Generating the final output
Class listing

The most common task for a web application is to generate web pages. Anewt provides a convenient, programmable way to build valid XHTML Strict constructs. This module provides many classes and convenience methods to build XHTML constructs.

Basic usage

The classes and methods in this module closely resemble the elements available in XHTML. Each class corresponds to a XHTML element, and most XHTML elements have short-hand methods to generate class instances. The API is deliberately kept very simple, and closely matches the XHTML specification, so once you're used to the API, generating HTML should be just as fast as typing XHTML by hand, if not faster. Since this module builds on the classes in the xml module, all the XML goodies like output indenting and appending nodes to other nodes are available as well.

XHTML elements can be created by instantiating their corresponding classes directly, which is quite tiresome to type and quite hard to read, or they can be created by the ax_*() methods offered by this module. Both the constructor methods and the short-hand methods result in class instances (not strings) that can be manipulated afterwards, e.g. you can set attributes such as class or id after creating an element. The XHTML classes have names spelled out in full, e.g. AnewtXHTMLParagraph. On the other hand, the ax_*() methods use the element name directly after a ax_ function name prefix, e.g. ax_p(). This means that writing XHTML using the ax_*() methods is much more concise. See the example below:

Example 1: Creating a paragraph of text

// Building a paragraph using the class constructor:
$p = new AnewtXHTMLParagraph('This is some text');
 
// The same, but now using the convenience API:
$p = ax_p('This is some text.');

In exactly the same way, all other XHTML elements can be created.

Setting attributes

In addition to the basic ax_*() methods, several often-used cases, such as a paragraph of text with a class attribute, or a div block element with an id attribute, can be created with a single function call, e.g. ax_p_class() and ax_div_id(). An example:

Example 2: Generating output with attributes directly

// Results in <p class="foo">Paragraph text</p> when rendered
$p = ax_p_class('Paragraph text', 'foo');
 
// The same can be achieved like this:
$p = ax_p('Paragraph text');
$p->set_class('foo');
 
// Results in <div id="bar">Text here</div> when rendered
$p = ax_div_id('Text here', 'bar');
 
// The same can be achieved like this:
$div = ax_div('Text here');
$div->set_attribute('id', 'bar');
 
// Hyperlinks can be built like this:
$link = ax_a_href('Hyperlink text', 'http://anewt.net');
$link = ax_a_href_title('Hyperlink text',
    'http://anewt.net', 'This will be a tooltip');
 
// Images can be built like this:
$img = ax_img_src_alt('example.png', 'An example image');

Complex output

Elements can be easily nested:

Example 3: Creating nested elements

$div = ax_blockquote(ax_p('Some text in a blockquote.'));
 
$div = ax_blockquote(array(
    ax_p('Some text in a blockquote.'),
    ax_p('Another paragraph in the same blockquote.'),
    ));
 
$p = ax_p(array(
    'This is a ',
    ax_a_href('hyperlink', 'http://anewt.net'),
    ' inside some text.'));

Alternatively, if you don't want a wrapping element, you can use a XHTML fragment (AnewtXHTMLFragment) instead. Fragments can be transparently added to other elements or to AnewtPage instances.

Example 4: Building a fragment

/* Build a fragment containing a few paragraphs of text */
 
$paragraphs = array(
    ax_p('Paragraph one.'),
    ax_p('Paragraph two.'),
    ax_p('Paragraph three.'));
 
$fragment = ax_fragment($paragraphs);
 
$fragment->append_child(ax_p('Paragraph four'));

Another useful function is ax_sprintf(), which works like sprintf(), but handles XHTML elements, and returns an XHTML element with all content properly escaped:

Example 5: Building complex text output with format specifiers

$text_node_1 = ax_sprintf(
    'This is a %s inside some text',
    ax_a_href('hyperlink', 'http://anewt.net'));
 
$spice = 'Spice';
$text_node_2 = ax_sprintf(
    '%s & %s',
    ax_span_class('Sugar', 'sweet'),
    $spice);

Output escaping

All string content passed to the XHTML methods and class constructors is escaped by default. That means that you never need to worry about calling htmlspecialchars() on your strings to make sure special characters such as & and > don't cause trouble in the generated output.

In case you want to put a pre-formatted XHTML string inside an XHTML element, you have to use a raw text node. The AnewtXHTMLRaw class, which can also be created using the ax_raw() function, is used for this. The following example illustrates how to use it:

Example 6: Using raw strings as element content

// This will result in <a href="#">...</a> showing up in your browser:
$p = ax_p('This should be a <a href="#">hyperlink</a>, but it is not.');
 
// This will result in a functioning hyperlink:
$p = ax_p(ax_raw('This is a real <a href="#">hyperlink</a>.'));
 
// This is the same as the previous line of code:
$p = new AnewtXHTMLParagraph(new AnewtXHTMLRaw('This is a real <a href="#">hyperlink</a>.'));

Note that the content used as raw text should be a valid XHTML snippet for your page to be valid. Double-check that you did not make any typos or that you don't output untrusted input, since this may lead to cross-site scripting vulnerabilities!

Generating the final output

The AnewtPage available from the page module handles XHTML objects passed to the AnewtPage::append() and AnewtPage::append_to() methods just fine. Actually, many of the internal AnewtPage code uses functionality offered by the XHTML module internally when building the output.

Example 7: Adding XHTML elements to a page

anewt_include('page');
 
$p = new AnewtPage();
$p->append(ax_h1('Hello, world!'));
$p->append(ax_p('This is a simple test page.'));
$p->flush();

Of course it's not required to use the XHTML module in combination with the page module. XHTML object instances can be easily rendered to strings using the to_string() method:

Example 8: Rendering XHTML objects to a string

echo to_string(ax_div_id(
    ax_p('This is a paragraph of text wrapped in a div with an id attribute'),
    'this-is-the-div-id'));

Class listing

This module provides the following classes:

Back to the overview page