.. _topics-pagination:

=========================
ペジネータ (paginator)
=========================

:revision-up-to: 8961 (1.0)

.. module:: django.core.paginator
   :synopsis: ページ分割されたデータを管理しやすくするためのクラスです。

.. versionchanged:: 1.0
   ペジネーション機能はバージョン 1.0 でほぼ完全に書き直されました。

Django は、ページ分割された (paginated) データを扱うためのペジネータ
(paginator) クラスを提供しています。ページ分割とは、データが複数のページに
わたって表示され、それぞれのページに「前へ／次へ」といったリンクがある状態
を指します。ペジネータのクラスは、 :file:`django/core/paginator.py` モジュー
ルで定義されています。

.. Example:

例
=======

ペジネータを使うには、まず :class:`Paginator` クラスにオブジェクトのリスト
と、各ページに表示したい要素数を指定してインスタンスを生成します。生成され
るインスタンスは、各ページの要素にアクセスするためのメソッドを提供していま
す::

    >>> from django.core.paginator import Paginator
    >>> objects = ['john', 'paul', 'george', 'ringo']
    >>> p = Paginator(objects, 2)

    >>> p.count
    4
    >>> p.num_pages
    2
    >>> p.page_range
    [1, 2]

    >>> page1 = p.page(1)
    >>> page1
    <Page 1 of 2>
    >>> page1.object_list
    ['john', 'paul']

    >>> page2 = p.page(2)
    >>> page2.object_list
    ['george', 'ringo']
    >>> page2.has_next()
    False
    >>> page2.has_previous()
    True
    >>> page2.has_other_pages()
    True
    >>> page2.next_page_number()
    3
    >>> page2.previous_page_number()
    1
    >>> page2.start_index() # The 1-based index of the first item on this page
    3
    >>> page2.end_index() # The 1-based index of the last item on this page
    4

    >>> p.page(0)
    Traceback (most recent call last):
    ...
    EmptyPage: That page number is less than 1
    >>> p.page(3)
    Traceback (most recent call last):
    ...
    EmptyPage: That page contains no results

.. note::
    ``Paginator`` にはリストやタプル、 Django の ``QuerySet`` の他に、
    ``count()`` や ``__len__()`` をメソッドを備えた任意のオブジェクトを渡せ
    ることに注意してください。 ``Paginator`` は、渡されたコンテナ内のオブジェ
    クトの数を調べるのに、まず ``count()`` を呼び出そうとし、 ``count()``
    がなければ ``len()`` にフォールバックします。これにより、 ``QuerySet``
    のようなオブジェクトで、より効率的な ``count()`` を呼び出しています。 

.. _Paginator objects:

``Paginator`` オブジェクト
===========================

:class:`Paginator` クラスは、以下のようなコンストラクタを持っています:

.. class:: Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True)

.. _Required arguments:

必須の引数
------------------

``object_list``
    リスト、タプル、Django の ``QuerySet``, または ``count()`` や
    ``__len__()`` メソッドを備えたオブジェクトを指定します。

``per_page``
    一ページに表示するオブジェクトの最大個数です (後述のオプション引数
    ``orphans`` も参照してください)。

.. _Optional arguments:

オプションの引数
------------------

``orphans``
    最後のページに表示する要素の個数です。デフォルト値はゼロに設定されてい
    ます。最後のページに表示するオブジェクトの個数を一定以上にしたい場合に
    使ってください。 ``orphans`` を設定すると、ページ分割した要素の末尾のグ
    ループの個数が ``orphans`` の設定値以下のときに、そのグループの要素だけ
    のページを表示するのではなく、ひとつ前のページの要素に繰り入れて表示し
    ます（すなわち、一つ手前のページが最終ページになります）。例えば、
    ``per-page=10`` かつ ``orphans=3`` のペジネータで 23 個のオブジェクトを
    表示すると、ページは二つに分割され、最初のページには 10 個、二つ目のペー
    ジ（最終ページ）には 13 個の要素を表示します。

