ad_page_contract (public)

 ad_page_contract [ -form form ] [ -level level ] [ -context context ] \
    [ -warn ] [ -properties properties ] docstring [ args... ]

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

Specifies the contract between programmer and graphic designer for a page. When called with the magic "documentation-gathering" flag set (to be defined), the proc will record the information about this page, so it can be displayed as documentation. When called during normal page execution, it will validate the query string and set corresponding variables in the caller's environment.

Example:

ad_page_contract  {
        Some documentation.
        @author me (my@email)
        @cvs-id $Id: tcl-documentation-procs.tcl,v 1.67 2024/12/13 09:40:45 gustafn Exp $
    } {
        foo
        bar:integer,notnull,multiple,trim
        {greble:integer {[expr {[lindex $bar 0] + 1}]}}
    } -validate {
        greble_is_in_range -requires {greble:integer} {
            if { $greble < 1 || $greble > 100 } {
                ad_complain
            }
        }
        greble_exists -requires { greble_is_in_range } {
            if { ![info exists ::greble_values($greble)] } {
                ad_complain [_ acs-tcl.lt_Theres_no_greble_with]
            }
        }
    } -errors {
        foo {error message goes here}
        bar:integer,notnull {another error message}
        greble_is_in_range {Greble must be between 1 and 100}
    }

An argspec takes one of two forms, depending on whether there's a default value or not:

1. {name[:flag,flag,flag] default}

2. name[:flag,flag,flag]

If no default value is specified, the argument is considered required, but the empty string is permissible unless you specify :notnull. For all arguments, the filter :nohtml is applied by default. If the arg is named *.tmpfile, the tmpfile filter is applied.

Possible flags are:

trim

The value will be string trimmed.

notnull

When set, will barf if the value is the empty string. Checked after processing the trim flag. If not set, the empty string is always considered valid input, and no other filters are processed for that particular value. If it's an array or multiple variable, the filters will still be applied for other values, though.

optional

If there's a default value present, it's considered optional even without the flag. If a default is given, and the argument is present but blank, the default value will be used. Optional and no default value means the variable will not be set, if the argument is not present in the query string.

multiple

If multiple is specified, the var will be set as a list of all the argument values (e.g. arg=val1&arg=val2 will turn into arg=[list val1 val2]). The defaults are filled in from left to right, so it can depend on values of arguments to its left.

array

This syntax maps query variables into Tcl arrays. If you specify customfield:array, then query var customfield.foo will translate into the Tcl array entry $customfield(foo). In other words: whatever comes after the dot is used as the key into the array, or, more mathematically: x.y=z => set x(y) z. If you use dot or comma is part of your key (i.e., y above contains comma or dot), then you can easily split on it in your Tcl code. Remember that you can use any other flag or filter with array.

verify

Will invoke ad_verify_signature to verify the value of the variable, to make sure it's the value that was output by us, and haven't been tampered with. If you use export_vars -form -sign or export_vars -sign to export the variable, use this flag to verify it. To verify a variable named foo, the verify flag looks for a form variable named foo:sig. For a :multiple, it only expects one single signature for the whole list. For :array it also expects one signature only, taken on the [array get] form of the array.

cached

This syntax will check to see if a value is being passed in for this variable. If it is not, it will then look in cache for this variable in the package that this page is located, and get this value if it exists.

date

Pluggable filter, installed by default, that makes sure the array validates as a date. Use this filter with :array to do automatic date filtering. To use it, set up in your HTML form a call to a date formfield. Then on the receiving page, specify the filter using varname:array,date. If the date validates, there will be a variable set in your environment varname with four keys: day, month, year, and date. You can safely pass $varname(date) to Oracle.

time

Pluggable filter, installed by default, that makes sure the array validates as a time in am/pm format. That is that it has two fields: time and ampm that have valid values. Use this filter with :array to do automatic time filtering. To use it, set up in you HTML form using [ec_timeentrywidget varname] or equivalent. Then on the processing page specify the filter using varname:array,time. If the time validates, there will be a variable set in your environment varname with five keys: time, ampm, hours, minutes, and seconds.

time24

Pluggable filter, installed by default, that makes sure the array validates as a time in 24hr format. That is that it has one field: time that has valid values. Use this filter with :array to do automatic time filtering. To use it, set up in you HTML form using <input type="text" name="varname".time>. Then on the processing page specify the filter using varname:array,time24. If the time validates, there will be a variable set in your environment varname with four keys: time, hours, minutes, and seconds.

integer

Pluggable filter, installed by default, that makes sure the value is integer, and removed any leading zeros.

naturalnum

Pluggable filter, installed by default, that makes sure the value is a natural number, i.e. non-decimal numbers >= 0.

oneof

Pluggable filter, installed by default, that makes sure the value X contained in the set of the provided values. Usage example: color:oneof(red|blue|green)

range

Pluggable filter, installed by default, that makes sure the value X is in range [Y, Z]. Usage example: foo:range(1|100)

nohtml

Pluggable filter, installed by default, that disallows any and all html.

html

