Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Removing some old and now invalid parts of the documentation and add …
…ToscaWidgets2 documentation
  • Loading branch information
amol- committed Mar 25, 2012
1 parent 400ff58 commit 4f34076
Show file tree
Hide file tree
Showing 10 changed files with 185 additions and 86 deletions.
7 changes: 3 additions & 4 deletions docs/gettingtoknow.rst
@@ -1,8 +1,8 @@
.. _getting-to-know:

===================
The Gears in Detail
===================
=============================
About the TurboGears Project
=============================

This document describes the internal workings of TurboGears, how
the system is constructed, how the pieces fit together, and how
Expand Down Expand Up @@ -36,7 +36,6 @@ General Project Information
main/Contributing
main/bitbucket_tutorial
main/License
main/TGandPylons
building_docs
main/testing_core

Expand Down
4 changes: 2 additions & 2 deletions docs/index.rst
Expand Up @@ -16,9 +16,9 @@ The TurboGears documentation
============================

+----------------------------------------------+-------------------------------------------------+------------------------------------------------------------+-------------------------------------------------+----------------------------------------------+
| .. container:: part-tutorials | .. container:: part-gears | .. container:: part-extending | .. container:: part-recipes | .. container:: part-reference |
| .. container:: part-tutorials | .. container:: part-recipes | .. container:: part-extending | .. container:: part-gears | .. container:: part-reference |
| | | | | |
| :ref:`Get Started <tutorials>` | :ref:`The Gears in Detail <getting-to-know>` | :ref:`Extensions and Tools <extensions-and-tools>` | :ref:`Tips and Recipes <recipes-and-faq>` | :ref:`Index and API Reference <genindex>` |
| :ref:`Get Started <tutorials>` | :ref:`Recipes and Tips <recipes-and-faq>` | :ref:`Extensions and Tools <extensions-and-tools>` | :ref:`About TurboGears <getting-to-know>` | :ref:`Index and API Reference <genindex>` |
+----------------------------------------------+-------------------------------------------------+------------------------------------------------------------+-------------------------------------------------+----------------------------------------------+

The TurboGears Web Framework
Expand Down
4 changes: 2 additions & 2 deletions docs/main/FormBasics.rst
@@ -1,7 +1,7 @@
.. _form-basics:

TurboGears Form Handling Overview
=================================
TurboGears Autogenerated Forms Overview
=========================================

This is a succinct explanation on how to use sprox's form rendering
capabilities within TurboGears2. We will assume the reader is somewhat
Expand Down
30 changes: 0 additions & 30 deletions docs/main/StaticFile.rst

This file was deleted.

34 changes: 0 additions & 34 deletions docs/main/TGandPylons.rst

This file was deleted.

10 changes: 0 additions & 10 deletions docs/main/Templates/ChameleonGenshi.rst

This file was deleted.

1 change: 0 additions & 1 deletion docs/main/Templates/index.rst
Expand Up @@ -17,7 +17,6 @@ We currently support the following template engines out of the box.
Genshi
Mako
Jinja
ChameleonGenshi

All you need to do to use any one of these template engines is to add it to the list of renderers to prepare in app_cfg.py::

Expand Down
177 changes: 177 additions & 0 deletions docs/main/TwForms.rst
@@ -0,0 +1,177 @@
.. _tw2forms:

=================================
Creating and Validating Forms
=================================

TurboGears relies on ToscaWidgets for Forms building and validations.
Since version 2.2 TurboGears uses ToscaWidgets2, this is an introduction
on using ToscaWidgets2 for building and validating forms, a more complete
documentation is available on the
`ToscaWidgets2 Documentation <http://tw2core.readthedocs.org/en/latest/index.html#>`_ itself.

Displaying Forms
======================

To create a form you will have to declare it specifying:

* the form action (where to submit the form data)
* the form layout (how the form will be displayed)
* the form fields

The *action* can be specified as an attribute of the form itself, while the *layout*
must be a class named **child** which has to inherit from ``tw2.forms.BaseLayout``.
Any of ``tw2.forms.TableLayout`` or ``tw2.forms.ListLayout`` will usually do, but you
can easily write your own custom layouts. The form *fields* can then be specified
inside the **child** class.

.. code-block:: python
import tw2.core as twc
import tw2.forms as twf
class MovieForm(twf.Form):
class child(twf.TableLayout):
title = twf.TextField()
director = twf.TextField(value='Default Director')
genres = twf.CheckBoxList(options=['Action', 'Comedy', 'Romance', 'Sci-fi'])
action = '/save_movie'
To display the form we can return it from the controller where it must be rendered:

.. code-block:: python
@expose('tw2test.templates.index')
def index(self, *args, **kw):
return dict(page='index', form=MovieForm)
and *display* it inside the template itself.
Any field of the form can be filled using the *value* argument passed to the
display function. The values provided inside this argument will override the
field default ones.

.. code-block:: html+genshi

<div id="getting_started">
${form.display(value=dict(title='default title'))}
</div>

