Francesco Banconi avatar Francesco Banconi committed d308aa6

Improve documentation cross references.

Comments (0)

Files changed (11)

doc/changelog.rst

 
 For backward compatibility, the application still includes the two JavaScript
 ``endless.js`` and ``endless_on_scroll.js`` files. However, please consider
-migrating as soon as possible: the old JavaScript files are deprecated, are
-no longer maintained, and don't provide the new JavaScript features. Also note
-that the old Javascript files will not work if jQuery >= 1.9 is used.
+:ref:`migrating<javascript-migrate>` as soon as possible: the old JavaScript
+files are deprecated, are no longer maintained, and don't provide the new
+JavaScript features. Also note that the old Javascript files will not work if
+jQuery >= 1.9 is used.
 
 New features include ability to **paginate different objects with different
 options**, precisely **selecting what to bind**, ability to **register
 callbacks**, support for **pagination in chunks** and much more.
 
 Please refer to the :doc:`javascript` for a detailed overview of the new
-features and for instructions on **how to migrate** from the old JavaScript
-files to the new one.
+features and for instructions on :ref:`how to migrate<javascript-migrate>` from
+the old JavaScript files to the new one.
 
 ----
 
-**New feature**: the ``page_templates`` decorator also accepts a sequence
-of ``(template, key)`` pairs, functioning as a dict mapping templates and
-keys (still present), e.g.::
+**New feature**: the :ref:`page_templates<multiple-page-templates>` decorator
+also accepts a sequence of ``(template, key)`` pairs, functioning as a dict
+mapping templates and keys (still present), e.g.::
 
     from endless_pagination.decorators import page_templates
 
 ----
 
 **New feature**: ability to provide nested context variables in the
-*paginate* and *lazy_paginate* template tags, e.g.:
+:ref:`templatetags-paginate` and :ref:`templatetags-lazy-paginate` template
+tags, e.g.:
 
 .. code-block:: html+django
 
 
 ----
 
-**New feature**: the page list object returned by the ``{% get_pages %}``
-template tag has been improved adding the following new methods:
+**New feature**: the page list object returned by the
+:ref:`templatetags-get-pages` template tag has been improved adding the
+following new methods:
 
 .. code-block:: html+django
 
 - *'first'*: will display the first page as an arrow;
 - *'last'*: will display the last page as an arrow.
 
-The *show_pages* documentation in :doc:`templatetags_reference` describes how
-to customize Digg-style pagination defining your own page list callable.
+The :ref:`templatetags-show-pages` template tag documentation describes how to
+customize Digg-style pagination defining your own page list callable.
 
 When using the default Digg-style pagination (i.e. when
 ``settings.ENDLESS_PAGINATION_PAGE_LIST_CALLABLE`` is set to *None*), it is
 ----
 
 **New feature**: in addition to the ability to provide a customized pagination
-URL as a context variable, the *paginate* and *lazy_paginate* tags now
-support hardcoded pagination URL endpoints, e.g.:
+URL as a context variable, the :ref:`templatetags-paginate` and
+:ref:`templatetags-lazy-paginate` tags now support hardcoded pagination URL
+endpoints, e.g.:
 
 .. code-block:: html+django
 
 ----
 
 **New feature**: ability to specify negative indexes as values for the
-``starting from page`` argument of the ``paginate`` template tag.
+``starting from page`` argument of the :ref:`templatetags-paginate` template
+tag.
 
 When changing the default page, it is now possible to reference the last page
 (or the second last page, and so on) by using negative indexes, e.g:
 
 ----
 
-**Fix**: the *using* argument of *paginate* and *lazy_paginate* template tags
-now correctly handles querystring keys containing dashes, e.g.:
+**Fix**: the *using* argument of :ref:`templatetags-paginate` and
+:ref:`templatetags-lazy-paginate` template tags now correctly handles
+querystring keys containing dashes, e.g.:
 
 .. code-block:: html+django
 

