Skip to content
Browse files

Removing some old and now invalid parts of the documentation and add …

…ToscaWidgets2 documentation
  • Loading branch information...
1 parent 400ff58 commit 4f34076be22f31d6dbc4bfa31a94757724da44ce @amol- amol- committed Mar 25, 2012
View
7 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
@@ -36,7 +36,6 @@ General Project Information
main/Contributing
main/bitbucket_tutorial
main/License
- main/TGandPylons
building_docs
main/testing_core
View
4 docs/index.rst
@@ -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
View
4 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
View
30 docs/main/StaticFile.rst
@@ -1,30 +0,0 @@
-
-Serving Static Files (Css, Javascript, Images, etc.)
-====================================================
-
-
-Place any static files in the 'public' folder. Files there will be
-served up just as they would in a "normal" web server. You might want
-to consider putting all static files in a static directory, so that
-you can use apache/nginx to serve up these static files for you when
-you go into production, or later when your traffic requires it.
-
-
-Getting Rid Of The Static File Middleware
------------------------------------------
-
-If your app is running in production, and Apache or another web server
-is handling this static content, edit config/middleware.py and
-remove::
-
- javascripts_app = StaticJavascripts()
- static_app = StaticURLParser(config['pylons.paths']['static_files'])
- app = Cascade([static_app, javascripts_app, app])
-
-Reference
----------
-
-Upload File
-
- * http://wiki.pylonshq.com/display/pylonscookbook/Hacking+Pylons+for+handling+large+file+upload
- * http://kelpi.com/script/06fff7
View
34 docs/main/TGandPylons.rst
@@ -1,34 +0,0 @@
-TurboGears And Pylons Working Together
-======================================
-
-TurboGears 2 will be what TG has been designed to be from the
-beginning: a stack of best of breed Python components. We'll make
-sure these components are wired together to provide a web experience
-that gets you started quickly, and provides a robust web development
-environment. TurboGears 2 will also be as API compatible with
-TurboGears 1 as is reasonable. We do want to make a few API changes,
-and clean things up a bit as we go. But it should be very easy to port
-applications from TurboGears 1 to TurboGears 2.
-
-The question has been asked, what does TurboGears 2 do to benefit
-Pylons development? The simple answer is that TurboGears 2 provides
-Pylons with a set of standard components, a new controller publishing
-API that is easier to get started with than Routes, a bunch of
-additional rapid web development tools, and perhaps most importantly a
-lot more developer attention.
-
-By working together on core components, we'll be able to move forward
-more quickly, and put even more effort into creating a robust, stable
-core.
-
-Pylons provides a robust WSGI stack, and a clean way to re-implement
-the TurboGears API in relatively little code. And since Pylons has a
-goal of being a framework that maximizes developer choices, people
-have been pushing Ben and the rest of the Pylons developers to make a
-well documented set of defaults, and to make the framework a bit
-easier for new developers to learn.
-
-In the new TurboGears+Pylons working together world, we're both able
-to focus on the things that have made our individual frameworks
-successful in the past, and share development effort on lots and lots
-of things.
View
10 docs/main/Templates/ChameleonGenshi.rst
@@ -1,10 +0,0 @@
-Why Chameleon Genshi?
-=====================
-
-Due to it's C backend chamelion is faster than genshi and still contains the (x)html validation properties.
-
-Using chameleon.genshi in tg2
-------------------------------
-
-.. todo:: Difficulty: Medium. Document how to install and use chameleon.genshi in tg2.1
-
View
1 docs/main/Templates/index.rst
@@ -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::
View
177 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.
View
3 docs/recipesandfaq.rst
@@ -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
@@ -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
@@ -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
View
1 docs/tutorials.rst
@@ -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

0 comments on commit 4f34076

Please sign in to comment.
Something went wrong with that request. Please try again.