===================
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.

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".
