Installation¶

Sprox is installable from pypi.:

easy_install sprox

Schema Based Widget Generation¶

Well, that’s a mouthfull! Sprox provides a bridge between database schema and the forms you want to customize for the web. Sprox has an IProvider, which basically tells sprox how to interpret data extracted from the database manipulation library. Sprox comes packaged with a provider for SQLAlchemy. It is important to understand that Sprox expects that the database manipulation library will have a unique way to map database objects to table schema. The mapped objects are often referred to as models, in Sprox, these are called entities, because Sprox has abstracted the manipulation of table and field schema to the point where they interface other parts of the system in a similar manner.

SQLAlchemy’s Object Relational Mapper provides a basis for many of the examples in this documentation. Here is the Model used in this documentation.

Form Generation¶

Sprox has a simple but powerful way to generate forms. Here is the simplest way to create a form based on a “User” class.:

from sprox.formbase import AddRecordForm

class UserForm(AddRecordForm):
    __model__ = User

user_form = UserForm(DBSession)

That form can then be passed into a template, just like if it were a regular ToscaWidgets form. But you ask, “Why do you need to pass in the DBSession?” Well, in fact the session is not required to be passed in, but if you want Sprox to pick up the data for the drop-down menus, and multiple select fields, it needs a way to connect to the database in order to get the appropriate data. You might say, “Ok, but that form gives me a lot of junk I don’t want, and the password field is going to have to be verified if we wanted to say, make a registration form.” Well, remember Sprox is fully customizable. Here is an example registration form based on Sprox, complete with password validation.:

from sprox.formbase import AddRecordForm
from formencode import Schema
from formencode.validators import FieldsMatch
from tw.forms import PasswordField, TextField

form_validator =  Schema(chained_validators=(FieldsMatch('password',
                                                         'verify_password',
                                                         messages={'invalidNoMatch':
                                                         'Passwords do not match'}),))
class RegistrationForm(AddRecordForm):
    __model__ = User
    __require_fields__     = ['password', 'user_name', 'email_address']
    __omit_fields__        = ['_password', 'groups', 'created', 'user_id', 'town_id']
    __field_order__        = ['user_name', 'email_address', 'display_name', 'password', 'verify_password']
    __base_validator__     = form_validator
    email_address          = TextField
    display_name           = TextField
    verify_password        = PasswordField('verify_password')

registration_form = RegistrationForm(DBSession)

Which makes a form that looks something like this:

Notice first that we have made three fields required set the order, and omitted the fields that we do not want in the form. Also, we overrode the widget type for email_address and display_name (The default was a text area). Lastly we add a verify_password field that is not in the current schema. Also keep in mind that if you were to alter the schema for your database, any fields you added to your User model would also be added to this form. If you wanted to avoid this, you would use __limit_fields__ instead of __omit_fields__. There are many other __modifiers__ for FormBase in Sprox, you can use them to generate the forms you desire in any number of combinations. For more information see sprox.formbase and sprox.fillerbase.

Table Generation¶

Most people look for things that render forms, but fail to realize that generating tabular formed data provides almost the same challenge. After all, in an editable form, you must retrieve the data from the database in order to fill in the form entries. Well, Sprox makes this easy too. Here is some code to list out the users and their email addresses:

from sprox.tablebase import TableBase
from sprox.fillerbase import TableFiller

class UserTable(TableBase):
    __model__ = User
    __limit_fields__ = ['display_name', 'email_address']

user_table = UserTable(DBSession)

class UserTableFiller(TableFiller):
    __model__ = User
    __limit_fields__ = ['user_id', 'display_name', 'email_address']

user_table_value = UserTableFiller(DBSession).get_value()

And your template code would look like this:

${user_table_form(value=user_table_value)}

Rendered, the table would look like this:

Keep in mind that since the form generators are declarative, you can use mixins and other class trickery to reduce your code further (although it is not advised to use this to fool your fellow developer). Can you think of a way to reduce the 14 lines of python code above to 8?

Sprox, the big picture¶

In reality, Sprox is not about making your code smaller, but making it _smarter_. Since you have a declarative base to work from, you can subclass a set of widgets that fits your application. You can provide customized widget selectors which tell Sprox which widgets to use for which fields. Because Sprox gives you the power to customize any part of the form at any level of abstraction, you can create your own form generation based on the requirements for your project.

• Table Tutorial
• Form Tutorial

• Class Diagram

$ nose --with-coverage --cover-package=sprox --cover-erase
...
Name                         Stmts   Miss  Cover   Missing
----------------------------------------------------------
sprox                            0      0   100%
sprox._validatorselector        26      0   100%
sprox._widgetselector           15      0   100%
sprox.configbase                78      0   100%
sprox.dojo                       0      0   100%
sprox.dojo.fillerbase           14      0   100%
sprox.dojo.formbase             24      0   100%
sprox.dojo.sprockets            18      0   100%
sprox.dojo.tablebase            30      0   100%
sprox.dummyentity                1      0   100%
sprox.entitiesbase              15      0   100%
sprox.fillerbase               102      0   100%
sprox.formbase                 156      0   100%
sprox.iprovider                 51      0   100%
sprox.metadata                  53      0   100%
sprox.mg                         0      0   100%
sprox.mg.provider              236      0   100%
sprox.mg.validatorselector      25      0   100%
sprox.mg.widgetselector         35      0   100%
sprox.mk                         0      0   100%
sprox.mootools                   0      0   100%
sprox.providerselector          85      0   100%
sprox.recordviewbase            15      0   100%
sprox.sa                         0      0   100%
sprox.sa.provider              391      0   100%
sprox.sa.validatorselector      30      0   100%
sprox.sa.widgetselector         37      0   100%
sprox.sprockets                 55      0   100%
sprox.tablebase                 45      0   100%
sprox.util                      42      0   100%
sprox.validators                11      0   100%
sprox.validatorselector          6      0   100%
sprox.viewbase                 128      0   100%
sprox.widgets                    1      0   100%
sprox.widgets.dojo              85      0   100%
sprox.widgets.templates          0      0   100%
sprox.widgets.widgets           90      0   100%
sprox.widgetselector             6      0   100%
----------------------------------------------------------
TOTAL                         1906      0   100%
----------------------------------------------------------------------
Ran 369 tests in 7.971s

• sprox.formbase
• sprox.tablebase
• sprox.fillerbase
• sprox.configbase
• sprox.viewbase
• sprox.entitiesbase
• sprox.recordviewbase
• sprox.validators
• sprox.sprockets
• sprox.metadata
• sprox.iprovider
• sprox.widgets
• sprox.util

• sprox.sa.provider
• sprox.sa.widgetselector
• sprox.sa.validatorselector

• sprox.mg.provider
• sprox.mg.widgetselector
• sprox.mg.validatorselector

• General Dojo Usage Information
• sprox.dojo.tablebase
• sprox.dojo.fillerbase
• sprox.dojo.formbase

• sprox.mootools.formbase

• test_model