Page Templates are a web page generation tool. They help programmers and designers collaborate in producing dynamic web pages for Zope web applications. Designers can use them to maintain pages without having to abandon their tools, while preserving the work required to embed those pages in an application. In this chapter, you'll learn the basics about Page Templates including how you can use them in your web site to create dynamic web pages easily. In Chapter 9, "Advanced Page Templates", you'll learn about advanced Page Template features.
The goal of Page Templates is to allow designers and programmers to work together easily. A designer can use a WYSIWYG HTML editor to create a template, then a programmer can edit it to make it part of an application. If required, the designer can load the template back into his editor and make further changes to its structure and appearance. By taking reasonable steps to preserve the changes made by the programmer, the designer will not disrupt the application.
Page Templates aim at this goal by adopting three principles:
A Page Template is like a model of the pages that it will generate. In particular, it is a valid HTML page.
Zope already has DTML, why do you need another template language. First of all, DTML is not aimed at HTML designers. Once a page has been converted into a template, it is invalid HTML, making it difficult to work with outside of the application. Secondly, DTML suffers from a failure to separate presentation, logic, and content (data). This decreases the scalability of content management and website development efforts that use these systems.
DTML can do things that Page Templates can't such as dynamically generate email messages (Page Templates can only generate HTML and XML). So DTML won't go away. However, we do see Page Templates taking over almost all HTML/XML presentation work in Zope.
Page Templates use the Template Attribute Language (TAL). TAL consists of special tag attributes. For example, a dynamic page title might look like this:
<title tal:content="here/title">Page Title</title>
The tal:content attribute is a TAL statement. Since it has an
XML namespace (the tal: part) most editing tools will not
complain that they don't understand it, and will not remove it.
It will not change the structure or appearance of the template
when loaded into a WYSIWYG editor or a web browser. The name
content indicates that it will set the content of the title
tag, and the value "here/title" is an expression providing the
text to insert into the tag.
All TAL statements consist of tag attributes whose name starts
with tal: and all TAL statements have values associated with
them. The value of a TAL statement is shown inside quotes. See
Appendix C, "Zope Page Templates Reference", for more information
on TAL.
To the HTML designer using a WYSIWYG tool, the dynamic title example is perfectly valid HTML, and shows up in their editor looking like a title should look like. In other words, Page Templates play nicely with editing tools.
This example also demonstrates the principle that, "What you see is very similar to what you get". When you view the template in an editor, the title text will act as a placeholder for the dynamic title text. The template provides an example of how generated documents will look.
When this template is saved in Zope and viewed by a user, Zope turns the dummy content into dynamic content, replacing "Page Title" with whatever "here/title" resolves to. In this case, "here/title" resolves to the title of the object to which to the template is applied. This substitution is done dynamically, when the template is viewed.
There are template statements for replacing entire tags, their contents, or just some of their attributes. You can repeat a tag several times or omit it entirely. You can join parts of several templates together, and specify simple error handling. All of these capabilities are used to generate document structures. Despite these capabilities, you can't create subroutines or classes, perform complex flow control, or easily express complex algorithms. For these tasks, you should use Python-based Scripts or application components.
The Page Template language is deliberately not as powerful and general-purpose as it could be. It is meant to be used inside of a framework (such as Zope) in which other objects handle business logic and tasks unrelated to page layout.
For instance, template language would be useful for rendering an invoice page, generating one row for each line item, and inserting the description, quantity, price, and so on into the text for each row. It would not be used to create the invoice record in a database or to interact with a credit card processing facility.
If you design pages, you will probably use FTP or WebDAV instead of the Zope Management Interface (ZMI) to create and edit Page Templates. See the "Using FTP and WebDAV" section later in this chapter for information on editing Page Templates remotely. For the small examples in this chapter, it is easier to use the ZMI.
Use your web browser to log into the Zope Management Interface as a manager. Choose a Folder to work in (the root is fine) and pick "Page Template" from the drop-down add list. Type "simple_page" in the add form's Id field, then push the "Add and Edit" button.
You should now see the main editing page for the new Page
Template. The title is blank, the content-type is text/html,
and the default template text is in the editing area.
Now let's create simple dynamic page. Type the words "a Simple Page" in the Title field. Then, edit the template text to look like this:
<html>
<body>
<p>
This is <b tal:replace="template/title">the Title</b>.
</p>
</body>
</html>
Now push the Save Changes button. Zope should show a message confirming that your changes have been saved.
If an HTML comment starting with <-- Page Template Diagnostics
is added to the template text, then check to make sure you typed
the example correctly and save it again. This comment is an error
message telling you that something is wrong. You don't need to
erase the error comment; once the error is corrected it will go
away.
Click on the Test tab. You should see a page with, "This is a Simple Page." at the top. Notice that the text is plain; nothing is in bold.
Back up, then click on the Browse HTML source link under the content-type field. This will show you the unrendered source of the template. You should see, "This is the Title." Back up again, so that you are ready to edit the example further.
The Content-Type field allows you to specify the content type of
your page. Generally you'll use a content type of text/html HTML
or text/xml for XML.
If you set the content-type to text/html then Zope parses your
template using HTML compatiblity mode which allowers HTML's loose
markup. If you set your content-type to something other than
text/html then Zope assumes that your template is well formed
XML. Zope also requires an explicit TAL and METAL XML namespace
declarations for well formed XML.
The Expand macros with editing control is explain in Chapter 9, "Advanced Page Templates".
The expression, "template/title" in your simple Page Template is a path expression. This the most common type of expression. There are several other types of expressions defined by the TAL Expression Syntax (TALES) standard. For more information on TALES see Appendix C, "Zope Page Templates Reference".
The "template/title" path expression fetches the title property
of the template. Here are some other common path expressions:
request/URL: The URL of the current web request.user/getUserName: The authenticated user's login name.container/objectIds: A list of Ids of the objects in the
same Folder as the template.Every path starts with a variable name. If the variable contains the value you want, you stop there. Otherwise, you add a slash ('/') and the name of a sub-object or property. You may need to work your way through several sub-objects to get to the value you're looking for.
Zope defines a small set of built-in variables such as request
and user, which are described in Chapter 9, "Advanced Page
Templates". You will also learn how to define your own variables
in that chapter.
In your "simple_page" template, you used the tal:replace
statement on a bold tag. When you tested it, Zope replaced the
entire tag with the title of the template. When you browsed the
source, you saw the template text in bold. We used a bold tag in
order to highlight the difference.
In order to place dynamic text inside of other text, you typically
use tal:replace on a span tag rather than on a bold tag. For
example, add the following lines to your example:
<br>
The URL is <span tal:replace="request/URL">URL</span>.
The span tag is structural, not visual, so this looks like "The
URL is URL." when you view the source in an editor or browser.
When you view the rendered version, it may look something like:
<br>
The URL is http://localhost:8080/simple_page.
If you want to insert text into a tag but leave the tag itself
alone, you use the tal:content statement. To set the title of
your example page to the template's title property, add the
following lines between the html and the body tags:
<head>
<title tal:content="template/title">The Title</title>
</head>
If you open the "Test" tab in a new browser window, the window's title will be "a Simple Page". If you view the source of the page you'll see something like this:
<html>
<head>
<title>a Simple Page</title>
</head>
...
Zope inserted the title of your template into the title tag.
Now let's add some context to your page, in the form of a list of the objects that are in the same Folder as the template. You will make a table that has a numbered row for each object, and columns for the id, meta-type, and title. Add these lines to the bottom of your example template:
<table border="1" width="100%">
<tr>
<th>Number</th>
<th>Id</th>
<th>Meta-Type</th>
<th>Title</th>
</tr>
<tr tal:repeat="item container/objectValues">
<td tal:content="repeat/item/number">#</td>
<td tal:content="item/getId">Id</td>
<td tal:content="item/meta_type">Meta-Type</td>
<td tal:content="item/title">Title</td>
</tr>
</table>
The tal:repeat statement on the table row means "repeat this row
for each item in my container's list of object values". The
repeat statement puts the objects from the list into the item
variable one at a time (this is called the repeat variable), and
makes a copy of the row using that variable. The value of
"item/getId" in each row is the Id of the object for that row, and
likewise with "item/meta_type" and "item/title".
You can use any name you like for the repeat variable ("item" is
only an example), as long as it starts with a letter and contains
only letters, numbers, and underscores ('_'). The repeat variable
is only defined in the repeat tag. If you try to use it above or
below the tr tag you will get an error.
You can also use the repeat variable name to get information about
the current repetition. By placing it after the built-in variable
repeat in a path, you can access the repetition count from zero
('index'), from one ('number'), from "A" ('Letter'), and in
several other ways. So, the expression repeat/item/number is 1
in the first row, 2 in the second row, and so on.
Since one tal:repeat loop can be placed inside of another, more
than one can be active at the same time. This is why you must
write repeat/item/number instead of just repeat/number. You
must specify which loop your interested in by including the loop
name.
Now view the page and notice how it lists all the objects in the same folder as the template. Try adding or deleting objects from the folder and notice how the page reflects these changes.
Using Page Templates you can dynamically query your environment and selectively insert text depending on conditions. For example, you could display special information in response to a cookie:
<p tal:condition="request/cookies/verbose | nothing">
Here's the extra information you requested.
</p>
This paragraph will be included in the output only if there is a
verbose cookie set. The expression, 'request/cookies/verbose |
nothing' is true only when there is a cookie named verbose
set. You'll learn more about this kind of expression in Chapter 9,
"Advanced Page Templates".
Using the tal:condition statement you can check all kinds of
conditions. A tal:condition statement does nothing if its
expression has a true value, but removes the entire statement tag,
including its contents, if the value is false. Zope considers the
number zero, a blank string, an empty list, and the built-in
variable nothing to be false values. Nearly every other value
is true, including non-zero numbers, and strings with anything in
them (even spaces!).
Another common use of conditions is to test a sequence to see if it is empty before looping over it. For example is the last section you saw how to draw a table by iterating over a collection of objects. Here's how to add a check to page so that if the list of objects is empty no table is drawn:
<table tal:condition="container/objectValues"
border="1" width="100%">
<tr>
<th>Number</th>
<th>Id</th>
<th>Meta-Type</th>
<th>Title</th>
</tr>
<tr tal:repeat="item container/objectValues">
<td tal:content="repeat/item/number">#</td>
<td tal:content="item/getId">Id</td>
<td tal:content="item/meta_type">Meta-Type</td>
<td tal:content="item/title">Title</td>
</tr>
</table>
If the expressions, container/objectValues is false then the
entire table is omitted.
Most, if not all, of the objects listed by your template have an
icon property, that contains the path to the icon for that kind
of object. In order to show this icon in the meta-type column,
you will need to insert this path into the src attribute of an
img tag. Edit the meta-type column in both rows to look like
this:
<td><img src="/misc_/OFSP/Folder_icon.gif"
tal:attributes="src item/icon">
<span tal:replace="item/meta_type">Meta-Type</span>
</td>
The tal:attributes statement replaces the src attribute of the
img tag with the value of item/icon. The
src="/misc_/OFSP/Folder_icon.gif" attribute in the template acts
as a placeholder.
Notice that we've replaced the tal:content attribute on the
table cell with a tal:replace statement on a span tag. This
change allows you to have both an image and text in the table
cell.
Here's an example of using Page Templates with Zope to create a simple file library with one template, a little bit of Python code, and some files.
First, create a mock up of a file library page using your HTML editor. The examples in this chapter were made with Amaya. This mock-up doesn't need to overdo it, it just shows some dummy information. Here's a mock-up of a file library that contains one file:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>File Library</title>
<style type="text/css">
.header {
font-weight: bold;
font-family: helvetica;
background: #DDDDDD;
}
h1 {
font-family: helvetica;
}
.filename {
font-family: courier
}
</style>
<meta name="GENERATOR" content="amaya 5.1">
</head>
<body>
<h1>File Library</h1>
<p>Click on a file below to download it.</p>
<table border="1" cellpadding="5" cellspacing="0">
<tbody>
<tr>
<td class="header">Name</td>
<td class="header">Type</td>
<td class="header">Size</td>
<td class="header">Last Modified</td>
</tr>
<tr>
<td><a href="Sample.tgz" class="filename">Sample.tgz</a></td>
<td>application/x-gzip-compressed</td>
<td>22 K</td>
<td>2001/09/17</td>
</tr>
</tbody>
</table>
</body>
</html>
Now, log into your Zope and create a folder called FileLib. In
this folder, create a Page Template called index_html by
selecting Page Template from the add menu, specifying the Id
index_html in the form, and clicking Add.
Now, with your HTML editor, save the above HTML to the URL of the
index_html Page Template followed by /source.html, for
example, http://localhost:8080/FileLib/index_html/source.html.
Notice that the URL to save the index_html page ends in
source.html. Because Page Templates are dynamic, you need a way
to edit the raw source of the template, unrendered by the page
template language. Appending source.html to a Page Template
gives you this raw source. Note, if the content-type of your page
is text/xml then you'll use source.xml, rather than
source.html.
Now that you've saved the template, you can go back to Zope and
click on index_html and then click on its Test tab to view the
template. It looks just like it the mock-up, so everything is
going well.
Now let's tweak the above HTML and add some dynamic magic. First, we want the title of the template to be dynamic. In Zope, you'll notice that the Page Template has a title form field that you can fill in. Instead of being static HTML, we want Zope to dynamically insert the Page Templates title into the rendered version of the template. Here's how:
<head>
...
<title tal:content="template/title">File Library</title>
...
<body>
<h1 tal:content="template/title">File Library</h1>
...
Now go to Zope and change the title of the index_html page
template. After saving that change, click the Test tab. As you
can see, the Page Template dynamically inserted the title of the
template object in the output of the template.
Notice the new content tag attribute in the tal xml namespace.
This attribute says to "replace the content of this tag with the
variable 'template/title'". In this case, template/title is the
title of the index_html Page Template.
The next bit of magic is to build a dynamic file list that shows
you all the File objects in the FileLib folder.
To start, you need to write just one line of Python. Go to the
FileLib folder and create a Script (Python) in that folder.
Give the script the id files and click Add and Edit. Edit the
script to contain the following Python code:
## Script (Python) "files"
##
return container.objectValues('File')
This will return a list of any File objects in the FileLib folder.
Now, edit your index_html Page Template and add some more tal
attributes to your mock-up:
...
<tr tal:repeat="item container/files">
<td><a href="Sample.tgz" class="filename"
tal:attributes="href item/getId"
tal:content="item/getId">Sample.tgz</a></td>
<td tal:content="item/content_type">application/x-gzip-compressed</td>
<td tal:content="item/getSize">22 K</td>
<td tal:content="item/bobobase_modification_time">2001/09/17</td>
</tr>
...
The interesting part is the tal:repeat attribute on the tr
HTML tag. This attribute tells the template to iterate over the
values returned by "container/files" (the Python script you
created) and create a new table row for each of those files.
During each iteration, the current file object being iterated over
is assigned the name item.
The cells of each row all have tal:content attributes that
describe the the data that should go in each cell. During each
iteration through the table row loop, the id, the content type,
the size, and modification times replace the dummy data in the
rows. Also notice how the anchor link dynamically points to the
current file using tal:attributes to rewrite the href
attribute.
This data comes from the item object by calling Zope API methods
on what we know is a file object. The methods item/getId,
item/content_type, item/getSize,
item/bobobase_modification_time are all standard API functions
that are documented in Zope's online help system.
Go to Zope and test this script by first uploading some Files into
the FileLib folder. This is done by selecting File from the add
menu and clicking on the upload form button on the next screen.
After uploading your file, you can just click Add. If you do not
specify an id, then the filename of the file you are uploading will
be used.
After uploading some files, go to the index_html Page Template and
click the Test tab. Now, you can see the Page Template has
rendered a very simple file library with just a few HTML tag
attribute changes.
There are a few cosmetic problems with the file library as it stands. The size and date displays are not very pretty and don't match the format of the dummy content. You would like the size of the files to be displayed in K or MB rather than bytes. Here's a Python-based script that you can use for this:
## Script (Python) "file_size"
##
"""
Return a string describing the size of a file.
"""
bytes=context.getSize()
k=bytes/1024.0
mb=bytes/1048576.0
if mb > 1:
return "%.2f MB" % mb
if k > 1:
return "%d K" % k
return "%d bytes" % bytes
Create this script with the Id file_size in your FileLib
folder. It calculates a file's size in kilobytes and megabytes and
returns an appropriate string describing the size of the file. Now
you can use the script in place of the item/getSize expression:
...
<td tal:content="item/file_size">22 K</td>
...
You can also fix the date formatting problems with a little
Python. Create a script named file_date in your FileLib
folder:
## Script (Python) "file_date"
##
"""
Return modification date as string YYYY/MM/DD
"""
date=context.bobobase_modification_time()
return "%s/%s/%s" % (date.year(), date.mm(), date.day())
Now replace the item/bobobase_modification_time expression with
a reference to this script:
...
<td tal:content="item/file_date">2001/09/17</td>
...
Congratulations, you've successfully taken a mock-up and turned it into a dynamic Page Template. This example illustrates how Page Templates work well as the "presentation layer" to your applications. The Page Templates present the application logic (the Python-based scripts) and the application logic works with the data in your site (the files).
You can edit Page Templates remotely with FTP and WebDAV, as well as HTTP PUT publishing. Using these methods, you can use Page Templates without leaving advanced WYSIWYG editors such as DreamWeaver.
The previous section showed you how to edit a page remotely using Amaya, which uses HTTP PUT to upload pages. You can do the same thing with FTP and WebDAV using the same steps.
.html, while others prefer .zpt. Note, some names
such as index_html have special meanings to Zope./source.html or /source.xml. This gives you the source of
your Page Template.In later versions of Zope you'll probably be able to create Page Templates without using the Zope Management Interface.
Zope helps you find and correct problems in your Page Templates. Zope notices problem at two different times: when you're editing a Page Template, and when you're viewing a Page Template. Zope catches different types of problems when you're editing than when you're viewing a Page Template.
You're probably already familiar with trouble-shooting comments
that Zope inserts into your Page Templates when it runs into
problems. These comments tell you about problems that Zope finds
while you're editing your templates. The sorts of problems that
Zope finds when you're editing are mostly errors in your tal
statements. For example:
<!-- Page Template Diagnostics
Compilation failed
TAL.TALDefs.TALError: bad TAL attribute: 'contents', at line 10, column 1
-->
This diagnostic message lets you know that you mistakenly used
tal:contents rather than tal:content on line 10 of your
template. Other diagnostic messages will tell you about problems
with your template expressions and macros.
When you're using the Zope management interface to edit Page Templates it's easy to spot these diagnostic messages. However, if you're using WebDAV or FTP it's easy to miss these messages. For example, if you save a template to Zope with FTP, you won't get an FTP error telling you about the problem. In fact, you'll have to reload the template from Zope to see the diagnostic message. When using FTP and WebDAV it's a good idea to reload templates after you edit them to make sure that they don't contain diagnostic messages.
If you don't notice the diagnostic message and try to render a template with problems you'll see a message like this:
Error Type: RuntimeError
Error Value: Page Template hello.html has errors.
That's your signal to reload the template and check out the diagnostic message.
In addition to diagnostic messages when editing, you'll occasionally get regular Zope errors when viewing a Page Template. These problems are usually due to problems in your template expressions. For example, you might get an error if an expression can't locate a variable:
Error Type: Undefined
Error Value: "unicorn" not found in "here/unicorn"
This error message tells you that it cannot find the unicorn
variable which is referenced in the expression, here/unicorn. To
help you figure out what went wrong, Zope includes information
about the environment in the traceback. If you're in debugging
mode this information will be available at the bottom of the error
page. Otherwise, view the source of the error page to see the
traceback. The traceback will include information about the
environment:
...
'here': <Application instance at 01736F78>,
'modules': <Products.PageTemplates.ZRPythonExpr._SecureModuleImporter instance at 016E77FC>,
'nothing': None,
'options': {'args': ()},
'request': ...
'root': <Application instance at 01736F78>,
'template': <ZopePageTemplate instance at 01732978>,
'traverse_subpath': [],
'user': amos})
...
This information is a bit cryptic, but with a little detective
work it can help you figure out what went wrong. In this case, it
tells us that the here variable is an "Application
instance". This means that it is the top-level Zope folder (notice
how root variable is the same "Application instance"). Perhaps
the problem is that you wanted to apply the template to a folder
that had a unicorn property. The traceback doesn't provide a lot
of help, but it can help you sometimes.
Another example of the flexibility of Page Templates is that they can dynamically render XML as well as HTML. For example, in Chapter 5, "Creating Basic Zope Applications", you created the following XML:
<guestbook>
<entry>
<comments>My comments</comments>
</entry>
<entry>
<comments>I like your web page</comments>
</entry>
<entry>
<comments>Please no blink tags</comments>
</entry>
</guestbook>
This XML was created by looping over all the DTML Documents in a
folder and inserting their source into comment elements. In
this section, we'll show you how to use Page Templates to generate
this same XML.
Create a new Page Template called "entries.xml" in your guest book folder with the following contents:
<guestbook xmlns:tal="http://xml.zope.org/namespaces/tal">
<entry tal:repeat="entry python:here.objectValues('DTML Document')">
<comments tal:content="entry/document_src">Comment goes here...</comments>
</entry>
</guestbook>
Make sure you set the content type to text/xml. Now, click
Save Changes and click the Test tab. If you're using
Netscape, it will prompt you to download an XML document, if you
are using MSIE 5 or higher, you will be able to view the XML
document in the browser.
Notice how the tal:repeat statement loops over all the DTML
Documents. The tal:content statement inserts the source of each
document into the comments element. The xmlns:tal attribute is
an XML namespace declaration. It tells Zope that names that start
with tal are Page Template commands. See Appendix C, "Zope Page
Templates Reference" for more information about TAL and TALES XML
namespaces.
Creating XML with Page Templates is almost exactly like creating
HTML. The most important difference is that you must use explicit
XML namespace declarations. Another difference is that you should
set the content type to text/xml or whatever the content-type
for your XML should be. The final difference is that you can
browse the source of an XML template by going to source.xml
rather than source.html.
In general Zope supports content, presentation, and logic components. Page Templates are presentation components and they can be used to display content components.
Zope 2.5 ships with several content components: ZSQL Methods, Files, and Images. DTML Documents and methods are not really pure content components since they can hold content and execute DTML code. As this time Zope doesn't come with a good general purpose content object. You can use Files for textual content since you can edit the contents of Files if the file is less than 64K and contains text. However, the File object is pretty basic.
Zope's Content Management Framework (CMF) solves this problem by providing an assortment of rich content components. The CMF is Zope's content management add on. It introduces all kinds of enhancements including work-flow, skins, and content objects. The CMF makes a lot of use of Page Templates. A later release of Zope will probably include the CMF.
Zope Page Templates help you build web pages for your web applications. Templates make it easier for you to use normal HTML tools and techniques to build web pages. They also provide convenient hooks to allow you to attach them to your applications. Page Templates help designers and programmers work together to produce web applications. In Chapter 9, "Advanced Page Templates", you'll learn about powerful template techniques like Python expressions, and macros.