Namespace request

The request commands provide a mechanism for managing the query parameters to a page. The request is simply a special instance of a form object, and is useful for the frequent cases when data must be passed from page to page to determine display or page flow, rather than perform a transaction based on user input via a form.

Also see:

form
element

Method Summary

Listing of public methods:
template::request::create
template::request::error
template::request::get_param
template::request::is_valid
template::request::set_param

Method Detail

* indicates required

Public Methods:
template::request::create
Create the request data structure. Typically called at the beginning of the code for any page that accepts query parameters.
Options:
params A block of parameter declarations, separated by newlines. Equivalent to calling set_param for each parameter, but requiring slightly less typing.

template::request::error
Manually report request error(s) by setting error messages and then calling is_valid to handle display. Useful for conditions not tied to a single query parameter. The arguments to the procedure may be any number of name-message combinations.
Parameters:
name * A unique identifier for the error condition, which may be used for layout purposes.
msg * The message text associated with the condition.

template::request::get_param
Retrieves the value(s) of the specified parameter.
Parameters:
name * The name of the parameter.
Returns:
The value of the specified parameter.

template::request::is_valid
Checks for any param errors. If errors are found, sets the display template to the specified URL (a system-wide request error page by default).
Parameters:
url * The URL of the template to use to display error messages. The special value { self} may be used to indicate that the template for the requested page itself will handle reporting error conditions.
Returns:
1 if no error conditions exist, 0 otherwise.

template::request::set_param
Declares a query parameter as part of the page request. Validates the values associated with the parameter, in the same fashion as for form elements.
Parameters:
name * The name of the parameter to declare.
Options:
name The name of parameter in the query (may be different from the reference name).
multiple A flag indicating that multiple values may be specified for this parameter.
datatype The name of a datatype for the element values. Valid datatypes must have a validation procedure defined in the template::data::validate namespace.
optional A flag indicating that no value is required for this element. If a default value is specified, the default is used instead.
validate A list of custom validation blocks in the form { name { expression } { message } \ name { expression } { message } ...} where name is a unique identifier for the validation step, expression is a block to Tcl code that evaluates to 1 or 0, and message is to be displayed to the user when the validation step fails.
See Also:
element::create -

* indicates required