Zblog Demo Application

Yes, its a blog. Probably not a blog app you'd want to use anywhere, although
it could be taken as a starting point to building a more featured application.
Its pretty much a plain white interface that lets you create users, blogs,
blog posts, and comments, with everything reading fresh from the database,
i.e. no file generation or caching or anything.

The point of it is to illustrate a fairly powerful application layout, which
includes Ajax functionality, basic SQLAlchemy integration, a rudimentary
security framework, and form-handling paradigms that work across regular and
Ajax-style layouts.

ARCHITECTURE
------------
The blog application is basically providing a management interface to the
following graph of objects:

        Users
          |
          +----Blogs <-TopicAssociations-> Topics
                 |
                 +----Posts
                        |
                        +---Comments<--+
                               +       |
                               |       |
                               +-------+

The application is laid out something like this:

Server                       Application                Persistence
------                       ---------------------      ------------
bin/server.py           ---> lib/zblog/__init__.py -->  lib/zblog/database/tables.py
config/server_config.py      config/config.py           lib/zblog/database/mappers.py

                                                                    |
                                                                    v
View                Controller                           Domain
-----               -----------                          --------
htdocs/*.myt    <-- lib/zblog/controller/__init__.py <-- lib/zblog/domain/user.py
components/*.myc    lib/zblog/controller/front.py        lib/zblog/domain/blog.py
                    lib/zblog/controller/*.py            lib/zblog/domain/actions.py
                    lib/zblog/util/form.py 

Not included above are a few modules in the "bootstrap" category, which are
involved with auto-configuring the application and creating its database
tables when it is run for the first time.

Server
------
The server modules deal with running the application. bin/server.py is a basic
Myghty HTTPServerHandler runner, which reads the interpreter configuration
from config/server_config.py. Other runners, such as WSGI, Paste, mod_python,
etc. can be used instead with server_config.py.

Application
-----------
The base application includes the zblog __init__.py module, which provides
some initialization functions and the ability for other packages to add
themselves to the overall startup process, and the config.py configuration
which includes application-wide config. This file is generated by the initial
"bootstrap" runner.

Persistence
-----------
tables.py defines the SQLAlchemy table metadata for all tables, which is also
used to create the tables, and mappers.py defines the datamapping
relationships from the tables to the domain objects.

Domain
------
this is the center of the app, user.py includes a User object as well as some
basic crypt() functions for passwords, and blog.py includes all the rest of
the objects represented. actions.py defines a set of Action objects which
correspond to specific user actions and states. A single method access()
provides a yes/no response indicating if a particular action is allowed.

Controller
----------
The base controller class is in __init__.py, and an application-wide "front"
controller is in front.py. All HTTP requests, including Ajax calls, go through
the front controller. The front controller then locates the actual controller
to be called, examines its security attributes which may also include an
actions.Action object, and either passes along or raises a 403 return code.

The security attributes are set via a decorator, and this decorator is the
primary method of marking a particular controller method as publically
accessible. The front controller uses its own "resolver context" in order to
locate the secondary controller object; this context is configured in
config/server_config.py.

Each controller then handles its appropriate section, and makes heavy use of
the Form objects defined in util/form.py in order to send information about
form status to views.

View
----
All the Myghty templates, HTML, JS, CSS, including the Myghtyjax files. Form
handling is largely assisted by the components/components.myc package which
provides formfield rendering methods that integrate with the util/form.py
objects.
                      
RUNNING THE DEMO
----------------
1. We're using decorators, so you should use Python 2.4 or greater.
2. insure that SQLAlchemy is installed (http://www.sqlalchemy.org/).
3. insure that this latest source tree of Myghty is either installed or in the
PYTHONPATH.
4. insure that either pysqlite, psygopg/Postgres, mysqldb/mysql is installed (or
Oracle/cx_Oracle, but not tested as much).
5. run the server:  python ./bin/server.py
6. Go to the URL:  http://localhost:8080/
7. A "bootstrap" page should appear. enter an admin username, password, and
set up database parameters (foolproof defaults are provided for SQLite), then
press "connect" to try connecting to the database.
8. when connect is successful, press "create config file". this should bounce
to a textual screen of table create statements. it also writes a config file
in ./config/config.py .
9. to login, press "login" and login as the administrator user.
10. create a few test users, and a few "blogs". Then maybe a few posts inside
the blogs.
11. the console where the server.py is running should be dumping all the HTTP
requests as well as all the SQL calls and their results. The logging of SQL
calls can be switched off in the config/config.py file.
12. watch what happens when you create a user, then create some blogs for that
user. then delete the user. All the blogs, posts, comments owned by that user
(and comment replies) get deleted too ! amazing. the mapping relationships are
completely defined within lib/zblog/database/mappers.py.
