[ZDP] FAQ 0.2 - External Methods

[Martijn Faassen]

Zope FAQ 0.2 - External Methods

* 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 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 do I add a Folder in an External Method?

    If you want the folder created within the Folder from which you
    call the External Method, use 'self' as the first argument ('self'
    should be passed automatically, though sometimes there are subtle
    difficulties about which we should have more FAQs [FIXME]).

    This External Method adds a folder to 'self'::

        def myAddFolder(self, id, title):
            self.manage_addFolder(id, title)

    You can then call this External Method from a DTML Document or
    DTML Method. [FIXME: will this work with DTML Documents too? Isn't
    'self' the non-folderish Document in that case?] For instance::

        <!--#call "myAddFolder('some_id', 'some_title')" -->

* How can I get access to the Folder I just added inside an External
Method?

    If you just created the Folder in the External Method, you can
    retrieve the new Folder object by doing using 'getattr'::

        newFolderObj = getattr(self, newFolderId)
    
    If 'newFolderName' is not a variable but hardcoded in your
    External Method, by doing for instance::

        self.manage_addFolder('hardcoded_id', someFolderTitle)
    
    then you can simply do this::

        newFolderObject = self.hardcoded_id
   
* How do I add a Document or Property to a Folder inside an External
Method?

    To add a Document to a Folder (referred to by 'folderObj')::

        folderObj.manage_addDocument(id, title, content)

    To add a Property to folderObj::

        folderObj.manage_addProperty(id, value, type)

    Where 'value' is the value of the property, and 'type' is a string
    that describes the type of the value. For a list of possible types
    you can look at the select box in Zope's add properties form. More
    details on what property types you can find in the Object
    Reference of the Zope Manager's Guide.

    The Zope builtin help (under the 'help' tab in the Zope management
    screen) documents a lot of other 'manage_' methods that you can
    call on Folder objects and other Zope products.