Document layouts

docs/source/forms.rst

@@ -14,9 +14,9 @@ Form
 
 A form is usually created by declaring a subclass
 of a :class:`tw2.forms.Form`. Within the
-form a ``child`` attribute that is a subclass
-of :class:`tw2.forms.Layout` can be used to specify
-how the fields of the form should be arranged and then
+form a ``child`` attribute that specifies the :ref:`formlayout`
+(how the fields shoulb be arranged graphically)
+through a subclass of :class:`tw2.forms.Layout` and then
 within ``child`` all the fields of the form can be declared:
 
 .. code-block:: python
@@ -29,7 +29,7 @@ within ``child`` all the fields of the form can be declared:
         class child(twf.TableLayout):
             title = twf.TextField()
             director = twf.TextField(value='Default Director')
-            genres = twf.CheckBoxList(options=['Action', 'Comedy', 'Romance', 'Sci-fi'])
+            genres = twf.SingleSelectField(options=['Action', 'Comedy', 'Romance', 'Sci-fi'])
 
         action = '/save_movie'
 
@@ -42,11 +42,108 @@ to specify where the form should be submitted.
     you probably want the action to be a ``tg.lurl`` to
     ensure that prefix of your application is retained.
 
+Form Buttons
+~~~~~~~~~~~~~~~
+
+By default, each form comes with a **submit** button.
+
+The submit button can be replaced by setting the
+form ``submit`` attribute::
+
+    class NameForm(twf.Form):
+        class child(twf.TableLayout):
+            name = twf.TextField()
+
+        action = '/save_name'
+        submit = twf.SubmitButton(value="Save Name")
+
+Multiple buttons can also be provided for the form
+by setting the ``buttons`` attribute::
+
+    class NameForm(twf.Form):
+        class child(twf.TableLayout):
+            name = twf.TextField()
+
+        action = '/save_name'
+        buttons = [
+            twf.SubmitButton(value="Save Name"),
+            twf.ResetButton(),
+            twf.Button(value="Say Hi", attrs=dict(onclick="alert('hi')"))
+        ]
+
+
 .. autoclass:: tw2.forms.widgets.Form
     :members:
 
-Builtin Layouts
----------------------------
+.. _formlayout:
+
+Form Layout
+---------------------
+
+A layout specifies how the fields of the form
+should be arranged.
+
+This can be specified by having ``Form.child``
+inherit from a specific layout class::
+
+    class NameForm(twf.Form):
+        class child(twf.TableLayout):
+            name = twf.TextField()
+
+or::
+
+    class NameForm(twf.Form):
+        class child(twf.ListLayout):
+            name = twf.TextField()
+
+A custom layout class can also be made to
+show the children however you want::
+
+    class Bootstrap3Layout(twf.BaseLayout):
+        inline_engine_name = "kajiki"
+        template = """
+<div py:attrs="w.attrs">
+<div class="form-group" py:for="c in w.children_non_hidden" title="${w.hover_help and c.help_text or None}" py:attrs="c.container_attrs" id="${c.compound_id}:container">
+    <label for="${c.id}" py:if="c.label">$c.label</label>
+    ${c.display(attrs={"class": "form-control"})}
+    <span id="${c.compound_id}:error" class="error help-block" py:content="c.error_msg"/>
+</div>
+<py:for each="c in w.children_hidden">${c.display()}</py:for>
+<div id="${w.compound_id}:error" py:content="w.error_msg"></div>
+</div>"""
+
+    class BootstrapNameForm(twf.Form):
+        class child(Bootstrap3Layout):
+            name = twf.TextField()
+
+        submit = twf.SubmitButton(css_class="btn btn-default")
+
+In case of complex custom layouts, you can even
+specify the layout case by case in the form itself
+with each children in a specific position accessing
+the children using ``w.children.child_name``::
+
+    class OddNameForm(twf.Form):
+        class child(twf.BaseLayout):
+            inline_engine_name = "kajiki"
+            template = """
+            <div py:attrs="w.attrs">
+                <div py:with="c=w.children.name">
+                    ${c.display()}
+                    <span id="${c.compound_id}:error" py:content="c.error_msg"/>
+                </div>
+                <div py:with="c=w.children.surname">
+                    ${c.display()}
+                    <span id="${c.compound_id}:error" py:content="c.error_msg"/>
+                </div>
+
+                <py:for each="ch in w.children_hidden">${ch.display()}</py:for>
+                <div id="${w.compound_id}:error" py:content="w.error_msg"></div>
+            </div>
+            """
+
+            name = twf.TextField()
+            surname = twf.TextField()
 
 .. autoclass:: tw2.forms.widgets.BaseLayout
     :members: