/docs/shabti_templates/shabti_formalchemy.rst

.. _shabti_formalchemy:

|today|

.. _shabti-formalchemy:

**shabti_formalchemy** -- "Pylons Admin" Web UI
===============================================

.. note:: This Shabti template was kindly contributed by Ga??l Pasgrimaud of the Formalchemy development team.

.. rubric :: This template is a basic :ref:`shabti auth <shabti-auth>` setup which has been configured to use the `Formalchemy <http://code.google.com/p/formalchemy/>`_ package. Formalchemy generates HTML form fields and tables from SQLAlchemy mapped classes or manually added Fields. And, also, Elixir mapped classes. In this template, the standard Shabti identity model is coupled with FormAlchemy's "Pylons Admin" facility to produce an auto-generated facility for administrating the population of the identity model. 

In essence this template provides an out-of-the-box web interface for maintaining a lightweight identity model of Users, Groups and Permissions. Using the Pylons Admin interface is straightforward, direct and the interface itself is quite self-explanatory.

.. note :: shabti_formalchemy source code is in the `bitbucket code repository <http://bitbucket.org/gjhiggins/shabti/src/tip/shabti/templates/formalchemy/>`_


About Formalchemy
-----------------

The following description is taken from the `Formalchemy project web site <http://code.google.com/p/formalchemy/>`_ ...

"FormAlchemy greatly speeds development with SQLAlchemy mapped classes (models) in a HTML forms environment.

FormAlchemy eliminates boilerplate by autogenerating HTML input fields from a given model. FormAlchemy will try to figure out what kind of HTML code should be returned by introspecting the model's properties and generate ready-to-use HTML code that will fit the developer's application.

Of course, FormAlchemy can't figure out everything, i.e, the developer might want to display only a few columns from the given model. Thus, FormAlchemy is also highly customizable."

.. seealso:: For further details, see the project `documentation <http://docs.formalchemy.org/>`_


Dependencies
------------

You need to ``easy-install FormAlchemy`` and  ``easy-install fa.jquery`` before using the template.

Using the template
------------------

After successfully installing Shabti, additional paster templates will be available. Simply create a Shabti-configured project by specifying that paster should use the shabti_formalchemy template:

.. code-block :: bash

    $ paster create -t shabti_formalchemy myproj

These are the option dialogue choices appropriate for the Shabti auth shabti_formalchemy template --- which uses mako templates and requires SQLAlchemy  ...

.. code-block :: bash

    (mako/genshi/jinja/etc: Template language) ['mako']: 
    (True/False: Include SQLAlchemy 0.4 configuration) [False]: True

Once the project has been created, navigate to the project directory.

The next step is to initialise the database by running the project setup script which will create the initial entries.

.. code-block :: bash

    $ paster setup-app development.ini

The next (optional) step after initialising the relational store is to run the tests.

.. code-block :: bash
    
    $ nosetests
    
8/10 tests should run successfully. Two are known to fail but these failures appear to be restricted to the test environment, normal functioning remains unaffected.

Running the generated app
-------------------------

After initialising and testing, start the Pylons web app with:

.. code-block :: bash

    $ paster serve --reload development.ini

The Shabti Formalchemy template's variant on the standard Pylons welcome screen is browsable at at ``http://localhost:5000/`` ...



Welcome screen
^^^^^^^^^^^^^^

.. image:: images/shabti_formalchemy_welcome.jpg
   :align: center


.. note:: The identity admin interface is pre-rolled and is accessible via the "Admin WUI" link.


Template details
----------------

This template is an extension of the standard :ref:`shabti auth <shabti-auth>` template that adds and routes an "admin" controller for the CRUD operations on the identity model and an ancillary "jquery" controller whose sole purpose is the handling of the resolution of JQuery libs.

The "admin" controller imports the standard Shabti Elixir-mapped identity model of User, Permission and Group entities and hooks them up to FormAlchemy:

