This file describes the context variables as seen by user code in Python scripts and page templates, as well as the ophelia.request and ophelia.util modules (which are the parts of the Ophelia core most likely to be used in user code) and how to use exceptions for redirecting to another URL and controlling traversal.
For the APIs of the request and input splitter objects, see their user interfaces specified in the ophelia.interfaces module: IRequestAPI and ISplitterAPI.
Scripts are successively run in a namespace freshly initialized by Ophelia with the following variables:
|__file__:||the absolute file system path of the input file|
|__text__:||the text of the current file’s template, as unicode|
|__template__:||the PageTemplate created from the input file’s template text|
|__request__:||the currently running Request instance|
All of the above variables except for __request__ will be reset after each script is run. None of the above names should be assigned to. The template may be influenced by calling its methods; see the zope.pagetemplate documentation.
Additional context variables may be passed to the request when its traverse method (or the request itself) is called. They will be used to update the context namespace before the first script is run on it. When using the WSGI interface, a mapping that contains this additional context may be passed in the environ dictionary under the ophelia.context key.
The context of a page template, i.e. the set of variables that can be accessed by TALES expressions, contains:
variables from the ZPT engine
For documentation, see <http://wiki.zope.org/ZPT/TAL>.
variables added by Ophelia
namespace of compiled macros (see above), contains at this point all macros relevant to the requested path
unicode, the “magic” slot filled by evaluating the next more specific template. Example use:
<div tal:content="structure innerslot">
Making this slot magic avoids writing any boilerplate code at all in run-of-the-mill templates and pages.
all variables in the script context (including those relating to the input file of the template at hand)
Script variables using the same name as a variable defined by ZPT or Ophelia will override that variable.
To use the request or related functionality in a script or Python module:
The module defines the following items meant to be used in client code:
exception, see “controlling traversal” below
exception signalling that some file needed to respond to the request was not found
exception, see “redirection” below
an instance of this class represents the HTTP request and orchestrates the execution of scripts and assembly of the HTTP response.
Please see ophelia.interfaces.IRequestAPI and ophelia.interface.IRequestTraversal for a detailed description of the request API.
function returning the currently running Request instance
function returning the namespace of file-related variables (__file__, __text__, __template__)
Ophelia provides the request.Redirect exception that scripts and add-on libraries may raise to cause the HTTP server to redirect the client to another URI. The exception constructor takes a number of parameters:
|uri:||str, the URI to redirect to, defaults to the original request’s URI|
|path:||str, optional override value for uri’s path portion|
Overriding part of the redirection target is possible purely for convenience. It saves the client some URI manipulation in the simpler use cases.
This is at the edge of Ophelia’s scope.
Raising request.StopTraversal in a script prevents more specific scripts from being executed and the current as well as more specific templates from being evaluated. The exception accepts one optional parameter:
|text:||unicode, template text to use instead of the input file’s text|
The ophelia.util module contains some utilities:
class whose instances do nothing but carry attributes
Not using pure dictionaries here makes for more aesthetic code if nothing else. Namespaces can still be accessed as dictionaries.
like time.strftime, but handles unicode and takes into account the current locale’s character encoding.