 |
ActiveTcl User Guide
|
 |
|
[ Main table Of Contents | Tcllib Table Of Contents | Tcllib Index ]
ncgi(n) 1.2.2 "CGI Support"
ncgi - Procedures to manipulate CGI values.
package require Tcl 8.2
package require ncgi ?1.2.2?
The ncgi package provides commands that
manipulate CGI values. These are values that come from Web forms
and are processed either by CGI scripts or web pages with embedded
Tcl code. Use the ncgi package to query these
values, set and get cookies, and encode and decode www-url-encoded
values.
In the simplest case, a CGI script first calls ::ncgi::parse and then calls ::ncgi::value to get different form values. If a CGI
value is repeated, you should use ::ncgi::valueList to get back the complete list of
values.
An alternative to ::ncgi::parse is ::ncgi::input, which has semantics similar to Don Libes'
cgi_input procedure. ::ncgi::input restricts repeated CGI values to have names
that end with "List". In this case, ::ncgi::value will return the complete list of values,
and ::ncgi::input will raise errors if it find
repeated form elements without the right name.
The ::ncgi::reset procedure can be used in
test suites and Web servers to initialize the source of the CGI
values. Otherwise the values are read in from the CGI
environment.
The complete set of procedures is described below.
- ::ncgi::cookie cookie
- Return a list of values for cookie, if any.
It is possible that more than one cookie with the same name can be
present, so this procedure returns a list.
- ::ncgi::decode str
- Decode strings in www-url-encoding, which represents special
characters with a %xx sequence, where xx is the character code in
hex.
- ::ncgi::empty name
- Returns 1 if the CGI variable name is not
present or has the empty string as its value.
- ::ncgi::encode string
- Encode string into www-url-encoded
format.
- ::ncgi::header ?type? args
- Output the CGI header to standard output. This emits a
Content-Type: header and additional headers based on args, which is a list of header names and header values.
The type defaults to "text/html".
- ::ncgi::import cginame ?tclname?
- This creates a variable in the current scope with the value of
the CGI variable cginame. The name of the
variable is tclname, or cginame if tclname is empty
(default).
- ::ncgi::importAll args
- This imports several CGI variables as Tcl variables. If args is empty, then every CGI value is imported.
Otherwise each CGI variable listed in args is
imported.
- ::ncgi::importFile cmd cginame ?filename?
- This provides information about an uploaded file from a form
input field of type file with name cginame. cmd can be one of
-server -client,
-type or -data.
- -client cginame
- returns the filename as sent by the client.
- -type cginame
- returns the mime type of the uploaded file.
- -data cginame
- returns the contents of the file.
- -server cginame filename
- writes the file contents to a local temporary file (or filename if supplied) and returns the name of the
file. The caller is responsible for deleting this file after
use.
- ::ncgi::input ?fakeinput? ?fakecookie?
- This reads and decodes the CGI values from the environment. It
restricts repeated form values to have a trailing "List" in their
name. The CGI values are obtained later with the ::ncgi::value procedure.
- ::ncgi::multipart type query
- This procedure parses a multipart/form-data query. This is used by ::ncgi::nvlist
and not normally called directly. It returns an alternating list of
names and structured values. Each structure value is in turn a list
of two elements. The first element is meta-data from the
multipart/form-data structure. The second element is the form
value. If you use ::ncgi::value you just get the
form value. If you use ::ncgi::valueList you get
the structured value with meta data and the value.
The type is the whole Content-Type, including
the parameters like boundary. This returns a
list of names and values that describe the multipart data. The
values are a nested list structure that has some descriptive
information first, and the actual form value second. The
descriptive information is list of header names and values that
describe the content.
- ::ncgi::nvlist
- This returns all the query data as a name, value list. In the
case of multipart/form-data, the values are structured as described
in ::ncgi::multipart.
- ::ncgi::parse
- This reads and decodes the CGI values from the environment. The
CGI values are obtained later with the ::ncgi::value procedure. IF a CGI value is repeated, then
you should use ::ncgi::valueList to get the
complete list of values.
- ::ncgi::parseMimeValue value
- This decodes the Content-Type and other MIME headers that have
the form of "primary value; param=val; p2=v2" It returns a list,
where the first element is the primary value, and the second
element is a list of parameter names and values.
- ::ncgi::query
- This returns the raw query data.
- ::ncgi::redirect url
- Generate a response that causes a 302 redirect by the Web
server. The url is the new URL that is the
target of the redirect. The URL will be qualified with the current
server and current directory, if necessary, to convert it into a
full URL.
- ::ncgi::reset query type
- Set the query data and Content-Type for the current CGI
session. This is used by the test suite and by Web servers to
initialize the ncgi module so it does not try to read standard
input or use environment variables to get its data. If neither query or type are specified,
then the ncgi module will look in the standard CGI
environment for its data.
- ::ncgi::setCookie args
- Set a cookie value that will be returned as part of the reply.
This must be done before ::ncgi::header or ::ncgi::redirect is called in order for the cookie
to be returned properly. The args are a set of
flags and values:
- -name name
- -value value
- -expires date
- -path path restriction
- -domain domain
restriction
- ::ncgi::setDefaultValue key defvalue
- Set a CGI value if it does not already exists. This affects
future calls to ::ncgi::value (but not future
calls to ::ncgi::nvlist). If the CGI value
already is present, then this procedure has no side effects.
- ::ncgi::setDefaultValueList key defvaluelist
- Like ::ncgi::setDefaultValue except that the
value already has list structure to represent multiple checkboxes
or a multi-selection.
- ::ncgi::setValue key value
- Set a CGI value, overriding whatever was present in the CGI
environment already. This affects future calls to ::ncgi::value (but not future calls to ::ncgi::nvlist).
- ::ncgi::setValueList key valuelist
- Like ::ncgi::setValue except that the value
already has list structure to represent multiple checkboxes or a
multi-selection.
- ::ncgi::type
- Returns the Content-Type of the current CGI values.
- ::ncgi::urlStub ?url?
- Returns the current URL, but without the protocol, server, and
port. If url is specified, then it defines the
URL for the current session. That value will be returned by future
calls to ::ncgi::urlStub
- ::ncgi::value key ?default?
- Return the CGI value identified by key. If
the CGI value is not present, then the default
value is returned instead. This value defaults to the empty
string.
If the form value key is repeated, then there
are two cases: if ::ncgi::parse was called, then
::ncgi::value only returns the first value
associated with key. If ::ncgi::input was called, then ::ncgi::value returns a Tcl list value and key must end in "List" (e.g., "skuList"). In the case of
multipart/form-data, this procedure just returns the value of the
form element. If you want the meta-data associated with each form
value, then use ::ncgi::valueList.
- ::ncgi::valueList key ?default?
- Like ::ncgi::value, but this always returns
a list of values (even if there is only one value). In the case of
multipart/form-data, this procedure returns a list of two elements.
The first element is meta-data in the form of a parameter, value
list. The second element is the form value.
html
CGI , cookie , form , html