When submitting the form the **save_movie** controller declared in the *action*
attribute of the form will receive the submitted values as any other provided
GET or POST parameter.

.. code-block:: python
@expose()
def save_movie(self, **kw):
return str(kw)
Validating Fields
=====================

ToscaWidgets2 is able to use any `FormEncode` validator for validation of
both fields and forms. More validators are also provided inside the
``tw2.core.validators`` module.

To start using validation we have to declare the validator for each form field.
For example to block submission of our previous form when no title or director
is provided we can use the ``tw2.core.Required`` validator:

.. code-block:: python
class MovieForm(twf.Form):
class child(twf.TableLayout):
title = twf.TextField(validator=twc.Required)
director = twf.TextField(value="Default Director", validator=twc.Required)
genres = twf.CheckBoxList(options=['Action', 'Comedy', 'Romance', 'Sci-fi'])
action = '/save_movie'
Now the forms knows how to validate the title and director fields,
but those are not validated in any way.
To enable validation in TurboGears we must use the **tg.validate** decorator
and place it at our form action:

.. code-block:: python
@expose()
@validate(MovieForm, error_handler=index)
def save_movie(self, *args, **kw):
return str(kw)
Now every submission to */save_movie* url will be validated against
the *MovieForm* and if it doesn't pass validation will be redirected
to the *index* method where the form will display an error for each field
not passing validation.

More about TurboGears support for validation is available inside the
:ref:`validation` page.

Validating Compound Fields
============================

Suppose that you are afraid that people might enter a wrong director name
for your movies. The most simple solution would be to require them to
enter the name two times to be sure that it is actually the correct one.

How can we enforce people to enter two times the same name inside our form?
Apart from fields, ToscaWidgets permits to set validators to forms.
Those can be used to validate form fields together instead of one by one.
To check that our two directors equals we will use the
``formencode.validators.FieldsMatch`` validator:

.. code-block:: python
import tw2.core as twc
import tw2.forms as twf
from formencode.validators import FieldsMatch
class MovieForm(twf.Form):
class child(twf.TableLayout):
title = twf.TextField(validator=twc.Required)
director = twf.TextField(value="Default Director", validator=twc.Required)
director_verify = twf.TextField()
genres = twf.CheckBoxList(options=['Action', 'Comedy', 'Romance', 'Sci-fi'])
action = '/save_movie'
validator = FieldsMatch('director', 'director_verify')
Nothing else of our code needs to be changed, our */save_movie* controller
already has validation for the *MovieForm* and when the form is submitted
after checking that there is a title and director will also check that
both *director* and *director_verify* fields equals.

Automatic Form Generation
===========================

TurboGears provides support for forms autogeneration from models using ``Sprox``.

Those features are documented inside the :ref:`form-basics` page.

Back to ToscaWidgets1
======================

Some projects may still want to rely on ToscaWidgets1 due to legacy code or
due to external packages which are not available on ToscaWidgets2.

If you want to switch back your entire project to ToscaWidgets1, just remove the:

.. code-block:: python
base_config.prefer_toscawidgets2 = True
from your `config/app_cfg.py`.

If you want to use both ToscaWidgets2 and ToscaWidgets1 remove the *prefer_toscawidgets2* line
and replace it with:

.. code-block:: python
base_config.use_toscawidgets = True
base_config.use_toscawidgets2 = True
Please keep in mind that recent versions of `sprox`, `tgext.crud` and `tgext.admin`
all rely on ToscaWidgets2 if it is available inside your virtualenv so remember to have
ToscaWidgets2 enabled inside your project or remove it from your virtual environment
if you want to use those modules.
3 changes: 0 additions & 3 deletions docs/recipesandfaq.rst
Expand Up @@ -27,7 +27,6 @@ We cannot stress this enough: Read These Pages!
main/Templates/Genshi
main/Config
main/LogSetup
main/StaticFile
main/Internationalization

.. todo:: link repoze.who, repoze.what, and the other key middleware
Expand Down Expand Up @@ -114,7 +113,6 @@ Note: most new users do not need to choose an alternate templating language.
main/Templates/Genshi
main/master_html
main/Templates/index
main/Templates/ChameleonGenshi
main/Templates/Mako
main/Templates/Jinja

Expand All @@ -132,7 +130,6 @@ Mochikit package which was the default in TurboGears 1.x.
:maxdepth: 1

main/GlobalJSLib
main/StaticFile

.. todo:: JQuery, Dojo, EXT usage doc-links
.. todo:: Link documentation for doing JSON RPC/Ajax here
Expand Down
1 change: 1 addition & 0 deletions docs/tutorials.rst
Expand Up @@ -19,6 +19,7 @@ to get start with your first real web application.
main/QuickStart
main/BasicMoves
TurboGears Book: 20 Minutes Wiki Tutorial <http://www.turbogears.org/book/part1/wiki20.html>
main/TwForms

==================
Advanced Tutorials
Expand Down

0 comments on commit 4f34076

Please sign in to comment.