hello zen masters

i just finished documenting a developer version of a port of the ACS's 
(arsdigita community system) acs_page_contract to dtml.  test it out,
i'm pretty sure everyone will be happy with the simplification of the 
resulting dtml. 

feed back and thoughts welcome.

if no bugs are found in the next week or so i'll make it a general release,
new filters are always welcome.

available at 



readme included below.


        extract PageContact.tgz in your zope directory. it will create
        a python product in lib/python/Products. you will need to
        restart zope before you can use dtml-contract

        remove the PageContract directory from lib/python/Products and
        restart zope.

I. What
        Page-Contract is a python product that adds a new type of dtml-tag 
        to your zope installation. dtml-contract is a multi-purpose tag that
        is designed to provide documentation, marshalling and filtering of
        request data, and custom error handling of the request data. the
        documentation comes from a read only section of the contract 
        which should describe the purpose of the object, its author, and
        some information about its parameters. the marshalling and filtering
        is done by naming variables expected in the request and associating
        one or more filters with those variables. PageContract comes with
        a set of prebuilt filters although it can easily be extended by
        writing new filters. lastly it allows association of different
        error handlers to different variables.

II. Why
        Zope already includes facilties to perform simple marshalling of 
        REQUEST values submitted via GET/POST into python data_types. This
        facility is built into ZPublisher. There are a couple of problems
        with this facility in real world usage. First, ZPublishers 
        marshalling isn't secure because it retrievesmarshalling info from
        the REQUEST, a cracker could perform url surgery to by pass
        the marshalling. Second, ZPublishers marshalling isn't easily
        extensible to provide application level support of. The marshalling
        is buried square in the guts of the Publishing process, even if you
        did extend it would be too early in the Publishing of the object to
        perform any meaningful application specific processing (ie you don't
        know where you're going so how do you know what you'll see when you 
        get there). Third ZPublisher has no concept of excluding parts of 
        the REQUEST that aren't needed, this is mitigated by Zope placing the
        REQUEST on the bottom of the namespace stack, however it still 
        provides a means for accidents (ie. you're expecting this object to have this
        attr, but it doesn't but the REQUEST has that attr). dtml-contract 
        can optionally strip the REQUEST of variables not explicitly named
        within it. Fourth, ZPublisher is inflexible about how it handles 
        errors. ZPublisher has hardcoded return values whenever it hits
        a bad input AND it short circuits the evalutation. Users don't 
        get informative messages regarding their errors other than they 
        made one. dtml-contract differs in that it collects all errors 
        and associates them with their variables and provides the option
        of custom error pages on a variable by variable basis with 
        information passing about the errors. (The current implementation
        is limited in that it only passes a list of filter errors to the
        error handler via a url string.)

        The dtml-contract also hopes to offer a standardized form
        of documenting your zope objects (DTML_METHODS, DOCUMENTS,
        and the like) by standardizing on a documentation format
        and a location for that documentation.

III. How
        So how do you use it?

        Documentation about this object

        @author Kapil Thangavelu <[EMAIL PROTECTED]>
        @params myobj_id the id of the object where after
        @params title we'll set the object's title to this value
        @params thedate should be the range of the bada and bing
            @params foobar optional integer value that tells us whats going on


        thedate:range(date, 1.1.1, 11/11/11)

        Generally dtml-contracts should be used at the start of a dtml
        page. why? so they can be easily referenced for documentation
        and knowledge of the expected parameters.

        Caveats. Note that there are no strict enforcements of the documentation
        section. Although some future documentation extraction utility 
        would benefit from it:) Also note other dtml tags are not allowed
        within the dtml-contract, trying to do so will have it abort. this
        is done mainly as a security feature to prevent malicious code
        from doing bad things (TM) to your zope server.

        I have made some attempts to make this code fast. it will ignore
        obviously alike filters such as :integer,naturalnum and it will 
        execute only naturalnum since it is the more exclusive of the 
        filters. it will short circuit on an optional variable if its not
        in the request.

        Full Documentation on the syntax is in 
        So how do you write a filter?
        see the README_FILTER document for more info on filter

IV. Who
        @author Kapil Thangavelu <[EMAIL PROTECTED]>
        thanks to Petru Paler for the seed.
        thanks to the members of Hayholt, AU for testing an alpha version
        and offering feedback on this documentation.

        thanks to ArsDigita.com for putting out a quality open 
        source community-toolkit and acs_page_contract upon which this is based.

        and of course thanks to Digital Creations for creating and releasing Zope


V. When (this section included for completeness:)
        Where do you want to go tomorrow?
        www.zope.org, ZopeDealers to the Internet

Zope-Dev maillist  -  [EMAIL PROTECTED]
**  No cross posts or HTML encoding!  **
(Related lists - 
 http://lists.zope.org/mailman/listinfo/zope )

Reply via email to