
formalchemy
Code has moved
FormAlchemy is now hosted on GitHub
The full documentation is here
Introduction
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.
Features
- Generates HTML form fields and tables from SQLAlchemy mapped classes or manually added Fields
- Works with declarative or classic mapper definitions
- Render and edits single objects or collections (grids)
- Handles object relationships (including many-to-many), not just simple data types
- Synonym support
- Composite and custom type support
- Supports all composite primary keys and most CFKs
- Pre-fills input fields with current or default value
- Highly customizable HTML output
- Validates input and displays errors in-line
- Syncs model instances with input data
- Easy-to-use, extensible API
- SQLAlchemy 0.4 (0.4.5 or later) and 0.5 compatible
Limitations
- Currently, only handles composite foreign keys of primitive Python types
Installation
Check out the instructions for InstallingFormAlchemy.
Quick introduction
To get started, you only need to know about two classes, FieldSet
and
Grid
, and a handful of methods:
render
: returns a string containing the htmlvalidate
: true if the form passes its validations; otherwise, falsesync
: syncs the model instance that was bound to the input data
This introduction illustrates these three methods. For full details on
customizing FieldSet
behavior, see the documentation.
We'll start with two simple SQLAlchemy models with a one-to-many relationship
(each User
can have many Order
s), and fetch an Order
object to edit:
from formalchemy.tests import Session, User, Order
session = Session()
order1 = session.query(Order).first()
Now, let's render a form to edit the order we've loaded.
from formalchemy import FieldSet, Grid
fs = FieldSet(order1)
print fs.render()
This results in the following form elements:
Note how the options for the User input were automatically loaded from the
database. str()
is used on the User objects to get the option descriptions.
To edit a new object, bind your FieldSet
to the class rather than a specific instance:
fs = FieldSet(Order)
To edit multiple objects, bind them to a Grid
instead:
orders = session.query(Order).all()
g = Grid(Order, orders)
print g.render()
Which results in:
Saving changes is similarly easy. (Here we're using Pylons-style request.params()
;
adjust for your framework of choice as necessary):
fs = FieldSet(order1, data=request.params())
if fs.validate():
fs.sync()
session.commit()
Grid
works the same way.
Full Documentation
FormAlchemy's documentation is available here. Some good starting points are * Using Forms in Controllers -- a complete example for Pylons. Other MVC frameworks should look similar. * Configuring forms -- the gory details on getting what you want and only what you want in your form * A lot of people want the Pylons admin interface * If you are starting a new Pylons projects, FormAlchemy has paster support to set things up automagically
Copyright and License
Copyright (C) 2007 Alexandre Conrad, alexandre dot conrad at gmail dot com
FormAlchemy is released under the MIT License.
Project Information
- License: MIT License
- 76 stars
- hg-based source control
Labels:
python
sqlalchemy
forms
validation
tables
html
mako
tempita
elixir