Templating System API: Page Request

## 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.

templating@arsdigita.com