3. Configuration

3.1 Intro

The configuration files are written in XML and are very simple. PyWork works with 3 configuration files (you would normally use 2). These are read on the first request the server receives and on every request if specified by the user in pywork.xml.

pywork.xml : Here you will place general stuff like, whether to reload the configuration, the location of your templates or modules, etc.
pywork-map.xml : This is the main conf file where you specify the mapping between the URLs and your PyWork Actions.
pywork-views.xml : This is the one that you commonly wouldnt use, it serves to specify your specialized view handlers. PyWork already comes with 3 view handlers XSTL, ZPT and PYTHON (the last one serves as a general purpose handler, that will let you write PDF, Images, SWF , etc. Anyway you dont need to configure the default view handlers.

3.2 pywork.xml

This the global configuration file for PyWork. Below is the XML schema: (included in the distribution under conf/pywork.xsd)

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xsd:element name="pywork" type="PyWorkType"/>
                                                                                                                                       
<xsd:complexType name="PyWorkType">
    <xsd:sequence>
        <xsd:element name="global" type="GlobalType" maxOccurs="unbounded" minOccurs="0"/>
        <xsd:element name="except" type="ExceptType" maxOccurs="unbounded" minOcccurs="0"/>
    </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="GlobalType">
    <xsd:attribute name="name" use="required" type="xsd:string"/>
    <xsd:attribute name="value" use="required" type="xsd:string"/>
</xsd:complexType>

<xsd:complexType name="ExceptType">
    <xsd:attribute name="class" use="required" type="xsd:string"/>
    <xsd:attribute name="action" use="required" type="xsd:string"/>
</xsd:complexType>

In the pywork.xml file there are a set some global names interpreted by PyWork:

reload. Values 0 or 1. This tells PyWork wheter reload on every request the whole configuration. Set to 1 for development enviroments and to 0 on production sites. (You will need to restart apache if reload is set to 0 to re-read the configuration files)
session. Value a full name python class (module.submodule.Class). With this you can specify your specific mod_python session handler. With mod_python at the time of writing you can use: mod_python.Session.MemorySession or mod_python.Session.DbmSession. If not specified the first available will be used.

Other names specified may be used for configuration vars in the other configuration files, or for your application to get via the Action api. An example would be:

<pywork>
    <global name="reload" value="1"/>
    <global name="PETSTORE" value="/petstore"/>
    <global name="PETSTORE_TEMPLATES" value="/apps.py/petstore/web"/>
</pywork>

Also, (from version 0.4) two new features were added: A new directive, except. This element has a class and and action attribute that tells PyWork to redirect to a specified action uri if that exception is raised. It is handy to define your own exception handling pages. And the use of PythonOption of mod_python. You can specify replacable configuration directives that include PythonOption values. For example, if you have a PythonOption MYCONF myval directive in apache you could use it in a value attribute by specifying:

 <global name="myconf" value="{$MYCONF}"/>

3.3 pywork-map.xml

This file is the most important configuration file. It defines the mapping between the URLs and your PyWork Action classes. Bellow is the XML schema: (included in the distribution under conf/pywork-map.xsd)

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xsd:element name="pywork-map" type="PyWorkMapType"/>
                                                                                                                                       
<xsd:complexType name="PyWorkMapType">
    <xsd:sequence>
        <xsd:element name="action" type="ActionType" maxOccurs="unbounded" minOccurs="0"/>
    </xsd:sequence>
</xsd:complexType>
                                                                                                                                       
<xsd:complexType name="ActionType">
    <xsd:sequence>
        <xsd:element name="alias" type="ActionAliasType" minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="view" type="ActionViewType" minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" use="required" type="xsd:string"/>
    <xsd:attribute name="module" use="required" type="xsd:string"/>
    <xsd:attribute name="class" use="required" type="xsd:string"/>
</xsd:complexType>
                                                                                                                                       
<xsd:complexType name="ActionViewType">
    <xsd:attribute name="name" use="required" type="xsd:string"/>
    <xsd:attribute name="file" use="required" type="xsd:string"/>
    <xsd:attribute name="view-handler" use="optional" type="xsd:string"/>
    <xsd:attribute name="content-type" use="optional" type="xsd:string"/>
</xsd:complexType>

<xsd:complexType name="ActionAliasType">
    <xsd:attribute name="name" use="required" type="xsd:string"/>
</xsd:complexType>
                                                                                                                                       
</xsd:schema>

Here you will specify the URLs mapping. Here is a human description of the file:

action @ name This is the full path of the URL you wish to map
action @ module The python module where the class resides
action @ class The class name that implements pywork.action.Action
action / alias @ name An alias for this action, you can define N-aliases
action / view @ name The string that identifies this view . It serves for the action execute method to request an specific view.
action / view @ file The file to be processed by the view-handler
action / view @ view-handler Optional argument, specifies the view to be used, if not specified PyWork would try to examine the file extension, otherwise the PYTHON view is selected. For ZPT extensions recognized are (.zpt, .zpt.html). For XSLT extension recognized is .xsl .
action / view @ content-type Optional argument, specifies an specific content-type for the response, by default PyWork sets it to "text/html", but you can modify this behaviour for JPEGs, XMLs, etc, by setting it here.

For each url in your site (you wish to process with PyWork) you must define an "action" xml element where the full virtual path of the uri must be specified in name. For example http://mysite.mydomain/myapp/login.action , would be "/myapp/login.action". Normally you would specify "/myapp/"as a global name in pywork.xml, like

...
	<global name="MYAPP" value="/myapp/"/>
...

And then in the action name you could simple write:

 
...
	<action name="${MYAPP}/login.action" ...
...

Furthermore, you may specify aliases to your action. Using the "alias"XML element, with the name attribute.

For each action you would normally specify one or more views to process. This views are selected with the name depending on the result of your action execute method. See the Action chapter for more information

3.4 pywork-views.xml

This the views configuration file for PyWork. Below is the XML schema: (included in the distribution under conf/pywork-views.xsd)

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xsd:element name="pywork-views" type="PyWorkViewsType"/>
                                                                                                                                       
<xsd:complexType name="PyWorkViewsType">
    <xsd:sequence>
        <xsd:element name="view-handler" type="ViewHandlerType" maxOccurs="unbounded" minOccurs="0"/>
    </xsd:sequence>
</xsd:complexType>
                                                                                                                                       
<xsd:complexType name="ViewHandlerType">
    <xsd:attribute name="name" use="required" type="xsd:string"/>
    <xsd:attribute name="class" use="required" type="xsd:string"/>
    <xsd:attribute name="module" use="required" type="xsd:string"/>
</xsd:complexType>
                                                                                                                                       
</xsd:schema>

Here you will specify any specialized View Handlers you have written. This is the human description of the file:

view-handler @ name This is the name of your view-handler You will need to specify this name in the map definition if you want to use this view.
action @ module The python module where the class resides
action @ class The class name that implements pywork.view.ViewHandler

Normally you would write a View Handler if you want to implement your specialized templating system.

See About this document... for information on suggesting changes.