doc/current_page_number.rst

 ~~~~~~~~~~~~~~~
 
 You can get and display the current page number in the template using
-the ``show_current_number`` templatetag, e.g.:
+the :ref:`templatetags-show-current-number` template tag, e.g.:
 
 .. code-block:: html+django
 
     {% show_current_number as page_number %}
     {{ page_number }}
 
-See :doc:`templatetags_reference` for more information on
-``show_current_number`` accepted arguments.
+See the :ref:`templatetags-show-current-number` refrence for more information
+on accepted arguments.
 
 In the view
 ~~~~~~~~~~~
 
     page = utils.get_page_number_from_request(request)
 
-If you are using multiple pagination or you have changed the default
-querystring for pagination, you can pass the querystring key as
-an optional argument::
+If you are using :doc:`multiple pagination<multiple_pagination>`, or you have
+changed the default querystring for pagination, you can pass the querystring
+key as an optional argument::
 
     page = utils.get_page_number_from_request(request, querystring_key=mykey)
 

doc/different_first_page.rst

 Sometimes you might want to show on the first page a different number of
 items than on subsequent pages (e.g. in a movie detail page you want to show
 4 images of the movie as a reminder, making the user click to see the next 20
-images). To achieve this, use comma separated *first page* and *per page*
-arguments, e.g.:
+images). To achieve this, use the :ref:`templatetags-paginate` or
+:ref:`templatetags-lazy-paginate` tags with comma separated *first page* and
+*per page* arguments, e.g.:
 
 .. code-block:: html+django
 

doc/digg_pagination.rst

     {% endfor %}
     {% show_pages %}
 
-That's it!
+That's it! As seen, the :ref:`templatetags-paginate` template tag takes care of
+customizing the given queryset and the current template context. The
+:ref:`templatetags-show-pages` one displays the page links allowing for
+navigation to other pages.
 
 Page by page
 ~~~~~~~~~~~~
 
 If you only want to display previous and next links (in a page-by-page
-pagination) you have to use the lower level ``get_pages`` templatetag
-(see :doc:`templatetags_reference`),
-e.g.:
+pagination) you have to use the lower level :ref:`templatetags-get-pages`
+template tag, e.g.:
 
 .. code-block:: html+django
 
 Showing indexes
 ~~~~~~~~~~~~~~~
 
-The ``{% get_pages %}`` template tag adds to the current template context a
-``pages`` variable containing several methods that can be used to fully
-customize how the page links are displayed. For example, assume you want to
-show the indexes of the entries in the current page, followed by the total
+The :ref:`templatetags-get-pages` template tag adds to the current template
+context a ``pages`` variable containing several methods that can be used to
+fully customize how the page links are displayed. For example, assume you want
+to show the indexes of the entries in the current page, followed by the total
 number of entries:
 
 .. code-block:: html+django
         {{ pages }}
     {% endif %}
 
-Again, for a full overview of the ``get_pages`` template tag, see
-:doc:`templatetags_reference`.
+Again, for a full overview of the :ref:`templatetags-get-pages` and all the
+other template tags, see the :doc:`templatetags_reference`.
+
+.. _digg-ajax:
 
 Adding Ajax
 ~~~~~~~~~~~
 
-The view is exactly the same as in ``show_more`` from
-:doc:`twitter_pagination`::
+The view is exactly the same as the one used in
+:ref:`Twitter-style Pagination<twitter-page-template>`::
 
     from endless_pagination.decorators import page_template
 
         return render_to_response(
             template, context, context_instance=RequestContext(request))
 
-Of course you have to split templates, as seen in :doc:`twitter_pagination`,
-but this time a container for the page template is needed too and, by default,
-must have a class named *endless_page_template*.
+As seen before in :doc:`twitter_pagination`, you have to
+:ref:`split the templates<twitter-split-template>`, separating the main one from
+the fragment representing the single page. However, this time a container for
+the page template is also required and, by default, must be an element having a
+class named *endless_page_template*.
 
 *myapp/entry_index.html* becomes:
 
 
 Done.
 
