README_FIRST


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 passes marshalling info along
	with 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 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 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>

	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 like 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 a 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 for putting out one of the finest
	open source community systems.
	thanks to Digitial Creations for putting out the best
	open source web app server.

	PAGE_CONTRACT IS RELEASED UNDER THE GPL.

	Copyright (C) 2001 Kapil Thangavelu

	This program is free software; you can redistribute it and/or modify
	it under the terms of the GNU General Public License as published by
	the Free Software Foundation; either version 2 of the License, or
	(at your option) any later version.

	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with this program; if not, write to the

	 Free Software Foundation, Inc.,
	 59 Temple Place, Suite 330,
	 Boston, MA  02111-1307  USA

V. When (this section included for completeness:)
	Where do you want to go tomorrow?
	

