[Zope-dev] Annouce Developer Version DTML-Page-Contract

[ender]

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 <k_vertigo@yahoo.com>
	@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 <k_vertigo@yahoo.com>
 	
	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