``allow_empty_first_page``
    先頭のページが空でもよいかどうかを決めるパラメタです。 ``False`` に設定
    すると、 ``object_list`` が空のときに ``EmptyPage`` 例外を送出します。

.. _Paginator Methods:

メソッド
---------

.. method:: Paginator.page(number)

    指定ページの :class:``Page`` オブジェクトを返します。ページ番号は 1 か
    ら始まる数です。存在しないページを指定すると :exc:`InvalidPage` を送出
    します。

.. _Paginator Attributes:

属性
----------

.. attribute:: Paginator.count
    
    全てのページにわたるオブジェクトの合計数です。
    
    .. note:: 

        ``object_list`` に入っているオブジェクトの個数を調べるときに、
        ``Paginator`` はまず ``object_list.count()`` を呼びます。
        ``object_list`` に ``count()`` メソッドがなければ、 ``Paginator`` 
	は ``object_list.__len__()`` に切り替えます。これにより、
        ``QuerySet`` のようなオブジェクトで、より効率的な ``count()`` を呼
        び出しているのです。
        
.. attribute:: Paginator.num_pages
    
    総ページ数です。
    
.. attribute:: Paginator.page_range
    
    ``[1, 2, 3, 4]`` のように、 1 から始まるページ番号です。


.. _`InvalidPage exceptions`:

``InvalidPage`` 例外
==========================

リクエストされたページが無効なページ (整数でないページ番号) であったり、ペー
ジにオブジェクトが含まれていない場合、 ``page()`` メソッドは
``InvalidPage`` を送出します。通常はこの ``InvalidPage`` 例外をトラップする
だけですみますが、より細かく例外処理するには、以下の例外をトラップしてくだ
さい:

``PageNotAnInteger``
    ``page()`` に整数でない値を渡したときに送出されます。

``EmptyPage`` 
    ``page()`` には有効な値が渡されているが、ページにオブジェクトが含まれな
    い場合に送出されます。

どちらの例外も ``InvalidPage`` のサブクラスなので、単に
``except InvalidPage`` としておけば両方の例外を捕捉できます。

.. _Page objects:

``Page`` オブジェクト
=====================

.. _Page Methods:

メソッド
---------

.. method:: Page.has_next()
    
    次のページがある場合に ``True`` を返します。    
    
.. method:: Page.has_previous()
    
    前のページがある場合に ``True`` を返します。
    
.. method:: Page.has_other_pages()
    
    前後 *いずれか* のページがある場合に ``True`` を返します。
    
.. method:: Page.next_page_number()
    
    次のページが存在するかどうかに関係なく、「次のページ」のページ番号を返
    します。
    
.. method:: Page.previous_page_number()
    
    前のページが存在するかどうかに関係なく、「前のページ」のページ番号を返
    します。
    
.. method:: Page.start_index()
    
    ページの先頭のオブジェクトの通番を、ペジネータ全体にわたるオブジェクト
    のリストの通番で返します。通番は 1 から始まります。例えば、ページあたり
    2 個のオブジェクトを表示するペジネータで 5 個のオブジェクトをページ分割
    している場合、2 ページ目の
    :meth:`~django.core.paginator.Paage.start_index` 
    は ``3`` を返します。
    
.. method:: Page.end_index()
    
    ページの末尾のオブジェクトの通番を、ペジネータ全体にわたるオブジェクト
    のリストの通番で返します。通番は 1 から始まります。例えば、ページあたり
    2 個のオブジェクトを表示するペジネータで 5 個のオブジェクトをページ分割
    している場合、2 ページ目の :meth:`~django.core.paginator.end_index()`
    は ``4`` を返します。 

.. _Page Attributes:

属性
------

.. attribute:: Page.object_list
    
    ページ上のオブジェクトのリストです。
    
.. attribute:: Page.number
    
    1 から数えたページ番号です。
    
.. attribute:: Page.paginator
    
    ページの結びついている ``Paginator`` オブジェクトです。