Pluggable filter, installed by default, that only allows certain, safe allowed tags to pass (see ad_html_security_check). The purpose of screening naughty html is to prevent users from uploading HTML with tags that hijack page formatting or execute malicious code on the users's computer.

allhtml

Pluggable filter, installed by default, that allows any and all html. Use of this filter is not recommended, except for cases when the HTML will not be presented to the user or there is some other reason for overriding the site-wide control over naughty html.

tmpfile

Checks to see if the path and file specified by tmpfile are allowed on this system.

sql_identifier

Pluggable filter, installed by default, that makes sure the value is a valid SQL identifier.

path

Pluggable filter, installed by default, that makes sure that argument contains only Tcl word characters or a few additional safe characters used in paths ("/", ".", "-")

token

Pluggable filter, installed by default, that makes sure that argument contains only Tcl word characters or a few additional safe characters (",", ":", "-").

word

Pluggable filter, installed by default, that makes sure that argument contains only Tcl word characters (as defined by \w in Tcl regular expressions, i.e. characters, digits and underscore).

localurl

Pluggable filter, installed by default, that makes sure that argument contains a non-external url, which can be used in ad_returnredirect without throwing an error.

clock

Pluggable filter, installed by default, that makes sure that argument is a time string formatted according to the format specified in the flag. The format uses the syntax from the clock Tcl command. Usage example time:clock(%H:%M:%S).

more filters...

Note that there can be no spaces between name, colon, flags, commas, etc. The first space encountered denotes the beginning of the default value. Also, variable names can't contain commas, colons or anything Tcl accepts as list element separators (space, tab, newline, possibly others) If more than one value is specified for something that's not a multiple, a complaint will be thrown ("you supplied more than one value for foo").

There's an interface for enhancing ad_page_contract with pluggable filters, whose names can be used in place of flags (see ad_page_contract_filter). There's also an interface for pluggable filter rules, which determine what filters are applied to arguments (see ad_page_contract_filter_rule).

Note on QQ-variables: Unlike the old ad_page_variables, ad_page_contract does not set QQ-versions of variables. The QQ-versions (had each single-quote replaced by two single-quotes) were only necessary for building up SQL statements directly in a Tcl string. Now that we're using bind variables, the QQ-variables aren't necessary anymore, and thus, ad_page_contract doesn't waste time setting them.

Default Values

Default values are filled in from left to right (or top to bottom), so it can depend on the values or variables that comes before it, like in the example above. Default values are only used when the argument is not supplied, thus you can't use default values to override the empty string. (This behavior has been questioned and may have to be changed at a later point.) Also, default values are not checked, even if you've specified flags and filters. If the argument has the multiple flag specified, the default value is treated as a list. If the array flag is specified, we expect it to be in array get format, i.e. a list of { name value name value ... } pairs. If both multiple and array are set, the value elements of the before-mentioned array get format are treated as lists themselves.

Errors Argument

The -errors block defines custom error messages. The format is a list in array get format with alternating error-names and error texts. The error names can be foo, which means it's thrown when the variable is not supplied. Or foo:flag,flag,..., which means it'll get thrown whenever one of the flags fail. If you want the same error to be thrown for both not supplying a var, and for a flag, you can say foo:,flag,... (a comma immediately after the colon).

Validation Blocks

The -validate is used to fully customized user input validation. The format is a list of named chunks of code, for example:

-validate {
        name {
            code block
        }
        another_name -requires { argname[:filter-or-validation-block-name,...] ... } {
            code block
        }
    }

The name is for use with the -errors block, and for use within the -requires argument of another validation block. The validation blocks will get executed after all flags and filters have been evaluated. The code chunk should perform some validation, and if it's unhappy it should call ad_complain, optionally with an error message. If no error message is specified, the error should be declared in the -errors section.

Each validation block can also have a -requires switch, which takes a list of validations that must already have been successfully passed, for the validation to get executed. The intent is that you want to provide as much feedback as possible at once, but you don't want redundant feedback, like "foo must be an integer" and "foo must be in range 10 to 20". So a check for foo in range 10 to 20 would have a -requires { foo:integer } switch, to ensure that the check only gets executed if foo was successfully validated as an integer.

In the -requires argument, you can specify a list of (1) the name of an argument, which means that the argument must be supplied. Or (2) you can specify argname:filter or argname:validation_block to say that a given filter, flag or valdiation block must have been executed and satisfied for this validation block to get executed. You can have as many requirements as you like.

Switches:

-form (optional)

Optionally supply the parameters directly here instead of fetching them from the page's form (ns_getform). This should be a reference to an ns_set.

-level (optional, defaults to "1")

-context (optional)

-warn (optional, boolean)

-properties (optional)

What properties the resulting document will contain.

Parameters:

docstring (required)

The documentation for your page; will be parsed like ad_proc and ad_library.

Authors:

Lars Pind <lars@pinds.com>

Yonatan Feldman <yon@arsdigita.com>

Bryan Quinn <bquinn@arsdigita.com>

Created:

16 June 2000

Partial Call Graph (max 5 caller/called nodes):

Testcases:

page_contracts