[soc2010/app-loading] merged trunkarchive/soc2010/app-loadingsoc2010/app-loading

git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2010/app-loading@13818 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 73 insertions, 14 deletions

diff --git a/docs/ref/contrib/flatpages.txt b/docs/ref/contrib/flatpages.txt
index 8c7f2781d0..ce6fdfcd1c 100644
--- a/docs/ref/contrib/flatpages.txt
+++ b/docs/ref/contrib/flatpages.txt
@@ -1,5 +1,3 @@
-.. _ref-contrib-flatpages:
-
 =================
 The flatpages app
 =================
@@ -21,7 +19,7 @@ template. It can be associated with one, or multiple, sites.
 
 .. versionadded:: 1.0
 
-The content field may optionally be left blank if you prefer to put your 
+The content field may optionally be left blank if you prefer to put your
 content in a custom template.
 
 Here are some examples of flatpages on Django-powered sites:
@@ -37,20 +35,20 @@ To install the flatpages app, follow these steps:
     1. Install the :mod:`sites framework <django.contrib.sites>` by adding
        ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` setting,
        if it's not already in there.
-       
+
        Also make sure you've correctly set :setting:`SITE_ID` to the ID of the
        site the settings file represents. This will usually be ``1`` (i.e.
        ``SITE_ID = 1``, but if you're using the sites framework to manage
        multiple sites, it could be the ID of a different site.
-       
+
     2. Add ``'django.contrib.flatpages'`` to your :setting:`INSTALLED_APPS`
        setting.
-       
+
     3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'``
        to your :setting:`MIDDLEWARE_CLASSES` setting.
-       
+
     4. Run the command :djadmin:`manage.py syncdb <syncdb>`.
- 
+
 How it works
 ============
 
@@ -69,7 +67,7 @@ If it finds a match, it follows this algorithm:
 
     * If the flatpage has a custom template, it loads that template. Otherwise,
       it loads the template :file:`flatpages/default.html`.
-    
+
     * It passes that template a single context variable, :data:`flatpage`, which
       is the flatpage object. It uses
       :class:`~django.template.context.RequestContext` in rendering the
@@ -92,11 +90,11 @@ Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you can
 put :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` at
 the end of the list, because it's a last resort.
 
-For more on middleware, read the :ref:`middleware docs
-<topics-http-middleware>`.
+For more on middleware, read the :doc:`middleware docs
+</topics/http/middleware>`.
 
 .. admonition:: Ensure that your 404 template works
-    
+
     Note that the
     :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`
     only steps in once another view has successfully produced a 404 response.
@@ -124,9 +122,9 @@ Via the Python API
 .. class:: models.FlatPage
 
     Flatpages are represented by a standard
-    :ref:`Django model <topics-db-models>`,
+    :doc:`Django model </topics/db/models>`,
     which lives in `django/contrib/flatpages/models.py`_. You can access
-    flatpage objects via the :ref:`Django database API <topics-db-queries>`.
+    flatpage objects via the :doc:`Django database API </topics/db/queries>`.
 
 .. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py
 
@@ -167,3 +165,64 @@ Since you're already entering raw HTML into the admin page for a flatpage,
 both ``flatpage.title`` and ``flatpage.content`` are marked as **not**
 requiring :ref:`automatic HTML escaping <automatic-html-escaping>` in the
 template.
+
+Getting a list of :class:`~django.contrib.flatpages.models.Flatpage` objects in your templates
+==============================================================================================
+
+.. versionadded:: 1.3
+
+The flatpages app provides a template tag that allows you to iterate
+over all of the available flatpages on the :ref:`current site
+<hooking-into-current-site-from-views>`.
+
+Like all custom template tags, you'll need to :ref:`load its custom
+tag library <loading-custom-template-libraries>` before you can use
+it. After loading the library, you can retrieve all current flatpages
+via the :ttag:`get_flatpages` tag:
+
+.. code-block:: html+django
+
+    {% load flatpages %}
+    {% get_flatpages as flatpages %}
+    <ul>
+        {% for page in flatpages %}
+            <li><a href="{{ page.url }}">{{ page.title }}</a></li>
+        {% endfor %}
+    </ul>
+
+.. templatetag:: get_flatpages
+
+Displaying ``registration_required`` flatpages
+----------------------------------------------
+
+By default, the :ttag:`get_flatpages` templatetag will only show
+flatpages that are marked :attr:`registration_required`\=False. If you
+want to display registration-protected flatpages, you need to specify
+an authenticated user using a``for`` clause.
+
+For example:
+
+.. code-block:: html+django
+
+    {% get_flatpages for someuser as about_pages %}
+
+If you provide an anonymous user, :ttag:`get_flatpages` will behave
+the same as if you hadn't provided a user -- i.e., it will only show you
+public flatpages.
+
+Limiting flatpages by base URL
+------------------------------
+
+An optional argument, ``starts_with``, can be applied to limit the
+returned pages to those beginning with a particular base URL. This
+argument may be passed as a string, or as a variable to be resolved
+from the context.
+
+For example:
+
+.. code-block:: html+django
+
+    {% get_flatpages '/about/' as about_pages %}
+    {% get_flatpages about_prefix as about_pages %}
+    {% get_flatpages '/about/' for someuser as about_pages %}
+