Templayer ((version)) Tutorial

Templayer Home Page / Tutorial / Reference

%toc_left% %toc_right%
{contents}

Templayer Tutorial Template File

This file is used by docgen_tutorial.py to generate the tutorial documentation tutorial.html.


Items in the list that follows are parsed by docgen_tutorial.py. Each item has a tag and a name, separated by a tab character. Items without tags are new sections. A --- separates the left and right columns in the table of contents. 
Tag	Section or Item Name
{section_data}
	Gordon's Lawn Happenings
lawn1	Static HTML — Before Templayer
lawn2	Minimal Templayer Template
lawn3	Using Slots
lawn4	Using a Simple Layer
lawn5	Using Nested Layers
lawn6	Advanced Nested Layers
---
{/section_data}

{toc_section}

%snum%. %name%
{/toc_section}

{toc_item}

%snum%.%inum%. %name%
{/toc_item}

{section_head}

%snum%. %name%

{/section_head}
{section_body}

%snum%.%inum%. %name% [back to top]

%content%

{/section_body}
{html_example}
%name%
%contents%
{/html_example}
{code_example}
%name%
%contents%
{/code_example}
{result}
%contents%
{/result}
{body[lawn1]}

Our examples will be based on a fictional web site that has a single page:

%html% %result[0]%

All the example source code may be extracted from the docgen_tutorial.py script that is included with Templayer by running: 

python docgen_tutorial.py -s

{/body[lawn1]}
{body[lawn2]}

The first thing we need to do to use this page as a Templayer template file is to add a contents layer to it. This is done by adding the strings "{contents}" and "{/contents}" to the file:

%html%

Templayer searches the template file for the first occurrence of "{contents}" and the last occurrence of "{/contents}". This splits the file into three parts: the header, the content and the footer.

The header and footer will appear in Templayer's output. The content is described in sections below.

%code[0]%

This is a minimal CGI script that uses Templayer to display the web site. The result of running this script will be the same as if we just used the static page above.

We first create an HTMLTemplate object to handle parsing of the template above.

The start_file function creates a FileLayer object that will use the our HTMLTemplate object. The FileLayer object handles a single output run for our template. The start_file function allows you to pass in a file-like object to use instead of the standard output. For a CGI script we use the default.

The FileLayer object's open function will be explained below.

No output is written until the close function is called at the end of the script. If you don't get any output from your script it might be because you forgot to call the close function on your FileLayer object.

{/body[lawn2]}
{body[lawn3]}

The next step is to add slots to the header and footer of the template. Slots are like variables that can be filled in by the application. In the template file slot names are wrapped in "%" characters:

%html%

We have added two %title% slots to the header and one %date% slot to the footer of this template.

Please note: "%" is not a special character in Templayer templates. You do not need to escape "%" characters that aren't part of a slot. When filling slots Templayer has a list of slot names and it only replaces those slots, leaving all the other "%" characters in the template intact.

%code[0]%

Essentially only one line has changed in the code. The open function takes keyword parameters where the names of the parameters correspond to slots in the header and footer. Here both %title% slots will be filled with "Gordon's Lawn Happenings", and the %date% slot will be filled with the current date and time.

The values passed in to fill slots are interpreted by our HTMLTemplate object. The HTMLTemplate object expects HTML Markup described by the expand_html_markup function. Plain strings are treated as unsafe in HTML Markup and any characters that might be interpreted as HTML are escaped by this function. This means that Templayer's default behaviour is to escape values being filled into HTML templates.

%result[0]% {/body[lawn3]}
{body[lawn4]}

Now we look at what we can do with the content of a template file. You will recall that this refers to everything between the first occurrence of "{contents}" and the last occurrence of "{/contents}" in the template file.

%html%

We have now added a {report} layer to the template, and we have removed the "Lawn Happenings" from the template so that the application can fill them in. Layers are placed one after the next in the template content. The {report} layer extends from the first occurrence of "{report}" to the last occurrence of "{/report}" in the template content. Layers have slots just like the template header and footer.

Splitting HTML into separate layers lets us reuse the layers throughout the generated HTML, consolidating duplicated layout information. This template format can also be loaded in a web browser to test changes without running the application. Most templates can also be validated for compliance with HTML and CSS specs.

%code[0]%

We are now storing the return value of our FileLayer object's open function. The return value is a Layer object that represents the whole file. It knows the value of the header and footer which were filled in the FileLayer object's open function, but it can still have text filled into its content between the header and footer.

Layer objects have a write_layer function that is passed a layer name followed by keyword parameters that correspond to slots in that layer. Here we are adding two instances of our {report} layer to the content of the template's main Layer object. Recall that values passed in to fill slots are interpreted as HTML Markup by the expand_html_markup function. The "happenings" lists are escaped, then concatenated by this function.

Of course, we can separate the "Lawn Happenings" data from the code by creating a structure for it:

%code[1]%

This structure is a list of (day, happenings) tuples that is iterated through in the script. The day and happenings values are treated as HTML Markup

%result[0]%

Unfortunately, the HTML code that this generates is different than before we added the {report} layer — the "Happenings" are no longer in separate paragraphs. One way to fix this is to use HTML Markup and avoid mixing actual HTML into the code:

%code[2]%

The expand_html_markup function will take the ('p', text) tuples, escape the text, wrap them in HTML paragraph tags then concatenate them.

%result[1]% {/body[lawn4]}
{body[lawn5]}

HTML Markup is not intended for anything beyond very simple formatting. A more flexible solution is to create another layer to nest within the first.

%html%

Now the decision to format individual "Happenings" as paragraphs has been moved to the template in a {happening} layer.

%code[0]%

Within the new inner loop we are calling our HTMLTemplate object's format function. This function is similar to the write_layer function except that it returns a RawHTML object instead of adding it to the content of a Layer object. The expand_html_markup function will leave the contents of the RawHTML object intact, so we can use this object within HTML Markup.

{/body[lawn5]}
{body[lawn6]}

Since it is common to nest layers in Templayer another method is provided that is similar to FileLayer's open function. First we need to rename a slot in the {report} to %contents%:

%html%

Now that we have a %contents% slot we can "open" this layer and write into it:

%code[0]%

The Layer object has an open_layer function that returns a new layer object. In this case the new Layer object represents a {report} layer that is being written. The Layer object stores everything above the %contents% slot as its header and everything below as its footer. It can have text filled into its content in the same way as our main Layer object. Here we are now using write_layer to fill {happening} layers into {report} layers.

We also renamed the slot in {happening} to %contents%, so we can use the open_layer function on that as well:

%code[1]%

We want to send text into this new Layer object, so instead of calling write_layer we call the write function. It takes a single parameter that is interpreted as HTML Markup.

When using Templayer to produce very large files, or when parts of an HTML page take longer to complete, you might want to flush your output part of the way through:

%code[2]%

Layer objects have a close_child function that forces any open "child" layers to finalize their output. In this code we are closing the {report} layer. FileLayer objects have a flush function that will send all the output possible. We are first closing our {report} layer so that when we flush the output the whole report will appear.

{/body[lawn6]}
{/contents}