Documents and Templates Architecture

In Zope, the fundamental piece of information is a Document, used by Business Users to communicate information. To deliver the content in Documents consistently, Site Designers create Templates that format the content into output.

In this chapter we will look at the goals of Documents and Templates, then discuss how they are used. Subsequent chapters will explore Documents and Templates in detail.

Overview

In this architecture, authors create content by simply writing structured content such as regular HTML. Site designers create consistent look and feel by simply writing structured content such as regular HTML. Zope turns these into Documents and Templates, respectively, and uses Templates to render Documents.

Business Users create Documents in multiple formats (HTML, XML, structured text, etc.) using multiple tools (the Zopetop, Radio UserLand, Netscape Composer, Adobe Golive, etc.):

The Documents produced by these authors have a very important element in common: they have well-formed structure:

No matter the format, the Document must be able to provide its internal structure when asked.

The author continues writing new Documents and editing old Documents with their favorite tool, without regard to anything specific to Zope nor to the consistent look and feel of the site.

Site Designers are in charge of the look-and-feel of pages in the site. They create this look and feel in a number of ways, such as directly authoring HTML:

The Site Designer, though, is in charge of how the author's content is "merged" into the site pages. To do this, they indicate in their templates the regions that are replaced with content from the Document. These indications give the Template a structure similar to Documents:

When the Document is viewed in the site, Zope matches up the places where the Template structure asks for something present in the Document structure:

The Document is viewed "through" the Template. The default sample content supplied by the Site Designer is replaced with real information in the Document. Viewing the URL of the Document in the site yields the content viewed through the Template:

With this architecture, the following scenarios are possible:

1) A Netscape Composer user authors regular HTML "files" that are given a consistent look and feel across the site. This uses the HTTP PUT protocol to create and modify Documents.

2) An Adobe GoLive 5 site designer creates professional look and feel as regular HTML files. These contain sample content to gauge the look without Zope being involved at all. When the files are placed into Zope and attached to Documents, the look and feel is applied to the site. This uses the WebDAV protocol for integrating GoLive and Zope.

3) An Amaya user just types stuff in and saves it. Since Amaya is a structured browser/editor that uses the HTTP PUT protocol, everything just works.

4) An Emacs user uses ange-ftp to create XML content in Simplified DocBkXML format. These .xml files are connected to a .xslt XSLT Template for rendering into HTML. This uses the FTP protocol to interact with Zope.

In summary:

• The author creates structured Documents.
• The designer creates structured Templates.
• Zope renders the Documents using the Templates.

Goals

The primary goal of this architecture for Documents and Templates is usability. First, content creators and site designers should be able to use standard tools and well-understood techniques. This architecture allows them to create valid material that can be viewed before Zope gets involved. Also, it does not require them to learn a new language.

There are secondary goals as well. From an architectural perspective, this model helps acheive separation of tiers such as presenation and data. Also, this architecture can enhance security, as the bulk of the objects authored won't have a need to access programming structures. A related issue is performance; removing the programming might provide better opportunities for caching.

If Documents and Templates are structured, Zope could turn the internal structure into separate database objects. This would allow finer granularity for caching. Far more important, though, changing a single word in a Document would revision only the paragraph, not the entire Document. This could also greatly assist comparing Documents.

By separating presentation from content, and by providing for structured content, Documents can be better indexed by the Catalog.

Multiple presentations is the final benefit. The way a Document is bound to a Template is governed by a set of rules. This allows different presentations to be chosen under different conditions, and is the subject of the next section.

However, the dominating goal of this architecture is to improve usability by allowing regular tools and concepts to be used.

Binding Documents to Templates

In the Overview above, we glossed over a piece of magic by saying "Zope matches up the places..." When a Document is viewed in the site, it is matched to the appropriate Template based on a set of rules:

By default the following precedence rules are applied when Zope finds the correct Document for a Template:

• If the Document contains an HTML LINK element that points to an XSLT or DTML Template, and the Document owner has the permission allowing them to specify the Template, that Template is chosen.
• Otherwise, if a skin rule maps a condition such as a locale to a Template, that rule is used.
• Otherwise, if the Folder or any parent Folder has a mapping that specifies how Documents are created, and the mapping assigns custom defaults of Templates to Documents, that mapping is used.
• Otherwise, if a parent Folder has a default Template for that Document format, that Template is used.
• Otherwise, the default Template in the ZClass definition for that Document format is used.

• The same content can be repurposed for WAP phones.
• Customization is possible at the Document, subFolder, site, or class level, but the site still has control.
• Different conditions at rendering time can give different results.

There is another binding rule that is critical, but is explicit. It is possible to use a Template other than the default by traversing the Document. For instance, imagine the URL /folderA/MyDocument.html by default uses /folderA/MyTemplate.html. However, we'd like to provide hyperlinks to alternate versions, such as the Template for Mozilla browsers at /folderA/MozTemplate.xul. We do this by using the URL /folderA/MyDocument.html/MozTemplate.xul.

Formats

