Understanding Your Application
==============================

Your application is broken up into specific directories, each with their own
purpose.  Using our helloworld example we have the following modules and
directories:

    * helloworld.core
    * helloworld.bootstrap
    * helloworld.controllers
    * helloworld.lib
    * helloworld.model
    * helloworld.templates
    * helloworld.helpers
    
We are going to briefly explain each, and go into more detail later in the 
documentation.


helloworld.core
---------------

This module is the 'core' of your application and is the first phase of the
application runtime where the Cement Framework is initialized.  By default this 
includes the appmain.py and config.py files.  Both of which can be modified, 
but you don't need to.  The core module should be used for any code that sets 
up the base of your application, or provides libraries and functions that are 
not tied to any commands (commands are created in the controllers module).  An 
example of a library that might go into the core module would be code that sets 
up an xmlrpclib proxy object to talk to a remote server.  Most likely you want 
all controllers to access the same proxy object once it is setup.  

It should be noted that plugins should not create files/libraries in this
namespace.


helloworld.bootstrap
--------------------

The bootstrap module is the second phase of the application runtime and is 
used to initialize parts of the application that are required before any
controllers or code is loaded.  Typical uses of the bootstrap module are for:

    * Creating namespaces
    * Defining and registering hooks

The helloworld/bootstrap/root.py is the only bootstrap called by the Cement
Framework, however the 'root' namespace is already setup by Cement and does
not get created in this bootstrap.  That said, any additional bootstrap files
need to be imported into the root bootstrap.  For example, if you are creating
a namespace for 'system' you would create a file at 
helloworld/bootstrap/system.py where you would define and configure that
namespace.  Then, in helloworld/bootstrap/root.py you would import it like:

.. code-block:: python

    from helloworld.bootstrap import system
    

This triggers the system bootstrap which is responsible for setting up the 
system namespace.


helloworld.controllers
----------------------

The controllers module is used primarily for creating commands.  A controller
is attached to a namespace when that namespace is bootstrapped, therefore
you should not import a controller directly anywhere in your application.

Controllers are used to expose commands to your application, and then perform
operations when that command is called.  Ideally it should not present 
output to the user at all, as this is handled by your templates however some
scenarios don't lend themselves well to templating so making print statements
is also possible.  Each command should perform an action and then return a 
dictionary of data.  This dictionary is then used to be rendered into either 
Json, or text by the Genshi Engine. That said, some people will not care to 
use templating and would rather just print output to the console.  This is 
perfectly fine, but may clutter up your controller code with excessive print 
statements and janky formatting.


helloworld.lib
--------------

The lib module is a common place for code that doesn't necessarily fit into
the 'controller', or 'model' modules, but is not necessarily 'core' code.  
Such code might be part of a plugin (which shouldn't create any code in the
core namespace).


helloworld.model
----------------

The model module is used to define objects related to data.  This might be
an SQLAlchemy DeclarativeBase object, or similar data abstractions.  It can
be anything you want, but should be strictly for interfacing with data and 
not interfacing with the user.  

Generally, the controller will use a model object to store data that it is
operating on.  This allows you to separate the code that defines the model
from the other parts of the application that use that model.


helloworld.templates
--------------------

The templates module is a data directory containing nothing but txt template
files.  Note that the first level must be directories related to a namespace.
For example 'helloworld/templates/root' would be the directory with txt
files used for templating commands that are exposed from the root controller.

Cement uses the Genshi Text Template Engine to render the dictionary of data
that your controller function returns.  Documentation can be found at:

    * http://genshi.edgewall.org/wiki/Documentation/text-templates.html 
    
Note that every directory under 'helloworld.templates' must have a __init__.py
file or your application will fail to load templates from it.

    
helloworld.helpers
------------------

Finally, the helpers module is used for miscellaneous code that is used 
throughout your application.  This code should not be namespace or plugin
specific but should be able to be called from anywhere in your application.
Helpers are often used for quick functions that just don't fit anywhere else.

