Ophelia API and predefined script and template variables
========================================================


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.


Script context
--------------

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.


Page template context
---------------------

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

  - CONTEXTS
  - nothing
  - default
  - repeat
  - modules
  - loop

  For documentation, see <http://wiki.zope.org/ZPT/TAL>.

* variables added by Ophelia

  :macros: namespace of compiled macros (see above), contains at this point
      all macros relevant to the requested path

  :innerslot: 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.


The ophelia.request module
--------------------------

To use the request or related functionality in a script or Python module::

   import ophelia.request

The module defines the following items meant to be used in client code:

:StopTraversal: exception, see "controlling traversal" below

:NotFound: exception signalling that some file needed to respond to the
    request was not found

:Redirect: exception, see "redirection" below

:Request: 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.

:get_request: function returning the currently running Request instance

:get_file_context: function returning the namespace of file-related variables
    (__file__, __text__, __template__)


Redirection
-----------

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.


Controlling traversal
---------------------

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


Utilities
---------

The ophelia.util module contains some utilities:

:Namespace: 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.

:strftime: like ``time.strftime``, but handles unicode and takes into account
    the current locale's character encoding.


.. Local Variables:
.. mode: rst
.. End:
