Previous Chapter | Next Chapter | Up | Next Section | Contents

Name Lookup


When a variable name is used in a DTML tag, such as a dtml-var tag or an expr attribute expression, that name must be resolved. Table See Simplest-case steps for looking up names shows the steps taken to look up data in the simplest case.

Simplest-case steps for looking up names

Step

Rule

1

When a document template is called from Python, the mapping object and keyword arguments supplied when calling the document template are searched, with keyword arguments taking precedence over the mapping object.

2

When a document templates is called from Python, attributes, including inherited and acquired attributes, of the client passed in the call to the document template are searched.

3

If DTML is used in a Zope DTML Method or Document and the variable name is document_id or document_title , then the id or title of the document is used.

4

Attributes of the folder containing the DTML are searched. Attributes include objects in the contents of the folder, properties of the folder, and other attributes defined by Zope6, such as ZopeTime7 . Folder attributes include the attributes of folders containing the folder, with contained folders taking precedence over containing folders.

5

Search Zope-defined Web-request data (table See Zope-defined Web request variables).

6

Search variables defined in Web-request form data.

7

Search variables defined in Web-request cookies.

8

Search variables named URLn , where n is a digit. URL0 is the Request URL without a query string. URL1 is the same as URL0 except that the last name in the URL is removed. URL2 is the same as URL0 except that the last two names are removed, and so on. For example, if the request URL is http://digicool.com/A/B , then URL0 , URL1 , and URL2 are respectively, http://digicool.com/A/B , http://digicool.com/A and http://digicool.com . URL3 is undefined.

9

Search CGI-defined Web-request variables. See table See CGI-defined Web request variables for a description of CGI-defined variables.

10

Search HTTP Headers. A variable name associated with a HTTP header consist of the HTTP header name, converted to upper case, with the Prefix, HTTP_ . For example, a HTTP Referer header, if present, can be accessed using the variable name HTTP_REFERER .

11

Search variables named BASEn , where n is a digit. BASE0 is the prefix of the request URL up to, but not including, the name of the Zope installation or module published by ZPublisher. BASE1 is the request URL up to and including the name of the Zope installation or module published by ZPublisher. BASE2 is the request URL up to the name following the name of the Zope installation or module published by ZPublisher, and so on. For example, assume that a Zope installation or module published by ZPublisher has the URL: http://digicool.com/Demos/Plutonia and that a request URL is http://digicool.com/Demos/Plutonia/Marketing. BASE0 is http://digicool.com/Demos, BASE1 is http://digicool.com/Demos/Plutonia and BASE2 is http://digicool.com/Demos/Plutonia/Marketing. BASE3 is undefined.

There are two situations in which the search rules for the simplest case are modified. If a Zope object or Python document template is called within a DTML expr attribute expression, then additional variables may be passed in. Variables passed in take precedence over all variables described in Table 6.

Zope-defined Web request variables

Name

Description

AUTHENTICATED_USER

An object that represents an authenticated user. When inserted into a DTML document, the value is the user name. This object currently provides no public attributes. Note that this variable may not be defined in Documents that are not protected by security information.

AUTHENTICATION_PATH

The path to the object containing the user database folder which contained the definition for the authenticated user.

PARENTS

A sequence of ancestors of the object that was accessed in the current request. For example, if the accessed object is a Document, then PARENTS[0] is the folder containing the document, PARENTS[1] is the folder containing the folder containing the document, and so on.

REQUEST

An object that represents the current request. This object may be used in an expr expression to look up request data, including variables described in this table, CGI-defined variables (table See CGI-defined Web request variables), form variables, cookies, and HTTP headers. In addition, expr expressions may use request attributes defined in table See Attributes of the REQUEST variable.

RESPONSE

An object that represents the response to the current request. This object is primarily useful in expr expressions using attributes defined in table See Attributes of the RESPONSE variable.

URL

The URL used to invoke the request without the query string, if any.

Attributes of the REQUEST variable.

Name

Description

cookies

