Web Oriented Object Framework

User Guide (Version 0.5b4)

Woof!
User Guide (Version 0.5b4)

Table of Contents
Page generation Default page layout

Page layout

A layout defines the HTML page head and body sections and then positions the various page sections within the body.

The following is a simple example of a layout:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN">
<html>
  <head>
    <title>Example Layout</title>
  </head>
  <body>
% if {[page fetch header content]} {
     $content
     <hr/>
% }
% if {[page fetch main content]} {
     $content
% }
% if {[page exists footer content]} {
     <hr/>
     $content
% }
  </body>
</html>

The above layout is defined in Woof! Template Format (WTF) format (with apologies for hurting anyone's sensibilities). This is a mixture of Tcl code and HTML markup. It starts with defining the standard HTML page headers. Within the body element, the above layout defines three sections - the header, the main content and the footer. The contents of each section, if defined, are expected to be in the page object. Note that the layout makes use of conditional Tcl statements to insert each section only if it exists. The fetch method returns true if the page section exists and stores it in the variable content. The page object, from which the HTML content is retrieved, is constructed when building page sections.

Woof! comes with a default layout, described in the next section, so in many cases you need not explicitly write one yourself.

Defining page sections in layouts

In the above layout, only three sections are referenced. However, Woof! itself does not impose any restrictions on the number and names of the sections, or how they are positioned. The page object will attempt to retrieve the content of each section based on the controller and action specified in the client request and the name of the section. The corresponding section content is either directly stored by the action method or generated from a template. It is up to the application writer to ensure the appropriate named sections can be generated.

Processing layout templates

A layout template is processed like any other WTF file. What makes it different is really only the intended usage. By convention, the layout template is primarily be concerned with positioning of major HTML areas and providing standard headers. It then makes use of the page object to retrieve the various page sections that contain the actual data, both static and dynamically retrieved from a controller.

However, there is nothing that prevents a layout from containing pure static HTML content, or directly accessing a controller's dynamic content. It does not have to use the page object. Nor does it does not have to be implemented in terms of page sections at all. However, as we will see, using page sections offers great flexibility and reuse and Woof! rendering system provides specific features to support that model. Moving away from this might be occasionally useful when a particular page does not follow a site's standard layout and is simple enough that adding separate layout and page section templates is not worthwhile.

Locating layout templates

An application's web pages may not all be layed out the same way. Woof! allows for this by using a search path to locate the layout to use for a particular controller and action. This search path allows for both sharing as well as specialization of layouts.

The algorithm of locating a layout for a page is the same as that used for page sections and is detailed in Locating templates. The method described there allows flexible sharing of common layouts within, and between, controllers and controller trees while simultaneously allowing special layouts for specific controllers or even actions within a controller.

Using layout overrides

There may be instances where you want to use a specific named layout and override the constructed layout file names described above. You can do this by setting the pagevar value layout as follows:

pagevar set layout special_layout

Woof! will then use special_layout.wtf as the name of the layout file and look for it in the search path as described above.

This kind of layout override may be done at any time before the page is rendered. If the above statement was executed within the constructor for the controller, special_layout.wtf would be used for all action methods in the controller (unless they in turn overrode it). If it was executed within an action method, only the layout for that action method would be overridden.

Page generation Default page layout