[Zope] [ZGotW] Issue #1 Entry

[Zope Guru of the Week]

===================================================================
Issue #1 -- DTML Subroutines
===================================================================

       Status:  Open 

    Zen Level:  Novice (1/8)

     Keywords:  DTML 

 Submitted by:  Tres Seaver tseaver@palladion.com
-------------------------------------------------------------------
 Suppose you have been happily hacking away at your Zope site,
 and discover that you are reusing a chunk of DTML over 
 and over::

  <!-- Display all contained FooTypes in a table-->
  <dtml-in "objectValues( 'FooType' )">
  <tr>
    <td> <a href="&dtml-id;"><dtml-var id></a> </td>
    <!-- more FooType properties follow -->
  </tr>
  </dtml-in>

 Now, you decide to "refactor" the site to follow the
 "Once and Only Once":http://c2.com/cgi/wiki?OnceAndOnlyOnce dictum of 
 "Extreme Programming":http://www.extremeprogramming.org :
 i.e., you'd like to make this snippet a reusable "subroutine,"
 so that you could make changes to it in just one place.
 The intent is to be able to reuse the loop, but be able
 to vary the meta_type(s) being passed to the loop:
 in one spot, it would be '"FooType"', but in another, 
 it might be '[ "Folder", "DTML Document" ]' [1].

 How do you move this code out into a DTML Method and then
 replace all the cloned copies with calls to that method?

[1] *Please pardon my inverting the single/double quotes here:
    while not valid DTML, it **is** valid Python, and renders
    correctly as StructeredText.*
-------------------------------------------------------------------

   Entry from:  Evan Simpson evan@4-am.com
-------------------------------------------------------------------
Zope Guru of the Week wrote:

> Entry from:  Jeff K. Hoffman jeff@goingv.com

[snip]

> If you want to call this method on objects elsewhere in the
> hierarchy (i.e., not the "current" folder):
>
> <dtml-with target>
>   <dtml-var "table_of_type(this(), _, type_list = ['FooType'])">
> </dtml-with>

This can more concisely be written as <dtml-var "table_of_type(target, _, type_list = ['FooType'])">.  Specifying the client like this is a little-appreciated compensation for having to make the first two arguments explicit when passing keyword arguments.

This can also be used to get around acquisition problems.  Suppose you don't want to clutter up your root folder with this sort of factored method, so you stick them all in a folder called '/lib'.  Now you want to call '/lib/table_of_type' on folder 'target'.  If you try...

<dtml-with target><dtml-with lib><dtml-var ...></...></...>

..you'll get a list of object in 'lib' instead of 'target'.  Reverse the 'dtml-with's and it may work, but it's awkward, and fails if there is a '/lib/target'.  On the other hand...

<dtml-var "lib.table_of_type(target, _, type_list='Folder')">

..will work just fine (even if table_of_type is a Document instead of a Method!).

Cheers,

Evan @ 4-am

P.S.  I *really* like this Zope Guru of the Week idea.  This could turn into a real Zope knowledge base.
-------------------------------------------------------------------