***CONFLICT*** percious and mcfletch edited docs/main/FormBasics.rst.…

… Both, please re-check this file, and coordinate with mpedersen.

--HG--
branch : 2.1

docs/gettingtoknow.rst

@@ -4,21 +4,18 @@
 Getting To Know TurboGears
 ==========================
 
-Read These Pages!
-=================
+This document describes the internal workings of TurboGears, how 
+the system is constructed, how the pieces fit together, and how 
+to navigate the source-code for the project.  Normally you will 
+want to read these pages in order to extend, debug, or change the 
+behaviour of TurboGears, or to start contributing to the project.
 
-These pages are the most useful pages for a new TurboGears developer
-to read after going through the tutorials. Reading the material
-here will help you understand much about the TurboGears architecture,
-and will make you a much more productive developer with TurboGears. We
-cannot stress this enough: Read These Pages!
+You will want to have read:
 
-.. toctree::
-   :maxdepth: 1
-
-   main/RequestFlow
-   main/master_html
-   main/Auth/index
+ * :ref:`Tutorials <tutorials>` which describes how to get started with TurboGears
+ * :ref:`recipes-and-faq` which describes how to accomplish particular tasks with TurboGears
+
+before diving into this material.
 
 What's New With The Latest Release
 ==================================
@@ -32,61 +29,25 @@ General Project Information
 ===========================
 
 .. toctree::
-   :maxdepth: 1
-
-   main/TG2Philosophy
-   main/RequestFlow
-   main/Contributing
-   main/bitbucket_tutorial
-   main/License
-   main/TGandPylons
-   building_docs
+    :maxdepth: 1
+
+    main/TG2Philosophy
+    main/RequestFlow
+    main/Contributing
+    main/bitbucket_tutorial
+    main/License
+    main/TGandPylons
+    building_docs
 
-Development Tools
-=================
-
-.. toctree::
-   :maxdepth: 1
-
-   main/CommandLine
-   main/Config
-   main/Session
-   main/Profile
-   main/Internationalization
-   main/ToolBox 
-
-Validation, Form handling and Widgets
-==========================================
-
-.. toctree::
-   :maxdepth: 1
-
-   main/FormBasics
-   main/Validation
-   main/ToscaWidgets/forms
-   main/ToscaWidgets/ToscaWidgets
-   main/GlobalJSLib
-
-General Reference for MVC Components
-====================================
-
-.. toctree::
-   :maxdepth: 1
-
-   main/Controllers
-   main/SQLAlchemy
-   main/DatabaseMigration
-
 Libraries and Modules Shipped With TurboGears
 =============================================
 
-   .. toctree::
-      :maxdepth: 2
-
-      modules/pylons/index
-      modules/tgdecorators
-      modules/tgflash
-      modules/thirdparty/formencode_api
-      modules/thirdparty/webhelpers_paginate
-      modules/thirdparty/index
-
+.. toctree::
+    :maxdepth: 2
+
+    modules/pylons/index
+    modules/tgdecorators
+    modules/tgflash
+    modules/thirdparty/formencode_api
+    modules/thirdparty/webhelpers_paginate
+    modules/thirdparty/index

docs/main/Deployment.rst

@@ -53,6 +53,7 @@ You may also want to package your app up as a redistributable egg, TG2
 sets up everything that you need to do this.
 
  :ref:`tgeggdeployment`
+
 
 Reference
 ---------
@@ -66,3 +67,5 @@ production.ini is slightly different.
 
 .. todo:: Difficulty: Medium. Document the recipes for deployment, updating the 1.0 docs
 
+
+.. todo:: Document usage of http://pypi.python.org/pypi/wsgisvc to deploy as a Win32 service 

docs/main/Validation.rst

@@ -200,14 +200,14 @@ just the thing for us -- Schema validators.
 If you want to do multiple-field validation, reuse validators or just
 clean up your code, validation ``Schema``s are the way to go. You
 create a validation schema by inheriting from
-``formencode.validators.Schema`` and pass the newly created ``Schema``
+``formencode.schema.Schema`` and pass the newly created ``Schema``
 as the ``validators`` argument instead of passing a dictionary.
 
 Create a schema:
 
 .. code-block:: python
 
