===================
Configuring Ophelia
===================


Configuration files
===================

Ophelia comes with a number of clients that all exercise its request handler,
but have different configuration mechanisms. The wsgiref-based HTTP server and
the ``ophelia-dump`` script read their configuration from a section of an
INI-style configuration file while the mod_python handler gets the same
information from PythonOption variables set in the Apache configuration.
Example configurations can be found below.

Two variables must always be present:

:template_root:
    The file system path to the template root directory.

:site:
    The absolute URI of the Ophelia site's root, i.e. that part of a page's
    URI that is the same for all pages served from the template directory.

In addition, the variables described below may be specified in order to
influence the request handler's behaviour. All of them have sensible default
values. They will end up in the environment namespace stored on the request
object, along with any other variables that are not recognized by Ophelia.
This allows configuring Python modules and scripts that belong to your site's
content.

While the above pertains to all three clients, the wsgiref server needs
additional information:

:host:
    The network interface to bind to.

:port:
    The TCP port to listen at on that interface.

For boolean variables such as redirect_index, the values "on", "true", or
"yes" (case-insensitive) are taken to mean True, anything else means False.


URL canonicalization and redirection
====================================

If a requested URL points to a directory, Ophelia will try to find a template
with a special file name and build the "index" page from that. There are two
configuration options concerned with the index template:

:index_name:
    The name of the index template Ophelia looks for. It defaults to
    "index.html".

:redirect_index:
    Whether to canonicalize the URL and redirect the browser if the path
    portion of the URL ends with the default index page's name. This option is
    turned off by default.


Character encoding
==================

Input encoding
--------------

By default, Ophelia expects Python scripts and TAL templates it reads from
input files to be in 7-bit ASCII encoding. There are several ways to override
this default.

You can declare a character encoding both for the Python script and the
template, and the two encodings may differ. To specify the Python encoding,
just start the script with a Python style encoding declaration like this::

# -*- coding: utf-8 -*-

The template's encoding is determined by looking at the "<?xml?>" tag::

<?xml coding="utf-8" ?>

specifies UTF-8 encoding for the template. The tag itself will be stripped
from the template and will not appear in the rendered page.

You may also specify a default encoding for any scripts and templates to be
read later during traversal. In a Python script, just do something like

::

    __request__.splitter.script_encoding = "utf-8"
    __request__.splitter.template_encoding = "utf-8"

A site-wide default can be set through options:

:script_encoding:
    Encoding of Python scripts found in input files, defaults to "ascii".

:template_encoding:
    Encoding of TAL templates found in input files, defaults to "ascii".

Response encoding
-----------------

Ophelia uses unicode internally, but an HTTP response consists of one-byte
characters, so some encoding has to be applied in the end. This encoding is
automatically declared in the page's XML declaration as well as the response
headers. By default, Ophelia encodes responses using UTF-8.

To set the response encoding to, say, latin-1 for a particular resource, do

::

    __request__.response_encoding = "latin-1"

in a script. To affect the response encoding site-wide, set an option:

:response_encoding:
    Encoding of the HTTP response body, default to "utf-8".


Processing of the result
------------------------

By default, the page body is encoded with the response encoding and prefixed
with an XML declaration before being returned by Request.build(). This can be
prevented by an option if the returned value is going to be processed further
instead of being sent directly to the client:

:immediate_result:
    Whether to use the unprocessed result of template evaluation as the
    response content.


Example configuration for an Apache/mod_python installation
===========================================================

Assume that the root of your site is published at
``<http://www.example.com/foo/bar/>``.

Assume further that your site uses the following file system locations on a
Unix system:

:/var/example/templates/: for the tree of Ophelia templates
:/var/example/python/:    for the Python packages
:/var/example/static/:    for the static stuff

To publish this site, add the following to your host's config::

    Alias /foo/bar /var/example/static
    <Location "/foo/bar">
        PythonInterpreter main_interpreter
        PythonPath "['/var/example/python'] + sys.path"
        PythonOption template_root /var/example/templates
        PythonOption site http://www.example.com/foo/bar/
        PythonFixupHandler ophelia.modpython
    </Location>

This instructs Apache to let Ophelia handle any URI under /foo/bar/. Ophelia
will build pages from templates where they exist, and Apache will serve files
from your static content otherwise.

It is possible to set the Ophelia handler only for directories or HTML
documents by applying some path name heuristics and matching the location
against a regular expression.

Due to an interaction between Python's restricted mode and how mod_python
creates multiple Python interpreters, Ophelia must run in mod_python's main
Python interpreter. This means that if more than one Ophelia site is hosted by
the same Apache process, they cannot be isolated from each other.


Example configuration for the included WSGI server
==================================================

Create a configuration file, say, opheliasite.cfg::

    [DEFAULT]
    host = 127.0.0.1
    port = 8080
    template_root = /var/example/opheliasite
    site = http://localhost:8080/

and run the ophelia-wsgiref script on that file::

    ophelia-wsgiref -c opheliasite.cfg

You may want to wrap this call in a run-control script.

The same configuration can be used with the ophelia-dump script, except that
it doesn't require the host and port to be set.


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