formalchemy.ext.pylons – Pylons extensions

Administration interface

Purpose

The Pylons administration interface provides a simple way to enable CRUD (create, retrieve, update, delete) operations on your SQLAlchemy models, with a high degree of customizability.

Sample model listing:

Sample model overview page:

Sample model creation page:

Setup

First, generate a controller in your application:

$ paster controller admin

Next, edit your controllers/admin.py, replacing yourapp with your application name:

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

log = logging.getLogger(__name__)

class AdminController(BaseController):
    model = model # where your SQLAlchemy mappers are
    forms = forms # module containing FormAlchemy fieldsets definitions
    def Session(self): # Session factory
        return meta.Session

AdminController = FormAlchemyAdminController(AdminController)

Add these lines in config/routing.py:

"""Routes configuration

The more specific and detailed routes should be defined first so they
may take precedent over the more generic routes. For more information
refer to the routes manual at http://routes.groovie.org/docs/
"""
from pylons import config
from routes import Mapper
from formalchemy.ext.pylons import maps # routes generator

def make_map():
    """Create, configure and return the routes Mapper"""
    map = Mapper(directory=config['pylons.paths']['controllers'],
                 always_scan=config['debug'])
    map.minimization = False
    
    # The ErrorController route (handles 404/500 error pages); it should
    # likely stay at the top, ensuring it can always be resolved
    map.connect('/error/{action}', controller='error')
    map.connect('/error/{action}/{id}', controller='error')

    # CUSTOM ROUTES HERE
    # Map the /admin url to FA's AdminController
    maps.admin_map(map, controller='admin', url='/admin')

    map.connect('/{controller}/{action}')
    map.connect('/{controller}/{action}/{id}')

    return map

All done! Now you can go to the /admin/ url.

Customization

FormAlchemyAdminController creates a new class having AdminControllerBase and the internal FA admin controller (formalchemy.ext.pylons.AdminController) as its parent classes, in that order.

So, you can do simple customization just by overriding the admin controller methods (index, list, edit, delete – create is just edit with id=None) in AdminControllerBase, e.g.,:

class AdminControllerBase(BaseController):
    ...

    @auth_required
    def edit(self, *args, **kwargs):
        return super(AdminControllerBase, self).edit(*args, **kwargs)

To customize the forms used to list and edit your objects, create a module yourapp.forms and specify that as the forms module in AdminController. In this module, create FieldSet (for create and edit forms) and Grid (for object lists) instances for the models you wish to customize. (The Grids will automatically get edit and delete links added, and be made readonly.)

See forms for details on form configuration.

Troubleshooting

If you click on a model link from the top-level admin page and get “NotImplementedError: Action ‘<modelname>’ is not implemented,” then your routing hasn’t been properly configured for the admin app. See “Add these lines in config/routing.py” above.

If you don’t see all your models on the top-level admin page, you’ll need to import them into your model module, or tell FormAlchemy the correct module to look in (the “model = ” line in the controller class you created). In particular, FormAlchemy does not recursively scan for models, so if you have models in e.g., model/foo.py, you will want to add from foo import * in model/__init__.py.

Sample app

You can have a look at the complete source of the application used for FA’s testing.