-It is possible to manually override the container selector used by
+It is possible to manually
+:ref:`override the container selector<javascript-selectors>` used by
 *$.endlessPaginate()* to update the page contents. This can be easily achieved
 by customizing the *pageSelector* option of *$.endlessPaginate()*, e.g.:
 
    current_page_number
    templatetags_reference
    javascript
+   generic_views
    customization
-   generic_views
    contributing
    contacts
    thanks

doc/javascript.rst

 
 For each type of pagination it is possible to enable Ajax so that the requested
 page is loaded using an asynchronous request to the server. This is especially
-important for Twitter-style pagination and endless pagination on scroll, but
-Digg-style pagination can also take advantage of this technique.
+important for :doc:`twitter_pagination` and
+:ref:`endless pagination on scroll<javascript-pagination-on-scroll>`, but
+:doc:`digg_pagination` can also take advantage of this technique.
 
 Activating Ajax support
 ~~~~~~~~~~~~~~~~~~~~~~~
         <script>$.endlessPaginate();</script>
     {% endblock %}
 
-This example assumes that you separated the fragment containing the single page
-(*page_tempate*) from the main template (the code snipper above). More on this
-in :doc:`twitter_pagination` and :doc:`digg_pagination`.
+This example assumes that you
+:ref:`separated the fragment<twitter-split-template>` containing the single
+page (*page_tempate*) from the main template (the code snipper above). More on
+this in :doc:`twitter_pagination` and :doc:`digg_pagination`.
 
 The *$.endlessPaginate()* call activates Ajax for each pagination present in
 the page.
 
+.. _javascript-pagination-on-scroll:
+
 Pagination on scroll
 ~~~~~~~~~~~~~~~~~~~~
 
         </script>
     {% endblock %}
 
+.. _javascript-selectors:
+
 Selectors
 ~~~~~~~~~
 
         </script>
     {% endblock %}
 
+.. _javascript-chunks:
+
 On scroll pagination using chunks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
         </script>
     {% endblock %}
 
+.. _javascript-migrate:
+
 Migrate from version 1.1 to 2.0
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/lazy_pagination.rst

 pages in advance.
 
 For this reason it is better to use lazy pagination in conjunction with
-twitter-style pagination (e.g. using the ``show_more`` template tag).
+:doc:`twitter_pagination` (e.g. using the :ref:`templatetags-show-more`
+template tag).
 
 In order to switch to lazy pagination you have to use the
-``{% lazy_paginate %}`` template tag instead of the ``{% paginate %}`` one,
-e.g.:
+:ref:`templatetags-lazy-paginate` template tag instead of the
+:ref:`templatetags-paginate` one, e.g.:
 
 .. code-block:: html+django
 
     {% endfor %}
     {% show_more %}
 
-The ``lazy_paginate`` tag can take all the args of the ``paginate`` one, with
-one exception: negative indexes can not be passed to the ``starting from page``
-argument. See :doc:`templatetags_reference`.
+The :ref:`templatetags-lazy-paginate` tag can take all the args of the
+:ref:`templatetags-paginate` one, with one exception: negative indexes can not
+be passed to the ``starting from page`` argument.

doc/multiple_pagination.rst

     {% endfor %}
     {% show_pages %}
 
