1. Francesco Banconi
  2. django-endless-pagination

Commits

Francesco Banconi  committed d308aa6

Improve documentation cross references.

  • Participants
  • Parent commits e9978ab
  • Branches default

Comments (0)

Files changed (11)

File doc/changelog.rst

View file
 
 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
 

File doc/current_page_number.rst

View file
 ~~~~~~~~~~~~~~~
 
 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)
 

File doc/different_first_page.rst

View file
 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
 

File doc/digg_pagination.rst

View file
     {% 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.:
 

File doc/index.rst

View file
    current_page_number
    templatetags_reference
    javascript
+   generic_views
    customization
-   generic_views
    contributing
    contacts
    thanks

File doc/javascript.rst

View file
 
 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

File doc/lazy_pagination.rst

View file
 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.

File doc/multiple_pagination.rst

View file
     {% 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::

File doc/start.rst

View file
     {% 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`.

File doc/templatetags_reference.rst

View file
 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
 ~~~~~~~~~~~~~~~~~~~
 

File doc/twitter_pagination.rst

View file
         {# 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.