.. _Pyramid: http://docs.pylonsproject.org/
.. _Colander: http://docs.pylonsproject.org/projects/colander/dev/
.. _Mail: mailto:aachurin@gmail.com

Installation Instructions
-------------------------

::

  pip install smallform

Basic Usage
-----------

The steps a developer must take to cause a form to be ready to accept are:
 - Define a schema
 - Create a form object
 - Validate a form

Defining A Schema
-----------------
The first step to using Smallform is to create a schema which represents the data structure you wish to capture.

See `Colander`_ for more information about schema definition.

::

  import colander
  
  class MyScheme(MappingSchema):
      name = SchemaNode(String(), validator = Length(min=4))
      email = SchemaNode(String(), validator = Email())
      password = SchemaNode(String(), validator = Length(min=5))
      
  myscheme = MyScheme()

Or, we can create new form with the bound schema using *bind_schema* decorator:

::

  import colander
  from smallform import bind_schema
  
  @bind_schema
  class MyForm(MappingSchema):
      name = SchemaNode(String(), validator = Length(min=4))
      email = SchemaNode(String(), validator = Email())
      password = SchemaNode(String(), validator = Length(min=5))

Create A From Object
--------------------
To create a form object, we do this:

::

  from smallform import Form
  
  myform = Form(myschema)

Or this, if we using bind_schema to create the form:

::

  myform = MyForm()

Additionly, we can set default form values:

::

  myform = MyForm(defaults=dict(name='default name'))

Validate A Form
---------------
Once we’ve created a Form object, we can validate it:

::

  values = myform.validate(request.POST)
  if not myform.errors:
      # processing values
      ...
  else:
      # processing errors

Furthermore, it’s possible to bind validated field values to an object instance, 
for example a SQLAlchemy model instance:

::

  obj = myform.bind(MyModel())

We can also use the parameters *include* and *exclude* to filter any unwanted data:

::
  
  obj = myform.bind(MyModel(), exclude=('password',))
  
  or
  
  obj = myform.bind(MyModel(), include=('name', 'email',))  


Using A Mako Template
---------------------
In your template:

::

  <form method="POST">
      <input name="name" type="text" value="${form.get('name')}" />
      % if form.has_errors('name'):
        <p>${form.get_first_error('name')}</p>
      % endif
      <input name="email" type="text" value="${form.get('email')}" />
      % if form.has_errors('email'):
        <p>${form.get_first_error('email')}</p>
      % endif
      <input name="password" type="password" value="" />
      % if form.has_errors('password'):
        <p>${form.get_first_error('password')}</p>
      % endif
  </form>
  
Feedback
--------
`Mail`_