Documents and Templates are structured Zope objects in a number of formats. For instance, Documents can come in many flavors, such as HTML, XML, structured text, and a row in a SQL result. Templates also have formats, such as DTML and XSLT.

The commonality between the formats is that they all provide a structured way to get to and modify the contents. For instance, imagine a SQL Folder at /sqlfolderA, with a SQL Document 0123 that is the primary key. The URL /sqlfolderA/0123 for the SQL Document is rendered with a Template '/sqlfolderA/Expense.html':

img:DTA08.png

In this case, Zope located the row of data using the primary key in the URL, put a standard Document structure around it, and rendered it using a Template.

Providing Structure

This architecture works by intersecting the structure of the Document and Template. The intersection is done using the Document Object Model (DOM) Level 2, a W3C specification of programming interfaces for object systems. Any Zope object that has a DOM can be assigned a Template and rendered with a Template.

Within the Document and Template, the only API available is the DOM. This means that majority of work in Zope is done using a very well documented, standard API used in many other applications. On the downside, this can make simple cases that are easier using alternatives such as Python more complicated using the DOM. However, these downsides are more than offset by using an industry standard API for working with the structure of content.

Also, the "code" in a Document or Template is only allowed to read the state of the Zope site and is not allowed to make changes. For instance, setting new value for a Folder property from within a Document or Template is not possible. To accomplish this, a Method must be created and used from the Document or Template.

Document authors can provide additional structure using standard conventions. For instance, HTML Documents can use META tags in the HEAD of the Document to provide additional structured information about the Document, such as workflow status. Also, the BODY used could be overridden with a DIV tag usin the ID of BODY. Likewise, structured text conventions could be used to indicate additional structure, similar to Frontier outline content. Template authors have the entire DOM of the target Document available, through which they can pick out the structure they are looking for.

The structure of the Document is important beyond rendering by Templates. For instance, the properties used by the Site Catalog can be provided with this structure, as the Site Catalog uses the DOM to access the content it indexes. Workflow models or event models also can be signaled when the structure is saved or updated.

Also note that structure from outside the Document can be added to the rendered Document by the Template. For instance, imagine that the site allows all Documents to have Discussions associated with them. The top-level posts in the Discussion are displayed at the bottom of the Document. With this architecture, the Template can locate the Discussion that is associated with the Document and insert it after the closing /BODY in the source Document. Meanwhile, the Document author can continue updating the Document without concern for removing the display of the Discussion.

This addition of Document-related structure can apply to attachments, tasks, workflow status, etc., all handled by the Template.

Complex Rendering

In some cases, the complexity of decision-making in rendering a snippet of HTML requires mingling logic and presentation. For instance, if the Document's status is overdue and the user's preferences say they are from France, then the resulting HTML should direct them to email the French office of the company for assistance.

In previous Zope architectures, this kind of scenario was possible. Presentation, logic, and data were often intermingled in the same object to allow solving this problem. Under this Document and Template architecture, though, clean separation requires other choices.

The first choice is XSLT as a Template format. This XML standard technology gives a tremendous amount of power, but also complexity, that can be used for difficult tasks. The alternative is to create a Method which has full access to programming logic. The Method would then handle the work of a difficult region in the Template.

This proposal does not address the idea of "components", or pieces of the page that can provide assistance to the site designer about their use.

Downsides

This Document and Template architecture provides dramatically increased usability and clean separation of presentation from data and logic. However, there are still obstacles.

Foremost, there is a fundamental paradox that regular authoring tools cannot cope with. If an author creates a Document that looks different when the site renders it, how does the author retrieve the original for editing? That is:

1) Author creates MyDocument.html.

2) The site makes the URL MyDocument.html look completely different, making the look and feel consistent with all other Documents.

3) Author later tries to retrieve MyDocument.html for editing, but the HTML is completely different than what they saved.

This problem does not apply to the Zopetop, ZopeStudio, or perhaps RadioUserLand. All of these tools are sophisticated enough to retrieve the source version of the Document URL, instead of the rendered version. However, it does apply to FrontPage 2000, GoLive 5, Amaya, and other important tools.

The first choice is to extend these tools, if possible, to do The Right Thing. Obviously this is impractical.

One way to address this would be to have the source version of all Documents available by going to a different URL, such as the normal site with a different port number. For instance, if http://my.site/folderA/MyDocument.html was the public site version rendered through a Template, then Document authors would be told to go to http://my.site:81/folderA/MyDocument.html when creating and editing their content.

Caching is another downside. The same URL can give many different results based on different rules. This is good, as pages can be presented in different languages, or for different browser capabilities. However, caching at the server or browser level is more difficult. When one URL can have many results, which do you cache?

One approach is to use advanced HTTP/1.1 facilities such as Etags. This HTTP header, when combined with the URL,, becomes the unique identifier to caches. Under this Document and Template architecture, each Template could generate an Etag when it is applied to a Document.

Conclusion

In conclusion, this Document and Template architecture is an industry-standard separation of presentation, content, and logic, allowing standard tools to work with Zope.

In subsequent chapters we will explore Documents and Templates in detail.