Documentation home Table of contents Module index Class index

Page module

Module for building XHTML pages

Back to the overview page

The most common task for a web application is to generate web pages. Anewt provides a convenient, programmable way to build valid XHTML Strict pages. This module provides the AnewtPage class which allows you to build valid XHTML pages easily.

Basic usage

The AnewtPage class provides an abstraction of an XHTML document, with many of the standard parts such as the title available as easy-to-use properties. Before going into details, this trivial example shows how to output an empty page:

anewt_include('page');
 
$p = new AnewtPage();
$p->title = 'This is the title of the page';
$p->flush();

In addition to title, several other properties can be set on an AnewtPage instance:

title

The title of the page

favicon

The uri of the favicon of the page. Optional, defaults to null.

show-dublin-core

Whether to include Dublin Core metadata. Enabled by default.

language

The main language of the page. Defaults to en.

description

A description of the page (optional)

creator

Creator of the page (optional)

date

The date of the page as a AnewtDateTimeAtom instance. Optional, defaults to the current date.

generator

The generator string used. Defaults to Almost No Effort Web Toolkit (Anewt). Set this to null to disable the generator <meta> tag.

robots

The value for the robots <meta> tag. Defaults to null, which means no robots <meta> tag will be included. Valid values look like this: index, nofollow.

base-uri

The base uri of the page. Defaults to null, which means no <base> element will be included.

Simple and block-based pages

AnewtPage allows you to build two slightly different and mutually exclusive page types: simple pages and block-based pages.

Simple pages, as the name suggests, allow you to build simple pages by setting some properties and adding some content, added using the AnewtPage::append() method. When the page is rendered all content is output in a linear fashion. The following code gives an example:

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

Block-based pages, on the other hand, use several blocks which are output as div elements with an id, so they can be easily styled using stylesheets. Therefore you should provide a list of blocks to render using the blocks property. Use the AnewtPage::append_to() method to add content to a specific block, or call AnewtPage::append() to add content to the default block (this only works if you specified a default block by setting the default-block property). When the page is rendered, the blocks are output in the order they are specified in the blocks property.

blocks

Array of block names, e.g. array('header', 'content', 'footer')

default-block

The name of the default block on this page. This is the block to which content is appended when AnewtPage::append() is called.

The example below shows how a block-based page can be built:

anewt_include('page');
 
$p = new AnewtPage();
 
$p->blocks = array('header', 'content', 'footer');
$p->default_block = 'content';
 
/* Add content to specific blocks */
$p->append_to('header', ax_p('This is the header text.'));
$p->append_to('footer', ax_p('This is the footer text.'));
 
/* Add content to the default block */
$p->append(ax_h1('Hello, world!'));
$p->append(ax_p('This is a simple test page.'));
 
/* You can add content to the default block using append_to() as well, but that
 * involves a bit more typing. */
$p->append_to('content', ax_p('Another paragraph.'));
 
$p->flush();

Extending the standard page

Although AnewtPage can be used directly, most projects should subclass it for simplicity and code reuse. When subclassing AnewtPage, you typically set some properties in the constructor of the derived class, e.g. a default title and language. You should also add stylesheet and JavaScript references there. For block-based pages, this also includes the blocks property.

The following example demonstrates how to build your own page with stylesheet and JavaScripts references:

class MyPage extends AnewtPage
{
    function __construct()
    {
        /* Call the parent constructor */
        AnewtPage::__construct();
 
        /* Add stylesheets */
        $this->add_stylesheet_href('style.css');
        $this->add_stylesheet_href_media('print.css', 'print');
 
        /* Link to an external JavaScript file */
        $this->add_javascript_src('some-script.js');
 
        /* Embed JavaScript code directly */
        $this->add_javascript_content(
            'function foo() {
                alert("foo");
            }'
        );
 
        /* Provide a list of blocks */
        $this->blocks = array('header', 'content', 'footer');
 
        /* Set some default values */
        $this->title = 'This is the default title';
    }
}
 
 
/* You can use this page like this: */
 
$p = new MyPage();
/* ... */
$p->flush();

Providing default content

