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 http://www.zope.org/Members/k_vertigo/PageContract.tgz kapil readme included below. README.txt INSTALL: 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 UNINSTALL: 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? <dtml-contract> 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 <dtml-params> myobj_id:objid foobar:integer,optional thedate:range(date, 1.1.1, 11/11/11) title:string <dtml-exceptions> myobj_id:my_error_page generic_error_page </dtml-contract> 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 README_SYNTAX So how do you write a filter? see the README_FILTER document for more info on filter interfaces. 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 PAGE_CONTRACT IS RELEASED UNDER THE GPL. 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] http://lists.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://lists.zope.org/mailman/listinfo/zope-announce http://lists.zope.org/mailman/listinfo/zope )