-    class PwdSchema(validators.Schema):
+    class PwdSchema(schema.Schema):
         pwd1 = validators.String(not_empty=True)
         pwd2 = validators.String(not_empty=True)
         chained_validators = [validators.FieldsMatch('pwd1', 'pwd2')]
@@ -230,7 +230,17 @@ matching fields.
 Again, for information about ``Invalid`` exception objects, creating
 your own validators, schema and FormEncode in general, refer to the
 `FormEncode Validator`_ documentation and don't be afraid to check the
-``Formencode.validators`` source. It's often clearer than the docs.
+``Formencode.validators`` source. It's often clearer than the 
+documentation.
+
+Note that Schema validation is rigorous by default, in particular, you 
+must declare *every* field you are going to pass into your controller 
+or you will get validation errors.  To avoid this, add::
+
+    class MySchema( schema.Schema ):
+        allow_extra_fields=True
+
+to your schema declaration.
 
 .. _`FormEncode Validator`: http://formencode.org/docs/Validator.html
 
@@ -261,3 +271,4 @@ problem of propagating the errors back to your users. In the end, it's
 usually far simpler to use the validation framework.
 
 .. _FormEncode: http://formencode.org/
+

docs/main/movie_tutorial.rst

@@ -1,3 +1,5 @@
+.. _movie-tutorial:
+
 A Movie Database (Models, Views, Controllers)
 =============================================
 
@@ -193,6 +195,13 @@ transaction.commit is normally handled by middleware which commits
 if a method returns "normally" (including redirects) and rolls 
 back if the method raises an uncaught exception.
 
+Aside: If you are an old SQLAlchemy hand, you may be wondering what 
+"transaction.commit()" is, as in SQLAlchemy you would normally use 
+DBSession.commit() to commit your current transaction.  TurboGears 2.x
+uses a middleware component ``repoze.tm`` which allows for multi-database 
+commits.  A side-effect of this usage is that use of DBSession.commit() 
+is no longer possible.
+
 Browse/Edit with Admin GUI
 --------------------------
 
@@ -347,6 +356,7 @@ forms.  We'll use this capability, which is provided by the `Sprox`_ library
 to create a simple form our users can use to add new movies to our database::
 
     from sprox.formbase import AddRecordForm
+    from tg import tmpl_context
     class AddMovie(AddRecordForm):
         __model__ = Movie
     add_movie_form = AddMovie(DBSession)
@@ -358,18 +368,27 @@ our root controller::
     def index(self, **named):
         """Handle the front-page."""
         movies = DBSession.query( Movie ).order_by( Movie.title )
+        tmpl_context.add_movie_form = add_movie_form
         return dict(
             page='index',
             movies = movies,
-            add_movie_form = add_movie_form,
         )
 
-and call it within our ``index`` template:
+Why are we using ``tmpl_context``?  Why don't we just pass our 
+widget into the template as a parameter?  The reason is is that 
+TurboGears controllers often do double duty as both web-page 
+renderers and JSON handlers.  By putting "view-specific" code 
+into the tmpl_context and "model-data" into the result dictionary,
+we can more readily support the JSON queries.
+
+The tmpl_context
+
+Now we call our widget from within our ``index`` template:
 
 .. code-block:: html
 
     <h2>New Movie</h2>
-    ${add_movie_form( action='add_movie') }
+    ${tmpl_context.add_movie_form( action='add_movie') }
 
 we pass an ``action`` parameter to the form to tell it what controller method 
 (url) it should use to process the results of submitting the form.  We'll create 
@@ -470,7 +489,6 @@ References
 
  * The zope.sqlalchemy transaction module
 
-.. todo:: document the transaction module
 .. _`SQLAlchemy Documentation`: http://www.sqlalchemy.org/docs/05/
 .. _`Object Relational Mapper`: http://www.sqlalchemy.org/docs/05/ormtutorial.html
 .. _`SQLAlchemy Expressions`: http://www.sqlalchemy.org/docs/05/sqlexpression.html