How to setup Aquarium with mod_python
Bob Van Zant
bob@norcalttora.com

- Install mod_python
- Install cheetah
- Install aquarium

In this state, mod_python is probably totally useless. Here is a sample
Directory:


<Directory "/usr/local/www/data">

    PythonPath "['/usr/local/www/data'] + sys.path"
    AddHandler python-program .py
    PythonHandler index
    PythonDebug On

    Options Indexes FollowSymLinks
    AllowOverride None
    Order allow,deny
    Allow from all

</Directory>


With that setup you should now be able to run a "stupid" demo of mod_python.
Try putting a file named index.py with this as its contents in your
/usr/local/www/data directory:

        from mod_python import apache

        def handler(req):
            req.write("Wow. So useful")
            return apache.OK

Note that from above "PythonHandler" determines the names of the files that
mod_python will try to handle. The extension is set by the AddHandler directive
and the filename by PythonHandler. In other words, mod_python will only execute
index.py files. Now visit your webserver.


Now let's try getting aquarium working.

-) Create some directories. Of most importance you'll need an htdocs
   directory, or somewhere to put an index.py and a site-packages directory
   which will become the root of your application. Within site-packages let's
   create a conf and a screen subdirectory.

-) Create the cheetah cache directory. mkdir ~/.cheetah and chmod or chown it
   so that your webserver can write to it.

-) Copy AquariumProperties.py from the demo/seamstress_exchange/site-packages/conf
   directory into your own site-packages/conf directory. Edit the file
   accordingly. For this initial setup, let's turn off Databases and Gettext
   because at this point all they could possibly do is make this first time
   setup ridiculously hard. Also, let's change DEFAULT_SCREEN to "test"

-) Edit the .py from before. We're going to change it up quite a bit now to
   tell it to load up the aquarium app framework. Mine looks like this:

        from mod_python import apache

        import __main__
        import sys
        __main__.packagePath = ["/home/bob/public_html/aquarium/site-packages"] + sys.path

        def handler(req):
            from aquarium.util.Aquarium import Aquarium
            from aquarium.wsadaptor.ModPythonAdaptor import ModPythonAdaptor
            Aquarium(ModPythonAdaptor(req))()

            return apache.OK


-) Create a screen directory in your site-packages. Add the file "test.tmpl"
   and have it contain:
   #extends aquarium.layout.CssAndJavaScript

   #def __call__
   Testing
   #end def

-) You should now be able to access your new aquarium website. The URL to get
   to your website is the same as it was before when you tested the "stupid"
   mod_python issue.

-) If you're getting a Not Found error, view the HTML source of the error and
   you should be treated to a more specific error.

-) If you're getting some crazy message about double exceptions and "I'm
   giving up" examine the first traceback at the top of the exception, it will
   be the most useful to you.

-) Assuming everything is working now, let's make our example slightly more
   complex. Rename test.tmpl to be index_view.tmpl. Create a new file,
   index.py, in the screen directory. So index.py will be side by side with
   index_view.tmpl. The contents of this index.py should be:

        from Controller import Controller

        class index(Controller):

            def __call__(self, *args, **kargs):
                self._ctx.iLib.forward("index_view")

   This file isn't very interesting, it's simply forwarding to index_view.tmpl
   for display by the browser.

-) When that is all working, we have a very simple view-controller paradigm
   present. But still, our example is not very exciting, we don't have a good
   way of "pushing" data from the controller to the view. Let's fix that.

   Let's start with index.py. I'm going to make my bean an instance of
   ContainerClass so that it is easy to use.

        from Controller import Controller
        from aquarium.util.ContainerClass import ContainerClass

        class index(Controller):

            def __call__(self, *args, **kargs):
                bean = ContainerClass()
                bean.subTitle = "Welcome to my test screen"
                bean.things = range(10)
                self._ctx.iLib.forward("index_view")

   Modify index_view.tmpl's __call__ method to accept an argument, we'll call
   it the bean.

        #def __call__($bean)
            <h1>$bean.subTitle</h1>
            <ul>
            #for $thing in $bean.things
              <li>$thing
            #end for
            </ul>
        #end def