ad_page_contract_filter (public)

ad_page_contract_filter [ -type type ] [ -priority priority ] name \
    proc_args doc_string body

Defined in packages/acs-core/tcl-documentation-procs.tcl

Declare a filter to be available for use in ad_page_contract.

Here's an example of how to declare a filter:

    ad_page_contract_filter integer { name value } {
	Checks whether the value is a valid integer, and removes any leading zeros so as 
	not to confuse Tcl into thinking it's octal
    } {
	if { ![regexp {^[0-9]+$} $value] } {
	    ad_complain "Value is not an integer"
	    return 0
	}
	# trim leading zeros, so as not to confuse Tcl
	set value [string trimleft $value "0"]
	if { [empty_string_p $value] } {
	    # but not all of the zeros
	    set value "0"
	}
	return 1
    }
    

After the filter has been declared, it can be used as a flag in ad_page_contract, e.g.

    ad_page_contract {
	foo:integer
    } {}
    

Note that there's only one global namespace for names. At some point, we might add package-local filters, but we don't have it yet.

The filter proc must return either 1 if it accepts the value or 0 if it rejects it. Any problem with the value is reported using ad_complain (see documentation for this). Note: Any modifications you make to value from inside your code block will modify the actual value being set in the page.

There are two types of filters. They differ in scope for variables that are multiple or array. The standard type of filter (filter classic) is invoked on each individual value before it's being put into the list or the array. A post filter is invoked after all values have been collected, and is invoked on the list or array as a whole.

Switches:

-type (defaults to "filter") - The type of filter; i.e. filter or post. Default is filter.
-priority (defaults to "1000")

Parameters:

name - The name of the flag as used in ad_page_contract
proc_args - the arguments to your filter. The filter must take three arguments, name, value, and parameters, although you can name them any way you want. The first will be set to the name of the variable, the second will be upvar'd to the value, so that any change you make to the value will be reflected in the value ultimately being set in the page's environment, and the third is a list of arguments to the filter. This third argument can have multiple parameters split by | with no spaces or any other characters. Something like foo:range(3|5)
doc_string - Standard documentation-string. Tell other programmers what your filter does.
body - The body is a procedure body that performs the filtering. It'll automatically have one argument named value set, and it must either return the possibly transformed value, or throw an error. The error message will be displayed to the user.

Author:

Lars Pind <lars@pinds.com>

Created:

25 July 2000