[Zope] [ZDP] Assorted FAQs

[Martijn Faassen]

Hi everybody,

Here is a start. I just randomly browsed the mailing list and created a
completely uncategorized set of questions and answers for the FAQ. I
even snuck in a question of myself, see if you can answer it. :)

If you see a problem with some of these questions or answers, send a
followup with suggested corrections to the list and I'll include them in
the FAQ. If you have more question/answer pairs, go ahead and followup
too. I prefer these things to appear in the list (in a thread, and
marked by [ZDP]) for now, as this might stop people from writing the
same FAQs twice. I hope in a while we'll get somekind of collaborative
FAQ environment going that makes all this easier.

I'd prefer additions to the FAQ in StructuredText for now. See what
follows for an example of the format I have in mind. If you think
another format works better feel free to convert. (yes, that's the theme
of open source; if you want something done differently, feel free to do
the work to change it :).

Here's what I have so far, enjoy!

* How do I return an image from an External Method?

    Example (for a png image)::

        def foo(self, RESPONSE):
            # set the header
            RESPONSE['content-type'] = 'image/png'
            # return the actual image data
            return mkimage()

    Another way to set the header information is::

        RESPONSE.setHeader('content-type','image/png')
  
* How can an External Method refer to the objects in the Zope app?

    Use an External Method that gets passed 'self'. 'self' is your
    hook into Zope world. From 'self' you should be able to get
    anywhere you'd like to go. 

    'self' is the folder in which the external method is
    called. External Methods are methods of Folders. Since External
    Methods are acquired, self is not always the same Folder in which
    the method is defined--it may be a child Folder.

* Is there any way for External Methods to access files on the
  filesystem of the server?

    An External Method can access anything on the server computer that
    the Zope process has access to. Therefore, an External Method can
    do just about anything a Python program can do. This is both a
    power and a liability.
 
* Can I restrict what an External Method can do? Is there somekind of
  sandbox environment for External Methods?

    Right now there is no sandbox execution environment for External
    Methods. An External Method has access to everything that the Zope
    process has access to. This is one of the reasons why External
    Methods are required to be defined in the Extensions
    directory--it's easier to keep an eye on them there.

* How do I call an external method from DTML?

    Use:

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

        &lt!--#var expr="external_method_name(arguments)"--&gt

    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.
 
* Why does StructuredText have trouble rendering the '#var' tags in
  the FAQ? Why do you use the HTML &amp escape codes in the FAQ when
  they don't work well either?

    I suspect there is some interaction between StructuredText and
    DTML that causes '#var' tags to be interpreted even when in a
    StructuredText code block (indicated by '::' or single quotes). I
    don't know any workaround right now, so I leave in ugly escape
    codes to encourage suggestions. :)

* 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']

* How do you safely do a backup of the Zope database? ('data.bbb' in
  the 'var' directory)

    In Zope 1.10 and later, you can simply back up the
    data.bbb. Because of the way the file written (all write
    operations are appends), it is highly unlikely for a backup file
    created directly to have a problem. If the database is being
    written while the file is being copied, then the Zope may discard
    the last transaction when reading the copy, if the last record is
    incomplete.
 
    Alternatively, you could export the entire site and backup the
    export file. This won't be a full backup however, as it won't
    contain old revisions of objects.

    Yet another alternative is to (mis)use the Pack operation (in the
    Zope Control Panel, database management). Pack will create a
    Data.bbb.old backup copy of your file before packing (for safety),
    which you could then back up. To exploit this side effect you
    could do a pack that says something ridiculous (like pack anything
    older than thousand days).