In many cases you want to provide default content to some of the div blocks, e.g. for headers and footers. This can be done by defining a method on your page subclass to generate that block. The function name should be YourPage::build_FOO, where FOO is the name of the block. Note that you can always override the content by using AnewtPage::append_to() and providing custom content for these blocks. When that happens, the build methods are not called at all.

An example: the list of blocks is header, content, and footer. The content is dynamically filled by the calling code, but the header and footer content are not explicitly provided by the calling code:

class MyPage extends AnewtPage
{
    function __construct()
    {
        AnewtPage::__construct();
        $this->blocks = array('header', 'content', 'footer');
    }
 
    function build_header() {
        return ax_p('This is the header');
    }
 
    function build_footer() {
        return ax_p('This is the footer');
    }
}
 
$p = new MyPage();
$p->append_to('content', ax_p('This is the content.'));
$p->flush();

Page output

The output generated by the AnewtPage class is designed to always produce valid XHTML 1.0 Strict output, which is supported by all modern browsers. However, in some cases you may want to change the document type declaration, e.g. to allow for framesets. You may do so using the document-type property:

document-type

The DTD to generate in the output (optional). Possible values include these constants: DTD_XHTML_1_0_STRICT (default), DTD_XHTML_1_0_TRANSITIONAL, or DTD_XHTML_1_0_FRAMESET. Alternatively you may provide a string value directly, but this is strongly discouraged.

The default character encoding for pages is UTF-8. You may override it by setting the encoding property:

encoding

The character encoding for this page. Defaults to UTF-8.

For block-based pages, a wrapper div is used by default that wraps all content. This allows for easy styling (e.g. setting an explicit width and centering all content). Several properties influence this behaviour:

use-wrapper-div

Whether to use a wrapper div (boolean, defaults to true).

wrapper-div-id

The id of the wrapper div. Defaults to wrapper.

Building valid pages

Of course you are responsible yourself for the well-formedness of the content you add to the page, but the XHTML methods and related functionality (see the xhtml module) can help you to create valid XHTML constructs easily. For instance, the ax_p() function lets you create a paragraph of text.

All string content added to the page is escaped by default (wrapped in a AnewtXMLDomText instance, actually), so you do not need to worry about special characters like & and < appearing in the content you add. In case you have already-formatted snippets of XHTML (e.g. stored in a database, from a text formatting engine, or from a template), you can add it as-is to the page using raw content nodes: wrap the value inside a call to ax_raw() to prevent the string from being escaped.

A few example lines of code to illustrate the above:

$p = new AnewtPage();
$p->append(ax_p('This is a paragraph of text.'));
$p->append(ax_raw('<p>This is some <code>pre-formatted</code> text.</p>'));
$p->append('This string will be escaped: <, &, and > are no problem!');
$p->flush();

Browser Compatibility

For maximum compatibility the AnewtPage class and the xhtml module produce compatible output as outlined in the XHTML specification. For more information, see these sections from the XHTML specification:

• XHTML compatibility issues
• HTML Compatibility Guidelines

The AnewtPage class serves its content with a MIME type understood by the user agent. It will only output an XML declaration when desired. The MIME type to use is auto-detected using the HTTP-Accept header of the request:

• User agents claiming to support XHTML receive a application/xhtml+xml page with both a XML prolog (<?xml … ?>) and a DOCTYPE declaration. Example browser: Mozilla Firefox.
• User agents not claiming to support the application/xhtml+xml MIME type will be served a text/html page instead with just a DOCTYPE declaration to force them into standards compliance mode. For these browsers XML prologs will not be sent. Example browser: Internet Explorer.

In almost all cases the output from AnewtPage will be understood correctly by the browsers. If absolutely necessary, you can set the content-type yourself by setting the content-type property:

content-type

The content type. Defaults to autodetection based on the HTTP_ACCEPT header sent by the client.

The result is that conforming user agents always get served the most strict output possible, without inflicting upon you the problems browser bugs and browser quirks that usually bite you when using XHTML (instead of plain old HTML).

Class listing

This module provides the following classes:

1. AnewtPage
2. AnewtBlankPage

Back to the overview page