-The ``using`` argument of the ``paginate`` template tag allows you to choose
-the name of the querystring key used to track the page number.
+The ``using`` argument of the :ref:`templatetags-paginate` template tag allows
+you to choose the name of the querystring key used to track the page number.
 If not specified the system falls back to
 ``settings.ENDLESS_PAGINATION_PAGE_LABEL``.
 
     {# page_variable is not surrounded by quotes #}
     {% paginate other_entries using page_variable %}
 
-You can use any style of pagination: ``show_pages``, ``get_pages``,
-``show_more`` etc... (see :doc:`templatetags_reference`).
+You can use any style of pagination: :ref:`templatetags-show-pages`,
+:ref:`templatetags-get-pages`, :ref:`templatetags-show-more` etc...
+(see :doc:`templatetags_reference`).
 
 Adding Ajax for multiple pagination
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Obviously each pagination needs a template for the page contents. Remember to
 box each page in a div with a class called *endless_page_template*, or to
 specify the container selector passing an option to *$.endlessPaginate()* as
-seen in :doc:`digg_pagination`.
+seen in :ref:`Digg-style pagination and Ajax<digg-ajax>`.
 
 *myapp/entry_index.html*:
 
     {% endfor %}
     {% show_pages %}
 
-Again, the decorator ``page_template`` simplifies the management of Ajax
-requests in views. You must, however, map different paginations to different
-page templates.
+As seen :ref:`before<twitter-page-template>`, the decorator ``page_template``
+simplifies the management of Ajax requests in views. You must, however, map
+different paginations to different page templates.
 
 You can chain decorator calls relating a template to the associated
 querystring key, e.g.::
 decorator, then the page template is associated to the querystring key
 defined in the settings.
 
+.. _multiple-page-templates:
+
 You can use the ``page_templates`` (note the trailing *s*) decorator in
 substitution of a decorator chain when you need multiple Ajax paginations.
 The previous example can be written as::
     {% show_pages %}
 
 Done.
+
+This is just a basic example. To continue exploring all the Django Endless
+Pagination features, have a look at :doc:`twitter_pagination` or
+:doc:`digg_pagination`.

doc/templatetags_reference.rst

 Templatetags reference
 ======================
 
+.. _templatetags-paginate:
+
 paginate
 ~~~~~~~~
 
 
     {% paginate 3,10 entries %}
 
-You must use this tag before calling the `show_more`_ one.
+You must use this tag before calling the `show_more`_, `get_pages`_ or
+`show_pages`_ ones.
+
+.. _templatetags-lazy-paginate:
 
 lazy_paginate
 ~~~~~~~~~~~~~
 one exception: negative indexes can not be passed to the ``starting from page``
 argument.
 
+.. _templatetags-show-more:
+
 show_more
 ~~~~~~~~~
 
 
 Must be called after `paginate`_ or `lazy_paginate`_.
 
+.. _templatetags-get-pages:
+
 get_pages
 ~~~~~~~~~
 
 
 This must be called after `paginate`_ or `lazy_paginate`_.
 
+.. _templatetags-show-pages:
+
 show_pages
 ~~~~~~~~~~
 
 
 This must be called after `paginate`_ or `lazy_paginate`_.
 
+.. _templatetags-show-current-number:
+
 show_current_number
 ~~~~~~~~~~~~~~~~~~~
 

doc/twitter_pagination.rst

         {# your code to show the entry #}
     {% endfor %}
 
+.. _twitter-split-template:
+
 Split the template
 ~~~~~~~~~~~~~~~~~~
 
         return render_to_response(
             template, context, context_instance=RequestContext(request))
 
-See below how to obtain the same result **just decorating the view**
-(in a way compatible with generic views too).
+See :ref:`below<twitter-page-template>` how to obtain the same result
+**just decorating the view** (in a way compatible with generic views too).
 
 *myapp/entry_index.html* becomes:
 
         {# your code to show the entry #}
     {% endfor %}
 
+.. _twitter-page-template:
+
 A shortcut for ajaxed views
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Paginating objects
 ~~~~~~~~~~~~~~~~~~
 
-All that's left is changing the page template and loading the endless
-templatetags, the jQuery library and the jQuery plugin
-``endless-pagination.js`` included in the distribution under
+All that's left is changing the page template and loading the
+:doc:`endless templatetags<templatetags_reference>`, the jQuery library and the
+jQuery plugin ``endless-pagination.js`` included in the distribution under
 ``/static/endless_pagination/js/``.
 
 *myapp/entry_index.html* becomes:
     {% endfor %}
     {% show_more %}
 
-See the :doc:`javascript` for a detailed explanation of how to integrate
-JavaScript and Ajax features in Django Endless Pagination.
+The :ref:`templatetags-paginate` template tag takes care of customizing the
+given queryset and the current template context. In the context of a
+Twitter-style pagination the :ref:`templatetags-paginate` tag is often replaced
+by the :ref:`templatetags-lazy-paginate` one, which offers, more or less, the
+same functionalities and allows for reducing database access: see
+:doc:`lazy_pagination`.
+
+The :ref:`templatetags-show-more` one displays the link to navigate to the next
+page.
+
+You might want to glance at the :doc:`javascript` for a detailed explanation of
+how to integrate JavaScript and Ajax features in Django Endless Pagination.
 
 Pagination on scroll
 ~~~~~~~~~~~~~~~~~~~~
 
 If you want new items to load when the user scroll down the browser page,
-you can use the **pagination on scroll** feature: just set the
-*paginateOnScroll* option of *$.endlessPaginate()* to *true*, e.g.:
+you can use the :ref:`pagination on scroll<javascript-pagination-on-scroll>`
+feature: just set the *paginateOnScroll* option of *$.endlessPaginate()* to
+*true*, e.g.:
 
 .. code-block:: html+django
 
 That's all. See the :doc:`templatetags_reference` to improve the use of
 included templatetags.
 
-It is possible to set the bottom margin used for pagination on scroll
-(default is 1 pixel). For example, if you want the pagination on scroll
-to be activated when 20 pixels remain to the end of the page:
+It is possible to set the bottom margin used for
+:ref:`pagination on scroll<javascript-pagination-on-scroll>` (default is 1
+pixel). For example, if you want the pagination on scroll to be activated when
+20 pixels remain to the end of the page:
 
 .. code-block:: html+django
 
 
 Again, see the :doc:`javascript`.
 
+On scroll pagination using chunks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes, when using on scroll pagination, you may want to still display
+the *show more* link after each *N* pages. In Django Endless Pagination this is
+called *chunk size*. For instance, a chunk size of 5 means that a *show more*
+link is displayed after page 5 is loaded, then after page 10, then after page
+15 and so on. Activating :ref:`chunks<javascript-chunks>` is straightforward,
+just use the *paginateOnScrollChunkSize* option:
+
+.. code-block:: html+django
+
+    {% block js %}
+        {{ block.super }}
+        <script src="http://code.jquery.com/jquery-latest.js"></script>
+        <script src="{{ STATIC_URL }}endless_pagination/js/endless-pagination.js"></script>
+        <script>
+            $.endlessPaginate({
+                paginateOnScroll: true,
+                paginateOnScrollChunkSize: 5
+            });
+        </script>
+    {% endblock %}
+
 Before version 2.0
 ~~~~~~~~~~~~~~~~~~
 
     <script src="{{ STATIC_URL }}endless_pagination/js/endless.js"></script>
     <script src="{{ STATIC_URL }}endless_pagination/js/endless_on_scroll.js"></script>
 
-However, please consider migrating as soon as possible: the old JavaScript
-files are deprecated, are no longer maintained, and don't provide the new
-JavaScript features.
+However, please consider :ref:`migrating<javascript-migrate>` as soon as
+possible: the old JavaScript files are deprecated, are no longer maintained,
+and don't provide the new JavaScript features. Also note that the old
+Javascript files will not work if jQuery >= 1.9 is used.
 
 Please refer to the :doc:`javascript` for a detailed overview of the new
-features and for instructions on **how to migrate** from the old JavaScript
-files to the new one.
+features and for instructions on :ref:`how to migrate<javascript-migrate>` from
+the old JavaScript files to the new one.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.