Merging Seth Davis' work

--HG--
branch : 2.1

docs/main/Auth/index.rst

@@ -18,12 +18,13 @@ Overview
 to be, which is normally done using credentials (e.g., when you need to access
 your email, you provide the email address and your password, or if you want
 to check your bank account, you'll probably have to provide you Id number and
-your card's ping). In other words, finding `who` you are.
+your card's PIN). In other words, finding `who` you are.
 
 ``Authorization``, on the other hand, is the act of granting access to given
-resources depending on who would use them. For example, allowing registered
-members to leave comments on a blog, or allowing your friends to see your
-pictures while others cannot. In other words, finding `what` you may do.
+resources depending on whether you have permission to use them. For example, 
+allowing registered members to leave comments on a blog, or allowing your 
+friends to see your pictures while others cannot. 
+In other words, finding `what` you may do.
 
 TurboGears 2 applications may take advantage of a robust, extendable, pluggable
 and easy-to-use system for authentication and authorization suitable for nearly
@@ -113,3 +114,7 @@ want to customize some things, you may want to read the following pages:
     Authorization
     Customization
 
+
+.. todo::  Fix up navigation in this section.   
+   I (laurin) wish I knew how to do it - perhaps someone else?.   
+   Next for "Authentication/who" is NOT "Authorization/what" - seems pyAMF snuck in there...

docs/main/BasicMoves.rst

@@ -28,7 +28,7 @@ obligatory "Hello World" text.   In doing so, we'll introduce you to the
 V and C of MVC, the view and controller.
 
 
-Hello World using template
+Hello World Using Template
 --------------------------
 
 In this first approach, we'll use the existing template that was provided
@@ -54,7 +54,7 @@ You can now point your browser at http://localhost:8080 to see the change. You
 should see "Hello, world!" text in h1 size.
 
 
-Hello World using static file
+Hello World Using Static File
 --------------------------------
 
 Open a new file, edit the content as a simple html file:
@@ -72,7 +72,7 @@ and save it to helloworld/public/hello.html.
 Browse http://localhost:8080/hello.html and see the page.
 
 
-Hello World using controller
+Hello World Using Controller
 -------------------------------
 
 The controller defines how the server responds to user actions.   In the case
@@ -111,7 +111,7 @@ Edit helloworld/controllers/root.py:
 Browse http://localhost:8080/hello to see the change.
 
 
-Hello World combining template with controller
+Hello World Combining Template With Controller
 -----------------------------------------------
 
 So far, we've been returning plain text for every incoming request.  
@@ -221,7 +221,7 @@ since it is now based on the Pylons_ framework.   You can read more about the
 `interactive debugger here
 <http://pylonsbook.com/en/1.0/tracking-down-problems-and-handling-errors.html>`_.
 
-Hello World using flash
+Hello World Using Flash
 --------------------------------
 
 Here we are going to use a builtin function that TurboGears supplies 

docs/main/DownloadInstall.rst

@@ -1,4 +1,6 @@
-How to install TurboGears 2
+.. _downloadinstall:
+
+How To Install TurboGears 2
 ===========================
 
 This document provides several methods of installing TurboGears; the method you choose will depend on your level of experience and platform.

docs/main/Pagination/index.rst

@@ -0,0 +1,204 @@
+Pagination quickstart for TurboGears2
+=====================================
+
+:Status: Work in progress
+
+Prequisites
+-----------
+
+We start where the MovieDemo left off. See the `ToscaSample`_ 
+tutorial or download the zipped ToscaWidgetsFormsExample_.
+
+.. _ToscaWidgetsFormsExample: ../../_static/ToscaWidgetsFormsExample.zip
+.. _ToscaSample: http://www.turbogears.org/2.0/docs/main/ToscaWidgets/forms.html
+
+Populating the database
+^^^^^^^^^^^^^^^^^^^^^^^
+
+To have some sample data to work with, let's populate the database with some
+movies. Add these lines to ``websetup.py`` (above transaction.commit())::
+
+	    movieDatas = [["Into the Wild", 2007],
+	                  ["The Big Lebowsky", 1998],
+	                  ["Pulp Fiction", 1994],
+	                  ["Dead Man", 1995],
+	                  ["Night on Earth", 1991],
+	                  ["Genova", 2008],
+	                  ["Snatch", 2000]]
+	    
+	    movies = []
+	    for data in movieDatas:
+	        movie = Movie()
+	        movie.title = data[0]
+	        movie.year = data[1]
+	        model.DBSession.add(movie)
+  
+
+After you set up your app and restart the server you should now have seven 
+movies listed.
+
+.. code-block:: bash
+
+	paster setup-app development.ini
+	paster serve --reload development.ini
+	 
+    
+
+Basic pagination
+----------------
+
+With a model and some data set up, add ``webhelpers.paginate`` to your controller, and 
+create an instance of ``paginate.Page`` that you pass to the template.  
+
+Import paginate in your ``controllers/root.py`` and modify the ``list()`` 
+method to look like this::
+
+	    from webhelpers import paginate
+		
+	    @expose("toscasample.templates.movie_list")
+	    def list(self, page=1):
+	        """List and paginate all movies in the database"""
+	        movies = DBSession.query(Movie)
+	        currentPage = paginate.Page(movies, page, items_per_page=5)
+	        return dict(movies=currentPage.items, page='ToscaSample Movie list', currentPage=currentPage)
+
+This creates and passes a ``paginate.Page`` object to our template, so we can use it there to access a ``pager()``.
+
+The subset of items that should be displayed for the current page we 
+get from ``currentPage.items`` and display them in the template like we normally would.
+
+
+Now the pagination can be displayed in the template like this:
+
+.. highlight:: html+genshi
+
+Template code in ``templates/movie_list.html``::
+
+	<p class="pagelist">${currentPage.pager()}</p>
+	
+.. highlight:: python
+
+
+
+Now we add some padding to the pagelist and make it centered. 
+
+Create a file pagination.css in your public/css/ directory with 
+the following contents and include it in style.css:
+
+.. highlight:: css
+
+CSS in ``public/css/style.css``::
+
+	@import url("pagination.css"); 
+
+CSS in ``public/css/pagination.css``::
+
+	.pagelist strong {
+		padding: 5px;
+	}
+	
+	p.pagelist {
+		text-align: center;
+	}
+	
+Your movie listing should now look something like this:
+
+.. image:: tg2pagination_fig1.png		
+
+
+
+Advanced pagination
+-------------------
+
+More formatting
+^^^^^^^^^^^^^^^
+
+Demonstrating some more formating arguments::
+
+	${currentPage.pager(format='~3~', page_param='page', show_if_single_page=True)}
+
+	
+See http://www.pylonshq.com/docs/en/0.9.7/thirdparty/webhelpers/paginate/ for more details.
+
+
+
+
+Adding previous and next links
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Let's add previous and next links:
+
+.. highlight:: html+genshi
+
+Modify the pagelist in ``templates/movie_list.html`` to look like this::
+
+	<p class="pagelist">
+		<a class="prevPage" href="/books?page=${currentPage.previous_page}">&lt;&lt;&lt;</a>
+		${currentPage.pager(format='~3~', page_param='page', show_if_single_page=True)}
+		<a class="nextPage" href="/books?page=${currentPage.next_page}">&gt;&gt;&gt;</a>
+	</p>
+	
+Functional, but not very pretty:
+
+.. image:: tg2pagination_fig2.png		
+
+
+
+Adding some arrow images
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Let's add some images:
+
+ .. image:: icons/arrow-left.png
+   :height: 32
+
+ .. image:: icons/arrow-right.png
+   :height: 32
+
+
+.. note ::
+
+	These images are public domain - feel free to use them any way you like. 
+	Different sizes and the source \*.psd are included in the project file.)
+
+
+.. highlight:: html+genshi
+
+Change the pagelist code in ``templates/movie_list.html``::
+
+	<p class="pagelist">
+		<a class="prevPage" href="/books?page=${currentPage.previous_page}">&nbsp;</a>
+		${currentPage.pager(format='~3~', page_param='page', show_if_single_page=True)}
+		<a class="nextPage" href="/books?page=${currentPage.next_page}">&nbsp;</a>
+	</p>
+	
+.. highlight:: css
+
+Add this to the CSS in ``public/css/pagination.css``::
+
+	a.prevPage {
+		background: url("/images/icons/png/32x32/arrow-left.png") no-repeat;
+		padding-left: 18px;
+		padding-right: 18px;
+		padding-top: 12px;
+		padding-bottom: 15px;
+		text-decoration: none;
+		}
+	
+	.nextPage {
+		background: url("/images/icons/png/32x32/arrow-right.png") no-repeat;
+		padding-left: 18px;
+		padding-right: 18px;
+		padding-top: 12px;
+		padding-bottom: 15px;
+		text-decoration: none;
+		}		
+
+And this is what the end result looks like:
+
+.. image:: tg2pagination_fig3.png		
+
+An :download:`Example Project <ToscaWidgetsFormsPaginated.zip>` has been attached so that you can try this easily. 
+
+
+.. todo:: Review this file for todo items.

