pform 0.6.2
Form generation library for Pyramid framework
License: BSD

pform
=====

.. image :: https://travis-ci.org/fafhrd91/pform.png
  :target:  https://travis-ci.org/fafhrd91/pform


Simple form example
-------------------

Form contains three different subsystems, basic form attributes, fields and actions.

.. code-block:: python

    import pform
    from pyramid.httpexceptions import HTTPFound


    class EditForm(pform.Form):

         label = 'Edit form'

         fields = pform.Fieldset(
             pform.TextField(
                'name', title='Name')
         )

         @pform.button('Save')
         def safe_handler(self):
             data, errors = self.extract()

             if errors:
                 self.add_error_message(errors)

             self.context.name = data['name']

         @pform.button('Cancel')
         def cancel_handler(self):
             return HTTPFound(location='.')

This form renders one field `name` and two actions `safe` and `cancel` (submit buttons). Now we can render this form:

.. code-block:: python

    from pyramid.view import view_config

    @view_config(route_name='....', renderer='myview.jinja2')
    def my_view(request):
        form = EditForm(some_context, request)
        return form()

also it is possible to use form class as view:

.. code-block:: python

    @view_config(route_name='....')
    class EditForm(pform.Form):

        fields = ...


To do additional custom form initialization just override `update` method, also
if `update` method returns dictionary this values bypasses to form template:

.. code-block:: python

   class EditForm(pform.Form):

       def update(self):
           # custom form initialization
           return {some_data: some_value}


To get form values use `extract` method, this method return
`data` and `errors`. `data` is a form result, `errors` is a list of errors:

.. code-block:: python

   class EditForm(pform.Form):

       @pform.button('Save')
       def save_handler(self):
           data, errors = self.extract()

           if errors:
               self.add_error_message(errors)

           # save data
           ...


Customization
-------------

There are two ways for field and form customization:

1. Global customization 

  `pform` library uses `player`::https://github.com/fafhrd91/pform/tree/master/examples library for customization. `pform` libriary defines layer category `form` for all templates.


2. Field/form customization

  Also it is possible to customize widget of input template for each field. You can pass ``tmpl_widget`` argument to to field constructor for widget customization and ``tmpl_input`` argument for input generation. Both arguments should be valid pyramid renderer path.
  Form accepts three different templates, ``tmpl_view``, ``tmpl_actions`` and ``tmpl_widget``. ``tmpl_view`` is form renderer, ``tmpl_actions`` if form buttons renderer, ``tmpl_widget`` is custom field widget renderer. If field does not use custom ``tmpl_widget`` then form automatically sets ``tmpl_widget`` for each of this fields.


Examples
--------

There are several example.  You can find them in the `examples` directory at github.

https://github.com/fafhrd91/pform/tree/master/examples


Requirements
------------

- Python 2.6+ or Python 3.2+

- virtualenv



License
-------

pform is offered under the BSD license.

CHANGES
=======


0.6.2 (01-16-2013)
------------------

- Fixed composite and options templates for Chrome


0.6.1 (01-09-2012)
------------------

- Allow return additional data from action handler

- Pass different context to vocabulary factory 
  (depends on factory argument name: request, content, context)


0.6 (01-07-2013)
----------------

- Added `OptionsField`

- BaseMultiChoiceField.missing value is [] by default

- Copy field missing value during fieldset data extraction

- Fixed form csrf support

- Fixed 'checked' value for radio field

- Do not use missing value if value is not validation


0.5 (12-21-2012)
----------------

- Added `flat` attribute to field and fieldset, 
  with flat fieldset and composite field uses primary data 
  dictionary instead of sub dict


0.4.1 (12-20-2012)
------------------

- Fixed FileField validation


0.4 (12-12-2012)
----------------

- Added `Composite` field

- Render str in `form:error` message

- Removed `display` mode

- SimpleTerm and SimpleVocabulary renamed to Term and Vocabulary

- Removed `from_items` and `from_value` SimpleVocabulary methods, 
  use Vocabulary constructor instead

- Use `form` layer category for form and field templates

- Button class now inherits from InputField


0.3 (11-27-2012)
----------------

- Allow to add `str` as error in `Form.validate` method

- Better button handling

- Better tanslations for `Invalid` messages

- Changed arguments order for `Invalid` class contrustor 

- Added sub errors support to `Invalid` class

- Added `extract` parameter to `Button` class, if extract is set then action
  extract values from form, adds errors to message and pass data to handler

- Added `pform.button2` decorator, `extract` parameter is true

- Added `max_size` and `allowed_types` parameters to FileField

- Do not override widget's custom tmpl_widget


0.2 (11-13-2012)
----------------

- Fixed submit button template

- Allow to return http response from form update or action handler

- Added support for `player.layout()`


0.1 (11-07-2012)
----------------

- Initial release