Commits

Anonymous committed dc17ec5

doc changes

  • Participants
  • Parent commits d8a2e40

Comments (0)

Files changed (5)

File docs/index.rst

 
 **PLEASE NOTE**
 
-**pyramid_simpleform** was originally designed to use with FormEncode. FormEncode usage is being deprecated in favour of Colander as of version _, as FormEncode itself is no longer actively maintained and Colander is used by other libraries in the Pyramid ecosystem, such as `Deform`_.
+**pyramid_simpleform** was originally designed to use with FormEncode. FormEncode usage is being deprecated in favour of Colander as of version **0.7**, as FormEncode itself is no longer actively maintained and Colander is used by other libraries in the Pyramid ecosystem, such as `Deform`_.
 
 It is therefore recommended if possible that you migrate existing FormEncode schemas over to Colander. 
 
 
 **pyramid_simpleform** doesn't require any special configuration using ZCML or otherwise. You just create FormEncode schemas or validators for your application as usual, and wrap them in a special **Form** class. The **Form** provides a number of helper methods to make form handling as painless, and still flexible, as possible.
 
-Here is a typical example::
+Here is a typical (truncated) example::
 
     import colander
 
         value = colander.SchemaNode(colander.Int())
 
     class MyModel(object):
+        """
+        Mock object. 
+        """
 
         pass
 
 The steps are:
 
 
-1. Create a **Form** instance with a Request and your schema and/or validators. You can optionally pass in default values or an object instance. 
+1. Create a **Form** instance with the Request and your schema. You can optionally pass in default values or an object instance. 
 
 2. Call **validate()**. This will check if the form should be validated (in most cases, if the request method is HTTP POST), and validates against the provided schema. It returns **True** if the form has been validated and there are no errors. Any errors get dumped into the **errors** property as a dict. 
 
 It is expected that you will want to subclass **FormRenderer**, for example you might wish to generate custom fields with JavaScript, HTML5 fields, and so on.
 
 
+Peppercorn
+----------
+
+**pyramid_simpleform** has optional support for the `Peppercorn`_ library, which is used for more advanced serialization/deserialization of web input. 
+
+The **FormRenderer** class supports the creation of the special `__start__` and `__end__` hidden tags required by Peppercorn::
+
+    renderer = FormRenderer(form)
+    renderer.start_hidden_tag('mapping', 'series')
+    >>> <<div style="display:none;">input type="hidden" name="__start__" value="series:mapping" /></div>
+
+    renderer.end_hidden_tag()
+    >>> <div style="display:none;"><input type="hidden" name="__end__" /></div>
+
+    renderer_end_hidden_tags(3)
+    >>> <div style="display:none;"><input type="hidden" name="__end__" /><input type="hidden" name="__end__" /><input type="hidden" name="__end__" /></div>
+
+Note that the hidden tags are automatically wrapped in hidden DIVs to preserve valid markup.
+
+The parameters are automatically passed through the Peppercorn ``parse`` function. 
+
+See the `Peppercorn`_ docs for more information.
+
+
 CSRF Validation
 ---------------
 
 
 However the **FormRenderer** class has a couple of helper methods for rendering the CSRF hidden input. **csrf()** just prints the input tag, while **csrf_token()** wraps the input in a hidden DIV to keep your markup valid.
 
-Remember to use the **allow_extra_fields** option with your schema to prevent validation errors caused by having the "_csrf" value (or other field values) in your form. A good tip is to create a base Schema class with **allow_extra_fields** and **filter_extra_fields** set to **True** and subclass this base Schema class with all your other schemas.
+
+Formencode
+----------
+
+**pyramid_simpleform** includes legacy support for `FormEncode`_ schemas and validators. This usage is deprecated and so will be eventually phased out, so it is recommended if possible to migrate existing FormEncode-based simpleform usage to Colander.
+
+You can access the old FormEncode Form class directly under the **pyramid_simpleform** package::
+
+    from pyramid_simpleform import Form
+
+Contrast this with the new, Colander-based class::
+
+    from pyramid_simpleform.form import Form
+
+The FormEncode-based Form works pretty much as the new Form, except that you pass in a FormEncode schema, or a dict of validators, rather than a Colander schema::
+
+    from formencode import Schema, validators
+    from pyramid_simpleform import Form
+
+    class MySchema(Schema):
+
+        allow_extra_fields = True
+        filter_extra_fields = True
+
+        name = validators.String(not_empty=True)
+
+    form = Form(request, MySchema)
+    if form.validate():
+        obj = form.bind(MyModel())
+        # ... process as usual
+
+It uses the same **FormRenderer** class::
+
+    renderer = FormRenderer(form)
+
+
+Note the use of the `allow_extra_fields` and `filter_extra_fields` attributes. These are recommended in order to remove unneeded fields (such as the CSRF) and also to prevent extra field values being passed through.
+
+State
+-----
+
+The FormEncode-based Form also includes support for handling state, including i18n.
+[TBD]
 
 API
 ---
 .. module:: pyramid_simpleform.form
 
 .. autoclass:: Form
+   :members:
 
 .. module:: pyramid_simpleform
 
 .. _WTForms: http://pypi.python.org/pypi/WTForms/
 .. _Flatland: http://pypi.python.org/pypi/flatland/
 .. _FormEncode: http://pypi.python.org/pypi/FormEncode/
-.. _Colander: http://pypi.python.org/pypi/FormEncode/
-.. _Deform: http://pypi.python.org/pypi/FormEncode/
+.. _Colander: http://pypi.python.org/pypi/Colander/
+.. _Peppercorn: http://pypi.python.org/pypi/Peppercorn/
+.. _Deform: http://pypi.python.org/pypi/Deform/
 .. _Pyramid: http://pypi.python.org/pypi/pyramid/
 .. _WebHelpers: http://pypi.python.org/pypi/WebHelpers/

File pyramid_simpleform/__init__.py

 
 class Form(object):
 
+    """
+    Legacy class for validating FormEncode schemas and validators.
 
-    """
+    :deprecated: 0.7
+
     `request` : Pyramid request instance
 
     `schema`  : FormEncode Schema class or instance

File pyramid_simpleform/form.py

         valid.
         
         This will check if the form should be validated (i.e. the
-        request method matches) and the schema/validators validate.
+        request method matches) and the schema validates.
 
         Validation will only be run once; subsequent calls to 
         validate() will have no effect, i.e. will just return
         the original result.
 
-        The errors and data values will be updated accordingly.
+        The `errors` and `data` dicts will be updated accordingly.
 
         `force_validate`  : will run validation regardless of request method.
 

File pyramid_simpleform/renderers.py

         """
         Renders peppercorn __start__ hidden tags with given values.
 
-        For example:
+        For example::
 
-        renderer.start_hidden_tag('mapping', 'series')
-        >>> <input type="hidden" name="__start__" value="series:mapping" />
+            renderer.start_hidden_tag('mapping', 'series')
+            >>> <input type="hidden" name="__start__" value="series:mapping" />
 
         :versionadded: 0.7
         """
         """
         Renders peppercorn __end__ hidden tag
 
-        For example:
+        For example::
 
-        renderer.end_hidden_tag()
-        >>> <input type="hidden" name="__end__" />
+            renderer.end_hidden_tag()
+            >>> <input type="hidden" name="__end__" />
 
         :versionadded: 0.7
         """

File pyramid_simpleform/tests.py

  
 class TestFormencodeForm(unittest.TestCase):
     
-
     def test_is_error(self):
         from pyramid_simpleform import Form