QuickStart
==========

This will give you a quick idea of how Reform works. Let's jump into the code!

A login form
------------

Let's create a simple login form with a username and a password. First let's
import what we need::

    >>> from reform import Form, field

:class:`Form` is the class we will derive to create a new form. :mod:`field`
is a module containing the fields. Let's define our new form class::

    >>> class LoginForm(Form):
    ...     username = field.String(required=True)
    ...     password = field.String(required=True)

To validate data, we instanciate the new form, and call :meth:`Form.validate`
with a dictionnary. This dictionnary is what the user submitted::

    >>> form = LoginForm()
    >>> form.validate({'username': 'me', 'password': 'my password'})
    True

You can then access the values via the class' attribute::

    >>> form.username.value # Clean value
    'me'
    >>> form.username.data # Raw value
    'me'

If a field is invalid, you can access its errors via the class' attribute::

    >>> form.validate({'username': 'me', 'password': ''})
    False
    >>> form.password.errors
    [u'Required']

If a field is absent from the dictionnary, an empty string is used::

    >>> form.validate({'username': 'me'})
    False
    >>> form.password.data
    u''
    >>> form.password.errors
    [u'Required']

Something a bit more complex
----------------------------

Now let's create a registration form with more types like :class:`Integer` and
:class:`Boolean`::

    >>> class RegisterForm(Form):
    ...     email = field.Email(required=True)
    ...     age = field.Integer()
    ...     accept_terms_of_service = field.Boolean()

    >>> form = RegisterForm()
    >>> form.validate({'email': 'test@example.com', 'age': '24',
    ...                'accept_terms_of_service': 't'})
    True

Once validated, we can access the "clean" values via ``form.<field
name>.value``::

    >>> form.email.value
    'test@example.com'
    >>> form.age.value
    24
    >>> form.accept_terms_of_service.value
    True

The original data is accessible via ``form.<field name>.data``::

    >>> form.age.data
    '24'

Let's add more features to our form. We want to make sure that people who
signup are 18 or older, and that they accepted the terms of service. We can add
additionnal validators to our form::

    >>> class BetterRegisterForm(RegisterForm):
    ...     def validate_age(self, value):
    ...         if value < 18:
    ...             return u'You must be 18 or older'
    ...
    ...     def validate_accept_terms_of_service(self, value):
    ...         if not value:
    ...             return u'Read and accept the terms of service'

    >>> form = BetterRegisterForm()
    >>> form.validate({'email': 'test@example.com', 'age': '14',
    ...                'accept_terms_of_service': ''})
    False
    >>> form.age.errors
    [u'You must be 18 or older']
    >>> form.accept_terms_of_service.errors
    [u'Read and accept the terms of service']

No need to rewrite what's in ``RegisterForm``, we just derive it to add extra
validators. We can also add fields::

    >>> class NameRegisterForm(RegisterForm):
    ...     first_name = field.String()
    ...     last_name = field.String()

You can even add fields & validators to existing classes, but it's not recommended::

    >>> RegisterForm.first_name = field.String()