Page Request

Templating System : API Reference

Summary

Transform, validate and report errors in the query parameters associated with a page request.

This API is an alternative to ad_page_contract which should usually be preferred if you have ACS installed.

Methods

template::request create

Initialize the data structure to store request parameters. Should be called at the start of any page that takes request parameters.

template::request set_param name 
                            -datatype datatype
                            -multiple
                            -optional
                            -validate { { expression } { message } }

Validates request parameter values and then sets a local variable. Values are transformed if a transformation procedure exists for the specified datatype (i.e. the components of a date are assembled into a single structure).

• Options for datatype are the same as for form elements.
• The multiple switch indicates that more than one value may be submitted. The local variable set by the procedure will be a list.
• The optional switch indicates that the parameter value may be empty or missing. A value is assumed to be required if this switch is not specified.
• The validate switch may be used to perform simple custom validation of each parameter value. expression must be a block of arbitrary Tcl code that evaluates to 1 (valid) or 0 (not valid). The variable $value may be used in the expression to reference the parameter value. message is simply a string containing a message to return to the user if validation fails. The variables $value and $label may be used in the message to reference the parameter value and label (or name if no label is supplied).

template::request get_param name

Returns the value (or values if the multiple is used) of the named parameter.

template::request is_valid error_url

Boolean procedure for determining whether any validation errors occurred while setting request parameters.

• error_url is the location of the template to use for reporting request errors. The default is /ats/templates/messages/request-error if no URL is specified. To report request errors in the template of the page itself, use self for the URL.

Example

request create

request set_param state_abbrev -datatype keyword -validate {
  { regexp {CA|HI|NV} $value } 
  { Invalid state abbreviation $value. }
}

request set_param start_date -datatype date
request set_param user_id -datatype integer -multiple

if { ! [request is_valid "/mytemplates/request-error"] } { return }

...

Note(s)

• Error reporting templates may reference the requesterror array to access error messages for each parameter.
• The request API provides a simple mechanism for processing request parameters. It is not intended as a replacement to ad_page_contract for sites built on the ArsDigita Community System.

---