.. code-block:: python

    import logging
    from MYPROJ.lib.base import BaseController, render
    from MYPROJ import model
    from MYPROJ import forms
    from formalchemy.ext.pylons.admin import FormAlchemyAdminController

    log = logging.getLogger(__name__)

    class AdminController(BaseController):
        model = model # where the Elixir mappers are
        forms = forms # module containing FormAlchemy fieldsets definitions
        # # Uncomment this to impose an authentication requirement
        # @authorize(SignedIn())
        # def __before__(self):
        #     pass
        def Session(self): # Session factory
            return meta.Session

    AdminController = FormAlchemyAdminController(AdminController)

(Note the commented-out code for access-protecting the Pylons Admin controller. Uncommenting the code will cause requests made of ``/admin`` resources to be automatically redirected to a login page and, upon successful authentication, will be automatically redirected to the originally-requested resource.)

The routing is simple and straighforward:

.. code-block:: python

    from formalchemy.ext.pylons import maps # routes generator

    # [ ... ]

    # CUSTOM ROUTES HERE

    # Map the /admin url to FA's AdminController
    # Map static files
    map.connect('fa_static', '/jquery/{path_info:.*}', 
                controller='jquery')
    # Index page
    map.connect('admin', '/admin', 
                controller='admin', action='models')
    map.connect('formatted_admin', '/admin.json', 
                controller='admin', action='models', format='json')
    # Models
    map.resource('model', 'models', path_prefix='/admin/{model_name}', 
                 controller='admin')

The form templating engine (by default Tempita but in this instance, Mako) is initialised and the JQuery-supported fieldset and grid form holders are all defined in ``MYPROJ/form/__init__.py``:

.. code-block:: python

    from pylons import config
    from fatest import model
    from fatest.lib.base import render
    from formalchemy import config as fa_config
    from formalchemy import templates
    from formalchemy import validators
    from formalchemy import fields
    from formalchemy import forms
    from formalchemy import tables
    from formalchemy.ext.fsblob import FileFieldRenderer
    from formalchemy.ext.fsblob import ImageFieldRenderer
    from fa.jquery import renderers as jquery

    if config.get('storage_path'):
        # set the storage_path if we can find its setting
        FileFieldRenderer.storage_path = config.get('storage_path')
        ImageFieldRenderer.storage_path = config.get('storage_path')

    fa_config.encoding = 'utf-8'

    class TemplateEngine(templates.TemplateEngine):
        def render(self, name, **kwargs):
            return render('/forms/%s.mako' % name, extra_vars=kwargs)
    fa_config.engine = TemplateEngine()

    # use jquery renderers
    forms.FieldSet.default_renderers.update(jquery.default_renderers)

    class FieldSet(forms.FieldSet):
        pass

    class Grid(tables.Grid):
        pass

    ## Initialize fieldsets

    User = FieldSet(model.User)
    User.configure(options=[User.created.readonly()])

    UserAdd = FieldSet(model.User)
    UserAdd.configure(exclude=[UserAdd.created])

    ## Initialize grids

    UserGrid = Grid(model.User)
    UserGrid.configure(include=[
        UserGrid.username,
        UserGrid.email,
        UserGrid.active,
        UserGrid.groups,
        ])

A set of FA's CSS grid-styled Mako templates are installed into the ``myproj/templates`` directory and the application is immediately ready for use.

Screenshots
-----------

View of the Shabti standard identity model
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. image:: images/shabti_formalchemy_admin.jpg
   :align: center


View of the User admin page
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. image:: images/shabti_formalchemy_user_index.jpg
   :align: center

Editing an existing User entity
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. image:: images/shabti_formalchemy_user_edit.jpg
   :align: center

Creating a new user entity
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. image:: images/shabti_formalchemy_user_new.jpg
   :align: center


.. seealso:: Form structure, content and appearance can all be customized. For details on how to customize the forms and the fields, see the docs for the `Formalchemy Pylons extension <http://docs.formalchemy.org/current/ext/pylons.html#customization>`_

TODO
----

1. Adjust the generation of the form so that password fields are presented unpopulated.

2. Find out why the 2 authentication tests fail.

3. Add a more extensive example, demonstrating more of FormAlchemy's features.

4. Add FormAlchemy and the `CouchDBkit Formalchemy extension <http://couchdbkit.org/docs/formalchemy.html>`_ to the Shabti auth_couchdb template.

:author: Graham Higgins <gjh@bel-epa.com>

|today|