[ZDP] FAQ 0.2 - DTML

[Martijn Faassen]

Zope FAQ 0.2 - DTML

* In a DTML expression, how do I access variable names with a '-' in
  them? (such as 'sequence-item')

    Any variable name (including those with '-') can be accessed in
    the '_' namespace. This contains a dictionary of all variables in
    the default namespace. To access 'sequence-item' you therefore use::

        _['sequence-item']

    Another possibly is to use '_.getitem()', like this::
   
        _.getitem('sequence-item')

    The difference is that the first renders 'sequence-item' through
    DTML, whereas 'getitem()' does not; it returns the raw value of
    'sequence-item'.

* How do I call an external method from DTML?

    Use::

        <!--#var "external_method_name(arguments)"-->
   
    to call any External Method in the folder (or acquired by the
    folder). The more explicit alternative is::

        <!--#var expr="external_method_name(arguments)"-->

    The rule is that anything between double quotes in the first
    argument of the #var tag is interpreted as an expression
    attribute; a first argument without quotes is interpreted as a
    name attribute.

* How do I define a variable for use in a document?

    Set it in REQUEST::

        <!--#call "REQUEST.set('varname', value)"-->

* How do I pass a non-form variable to the next requested URL?

    Use 'hidden' fields within the form::

        <input type="hidden" name="varname" value="<!--#var varname-->">

* How can I show all form data/cookies/REQUEST vars without knowing
their
names?

    By using the #in tag, you can easily all show all data in any
    dictionary object, like 'REQUEST.form', 'REQUEST.cookies' and even
    'REQUEST' itself. Just call the 'items()' method of the
    dictionary, and the #in tag will provide a 'sequence-key' and
    'sequence-item' variable for every item in the dictionary.

    Show showing all form data can be done like this::

        <!--#in "REQUEST.form.items()" sort-->
          <!--#var sequence-key-->:<!--#var sequence-item--><BR>
        <!--#/in-->

    Use 'REQUEST.cookies.items()' for all your cookies, and
    'REQUEST.items()' for all 'REQUEST' variables, including CGI
    Environment variables.
    
    If you don't mind the format, you could use '<PRE><!--#var
    REQUEST--></PRE>' as a shortcut.

* How do I tell the tree tag to show only Folders?

    By using the objectValues function in the branches_expr attribute
    of the tree tag. The objectValues function of a folder returns all
    objects contained by that folder.

    You can however, specify a list of object metatypes that it should
    return. objectValues(['DTML Document']) will only return all DTML
    Document objects in a Folder. Other metatypes you could select on
    are: Folder, DTML Method, File, Image, Mail Host, User Folder and
    Session.  This is not a complete list, as Products can and will
    define their own metatypes. If you want to show more types, just
    add them to the list, like objValues(['Image', 'File']).
    
    Example of a Folder tree (with links to them)::

        <!--#tree branches_expr="objectValues(['Folder'])"-->
            <A HREF="<!--#var URL1-->/<!--#var id-->">
            <!--#var title_or_id-->
            </A>
        <!--#/tree-->

* How can I collapse or expand a tree using a URL?

    The tree tag will show a tree fully expanded when the 'expand_all'
    variable is present in its namespace. So when a URL, showing a
    tree, is called with ?expand_all=1, the tree tag will expand all
    it's branches.  Collapsing can be achieved with collapse_all.

    The following example shows a tree with collapse and expand
'buttons'::

        <A HREF="<!--#var URL0-->?expand_all=1">
          Expand all</A>|
        <A HREF="<!--#var URL0-->?collapse_all=1">
          Collapse all</A>

        <!--#tree--><!--#var id--><!--#/tree-->

* How can I limit a tree to showing only *one* branch at a time?

    Use the 'single' attribute for your tree, like in::

        <!--#tree single--><!--#var id--><!--#/tree-->