[ZDP] DTML and context - ZCL III.3 somewhere (another draft 1)

[Rik Hoekstra]

Hi all,

Some remarks of Martijn Faassen and my own thoughts made me write the 
enclosed draft. It is meant as a part of an introduction to dtml and 
it goes a little oout of the ZCL outline. Is this too simplistic, too 
short, too long. Should I elaborate on this? Please send me feedback 
about what you think about it. 

I have a (slightly more intricate) example prepared in Zope - should 
I upload this to my member area, or should it go into the ZDP site 
somewhere?

Dody - this is explicitly not meant as complementary to and in no 
sense whatsoever a replacement of your var tag. The overlap is 
intentional; I think it is looking at the dtml stuff from a different 
point of view.

Martijn - is this what you meant (or a start of it)?

--------------------%<-------------------%<-----------------------%<-
DTML and context

DTML can script everything available in a given Zope context. DTML is 
(effectively) always written inside a DTML object (either a DTML 
method or a DTML Document). The place in the Acquisition hierarchy 
determines what its context is (for more information see 
Acquisition). Perhaps this would seem a bit formal description, 
but it is crucial to understanding Zope.

A DTML object and its context *always* consist of the following 
parts.

        namespace                  contents

______________________________________________________________________
Global Zope             ||  Zope internals (as far as they are
                        ||  exposed)
                        ||  string, math, random modules [did I leave 
                        ||  any out?]
______________________________________________________________________
acquistion parents      ||  Folders and folderish objects and their
                        ||  context. Acquisition presents you with a  
                        ||  namespace  stack, consisting of PARENTS.
                        ||  It is a (python) list, consisting of
                        ||  PARENTS[0,1...n] 
                        ||  The last item in the PARENTS list is
                        ||  always the root folder. PARENTS[n] may
                        ||  also be written as PARENTS[-1]
______________________________________________________________________
REQUEST                 ||    all variables concerned with the
                        ||    incoming (web) request, especially the
                        ||    webserver and cgi variables, and 
cookies
______________________________________________________________________
RESPONSE                ||    all variables concerning the outgoing
                        ||    (web)request, including cookies,
                        ||    content-types and redirection
______________________________________________________________________
object itself           ||    including object properties, both own
                        ||    and acquired
______________________________________________________________________

*NOTE* One caveat is that dtml objects do not always behave the same: 
a DTML Document is an object in itself (with its own properties), 
while a DTML Method is just a method of a folderish object [link to 
howto]. Mixing the two may lead to unwanted behaviour so choose your 
objects carefully.

Most of the scriptable parts of a DTML object in the table are 
treated extensively elsewhere. To get a bit of feeling of how the 
object and the changing context work together in Zope, let's take a 
look at an example. Please note that this example is neither meant to 
explain a specific tag nor any of the more subtle parts of 
acquisition. It is just to show the capabilities of DTML and the need 
to understand that understanding context is crucial to understanding 
Zope.

As acquisition is such a central phenonomenon in Zope lets throw in a 
little acquisition example:

Suppose we have a (folder/document) hierarchy as follows:

Folder1 {properties: property_1:'this is a folder'}
  DTMLDocument1 {no properties set}
  DTMLDocument2 {properties: property_1:'this is a document'}
  DTMLMethod1 {has no properties}

  Folder2 {no properties set}
    DTMLDocument21 {no properties}
    DTMLDocument22 {properties: property_1:'this is a DOCUMENT'}
    DTMLMethod21 {has no properties}


The dtml source code of *all* DTML documents and methods is as 
follows:

<dtml-var standard_html_header>  
<h2><dtml-var property_1></h2>
<dtml-var standard_html_footer>

In the different document this renders as follows:

DTMLDocument1:

<HTML>
<HEAD>
<TITLE>DTMLDocument1</TITLE>
</HEAD>
<BODY>
<H2>This is a folder</H2>
</BODY>
</HTML>


  DTMLDocument2:

<HTML>
<HEAD>
<TITLE>DTMLDocument2</TITLE>
</HEAD>
<BODY>
<H2>This is a document</H2>
</BODY>
</HTML>

  DTMLMethod1:

<HTML>
<HEAD>
<TITLE>DTMLMethod1</TITLE>
</HEAD>
<BODY>
<H2>This is a folder</H2>
</BODY>
</HTML>


  DTMLDocument21 
<HTML>
<HEAD>
<TITLE>DTMLDocument21</TITLE>
</HEAD>
<BODY>
<H2>This is a folder</H2>
</BODY>
</HTML>

  DTMLDocument22
<HTML>
<HEAD>
<TITLE>DTMLDocument22</TITLE>
</HEAD>
<BODY>
<H2>This is a DOCUMENT</H2>
</BODY>
</HTML>


  DTMLMethod21
<HTML>
<HEAD>
<TITLE>DTMLMethod</TITLE>
</HEAD>
<BODY>
<H2>This is a folder</H2>
</BODY>
</HTML>

These examples are just meant to show how a *very simple* form of
acquisition works, and how powerful it is. The use may not be readily 
apparent. However, remember you can do the same with dtml methods. So 
if you change the DTML method standard_html_header, it will have 
effect on *all* DTML object in the acquisition stack below it. In 
this way you can easily change or update the look of (parts of) your 
site by replacing only one (*1*) object.