docs/main/Wiki20/wiki20.rst

@@ -40,8 +40,7 @@ To go through this tutorial, you'll need:
     comes with Python 2.5 pre-installed; for 10.4 and
     before, follow *Macintosh* in the above link.
 
-#.  `TurboGears 2.0
-    <DownloadInstall>`_ or higher.
+#.  :ref:`downloadinstall`
 
 #.  docutils_ 0.4 or later,
     which is used for the wiki's formatting. ``docutils`` is not a required
@@ -477,6 +476,17 @@ This is a basic XHTML page with three substitutions:
 
 When you refresh the output web page you should see "initial data" displayed on the page.
 
+.. note:: py.replace_ replaces entire tag (including start and end tags) with
+   the value of the variable provided.  
+
+   .. _py.replace: http://genshi.edgewall.org/wiki/Documentation/xml-templates.html#id8
+
+.. admonition:: For the curious...
+
+   Do you wonder what those html comments like ##{PageContent} are?  
+   They do not matter for this tutorial and are only to help the documentation 
+   (you're soaking in it!) isolate certain lines of code to display, like above.
+
 .. _editing_pages:
 
 Editing pages

docs/misc.rst

@@ -46,3 +46,6 @@ Misc To Do Items From The Docs
 .. todo:: document override_template for doing dynamic templates in a controller method
 
 .. todo:: port http://docs.turbogears.org/1.0/FileUploadTutorial to TG2
+
+.. todo:: make sure to explain how to use "paster --daemon"
+

docs/recipesandfaq.rst

@@ -7,7 +7,7 @@ Recipes and FAQ
 .. toctree::
    :maxdepth: 2
 
-   main/Auth/Authentication
+   main/Auth/index
    main/TGandPyAMF
    main/TGandFirePython
    main/RoutesIntegration

docs/tutorials.rst

@@ -13,6 +13,7 @@ Tutorials
    main/movie_tutorial.rst
    main/SimpleWidgetForm
    main/ToscaWidgets/forms
+   main/Pagination/index
    main/AuthorizeTutorial
    main/Auth/index
    main/bitbucket_tutorial