If a HTTP Cookie was included in the request, then this attribute is a dictionary8 containing the cookie data. This allows cookie data to be looked up, even if a cookie name is the same as a form variable or an object attribute name.

form

If a request was initiated by submitting a form, then the form attribute is a dictionarya containing the form data. This allows form data to be looked up, even if a form name is the same as an object attribute name.

has_key(name)

Determine whether the REQUEST defines a given name.

set(name, value)

Set a variable in the request.

Attributes of the RESPONSE variable

Name

Description

setStatus(status)

Set the HTTP status code of the response; the argument may either be an integer or a string from {OK, Created, Accepted, NoContent, MovedPermanently, MovedTemporarily, NotModified, BadRequest, Unauthorized, Forbidden, NotFound, InternalError, NotImplemented, BadGateway, ServiceUnavailable} that will be converted to the correct integer value.

setHeader(name, value)

Set a HTTP return header name with value, clearing the previous value set for the header, if one exists.

getStatus()

Return the current HTTP status code as an integer.

setBase(base)

Set the base URL for the returned document.

expireCookie(name,...)

Cause a HTTP cookie to be removed from the browser The response will include a HTTP header that will remove the cookie corresponding to "name" on the client, if one exists. This is accomplished by sending a new cookie with an already passed expiration date.

setCookie(name,value,...)

Cause the response to include a HTTP header that sets a cookie on cookie-enabled browsers with a key name and value. This overwrites any previously set value for the cookie in the Response object. Additional cookie parameters can be included by supplying keyword arguments. The valid cookie parameters are expires , domain , path , max_age , comment , and secure .

getHeader(name)

Return the value associated with a HTTP return header or None if no such header has been set in the response.

appendHeader(name, value)

Set a HTTP return header "name" with value "value" and appending it following a comma if there is a previous value set for the header.

redirect(location)

Cause a redirection without raising an error.

CGI-defined Web request variables

Name

Description

SERVER_SOFTWARE

The name and version of the information server software answering the request. Format: name/version

SERVER_NAME

The server's host name, DNS alias or IP address as it would appear in self-referencing URLs.

GATEWAY_INTERFACE

The revision of the CGI specification to which this server complies. Format: CGI/revision.

SERVER_PROTOCOL

The name and revision of the information protocol this request came in with. Format: protocol/revision

SERVER_PORT

The port number to which the request was sent.

REQUEST_METHOD

The method with which the request was made. For HTTP, this is "GET", "HEAD", "POST", etc.

PATH_INFO

The part of the request URL, not counting the query string, following the name of the Zope installation or module published by ZPublisher.

PATH_TRANSLATED

The server provides a translated version of PATH_INFO, which takes the path and does any virtual-to-physical mapping to it.

SCRIPT_NAME

A virtual path to the script being executed, used for self-referencing URLs.

QUERY_STRING

The information which follows the ? in the URL which referenced this script. This is the query information.

REMOTE_HOST

The host name making the request. If the server does not have this information, it should REMOTE_ADDR and leave REMOTE_HOST unset.

REMOTE_ADDR

The IP address of the remote host making the request.

AUTH_TYPE

If the server supports user authentication, and the script is protected, this is the protocol-specific authentication method used to validate the user.

REMOTE_USER

If the server supports user authentication, and the script is protected, this is the username under which it has been authenticated.

REMOTE_IDENT

If the HTTP server supports RFC 931 identification, then this variable will be set to the remote username retrieved from the server. Usage of this variable should be limited to logging only.

CONTENT_TYPE

For queries which have attached information, such as HTTP POST and PUT, this is the content type of the data.

CONTENT_LENGTH

The length of the said content as given by the client.

Some DTML tags define additional variables. Variables defined by DTML tags take precedence over variables described in table 6. If tags are nested, variables defined in nested tags take precedence over variables defined in tags that are nested in.

Names may not begin with an underscore, except in the special case of the _variable used in an expr attribute expression.

If a variable lookup yields an object that has security information, then access to the variable is allowed only if the user on whose behalf the DTML is being rendered is allowed to access the object.

Previous Chapter | Next Chapter | Up | Next Section | Contents