[ZDP] DTML introduction (ZCL III.3) - draft 1

Wed, 27 Oct 1999 21:36:51 +0100

Attached I send the first draft of my first contribution to the 
ZBook. It is a little beside the ZCL, but I thought a high 
level/simple introduction to DTML would be useful in a book size 
document.

I appreciate your comments.

greetings

Rik
-------<snip>--------------------------------------------

III.3 The Document Template Markup Language (DTML)

A. Overview

The Document Template Markup Language (DTML for friends) is the
scripting language used in the Zope framework. It is the 'glue' for
using Zope, that makes it possible to use Zope products from the web. 
In this respect it is similar to other web application servers (like 
ASP, PHP, ColdFusion etc.). It is a (simple) programming language in 
itself. It does use a number of Python features, the language Zope is 
programmed in, but it is not Python.

DTML is used from within HTML documents and works with HTML-like 
tags. A sample DTML snippet looks like this: 

       <dtml-in "objectValues(['Folder'])">
          <dtml-var id>
       </dtml-in>

At this point, we're not concerned about what it means, but we may 
make some observations:
- a DTML tag 'looks like', HTML but it is not. DTML tags are ignored 
by HTML browsers.
- DTML always starts with '<dtml-' and ends with '>'
- some tags are single (in this example the <dtml-var...> tag), but 
other tags need to be closed (in this example the <dtml-in...> tag)
- arguments to tags can either be as-is or between quotes. Single 
quotes are different from double quotes.

Inserting DTML into a normal HTML document makes it a DTML document 
(or rather object) to Zope. A very simple DTML document could look 
like this:

example:
   <dtml-var standard_html_header>
   <h2><dtml-var title></h2>
   <p>Hello World!</p>
   <dtml-var standard_html_footer>

In the Zope framework this document is interpreted as follows:

             Interpretation                      Result
______________________________________________________________________
- show the contents of           | <HTML>
  standard_html_header           |  <HEAD>
                                 |    <TITLE>Document title</TITLE>
                                 |  </HEAD>
                                 |  <BODY> 
----------------------------------------------------------------------

- show the title of the current  | <h2>First document</h2>
  document                       | <p>Hello World!</p>
----------------------------------------------------------------------

- show the contents of           | </BODY>
  standard_html_footer           | </HTML>
---------------------------------------------------------------------

Perhaps needless to say, but standard_html_header and 
standard_html_footer are also DTML document, which are also 
interpreted (rendered in Zope terms).
In their turn they could also contain references to other DTML 
documents etcetera. DTML documents are *internal* to Zope. If a 
browser calls a DTML document, Zope renders it and returns the 
rendered document to the browser. Therefore, viewing the source of a 
DTML document in a browser only reveals the rendered HTML.

As DTML can call other DTML, it is easy in Zope to separate content 
and programs. The separation of content and programs is considered 
good Zope practice if not essential in building Zope sites. This 
feature distinguishes Zope from [XXX many?] other Web application 
servers. As from Zope 1.... [XXX which version???] there are two 
different standard DTML objects in Zope to accommodate the two types. 
Content should go into *DTML documents* that only contain the little 
dtml  needed for inserting the dynamic elements. The more extensive 
DTML coding should go into *DTML methods*. [XXX is a remark/link 
about the differences between DTML methods and DTML documents in 
place here???]

DTML has a number of different tags. While the basics are easily
learned, more advanced DTML programming can be complicated. More
advanced DTML is often easily replaced with python code. This may be 
done in External Methods [link] or products.

If DTML is easily learned, then why is DTML programming complicated? 
The main reason is that DTML is always closely tied to the Zope 
framework. It is not so much DTML itself, but the dynamically 
changing context of the Zope framework that can be very confusing. In 
this chapter we'll try to provide you with examples for the use of 
DTML in different contexts, but unforunately this could never be 
exhaustive. To get a full grasp of the Zope framework it is very
important to understand core Zope concepts like acquisition and
namespaces.

*Note about DTML syntax* In this document we only use Zope 2 style 
DTML syntax (<dtml-...>, as explained above). Before Zope 2 another 
syntax was used for DTML (). This is now deprecated, but 
you can still come across it in dtml documents, the Zope framework or 
Zope products. For compatibility reasons the old syntax is still 
recognized in Zope. You could even mix the two types of syntax if you 
really want to.