**************************
Pagination in Slices
**************************

.. include:: ../incomplete.rst

There are instances when the data given to the card or table slice is too much that it causes the
page to become very slow or frozen when loaded. With pagination, the data service can send a
chunk of the data to the front-end with additional data being requested by the
pagination links (like "next" and "prev").

Front-end
===========
The front-end renders a pagination widget at the bottom of the slice if the slice is configured 
to be paginated.

.. image:: images/paginated-slice.png
   :alt: A paginated slice


Slice Config
------------
To configure a slice to be paginated, set up it's config like this:

.. code-block:: python

    config:
      pagination:
        pageSize: 13

.. note::
   In Juicebox 4 some slices are automatically paginated with default values. You can 
   disable pagination for these slices by setting config.pagination.pageSize to zero, like this.
   
   .. code-block:: python
   
      config:
         pagination:
            pageSize: 0


Selections under pagination
---------------------------
The selections in the slice are maintained across pages during searching, sorting
and page traversal. However, if the slice is filtered by any of the slices above it or the
global filters, the selections will be matched to the data in the response and only the matches maintained.

How pagination works
--------------------

When the user clicks the "next" or "prev" links, additional pagination (``_pagination``) parameters are
passed to the data service:

.. code-block:: none

  {
    _selectedResponses:{foo: "Please give me a better name", bar: "Please give me a better name"}
    _pagination: { "page": 2, "q": "Nashville", "sort": ["-pop2000"] }
    exclusion:["vent_trach"]
    gender:["F"]
    metric:["pop2000"]
    ...
  }

These ``_pagination`` parameters are:

:page: What page to return (given the ``config.pagination.pageSize``). **REQUIRED**
:q: What search phrase to limit to (given the search fields defined in config). The backend is
   responsible for implementing search. **OPTIONAL**
:sort: An array of sort fields. Prefixing the field with a "-" indicates they are sorted
    in descending order. No prefix means ascending order. **OPTIONAL**

Backend
========

If there is a ``_pagination`` parameter passed in the request, the data service needs to 
perform searching or sorting, and then return the appropriate page.

Search needs to be added to the recipe.

.. code-block:: python

  recipe().dimensions('a', 'b').metrics('c').search('a','b', q="foo")


All recipes that need to response to a pagination request must implement a ``order_by`` clause in their recipes.
Failing to do so will generate an exception:

.. code-block:: python

   BadRecipe: Recipes that paginate must include a default order_by

When the data service returns the response for the paginated slice, it needs to tell the front-end
which page of data it is returning and how many total items exist. This information is injected by the
data service into ``config.pagination`` when the data service runs:

.. code-block:: javascript

  {
  'config': {
    'pagination':
      {
         page: 2,
         pageSize: 13,
         totalItems: 51
      },
  'data': [{ 'name': 'items',  'values': [] }],
  'metadata': {},
  'name': 'Untitled',
  'templateContext': {},
  'version': '3'
  }