# Templates

This document will describe how pagination can be rendered, extended and used in
templates. For now there's only a sliding pagination supported, so all documentation
will reference it.

## Overriding default pagination template

There are few ways to override templates

### Configuration

This way it will override it globally for all default pagination rendering.

You can override templates in [configuration of
paginator](http://github.com/KnpLabs/KnpPaginatorBundle/blob/master/README.md#configuration)

Or place this parameter in **config/packages/knp_paginator.yaml**

    knp_paginator.template.pagination: my_pagination.html.twig

Same for sorting link template:

    knp_paginator.template.sortable: my_sortable.html.twig

### Directly in pagination

``` php
$paginator = $this->get('knp_paginator');
$pagination = $paginator->paginate($target, $page);
$pagination->setTemplate('my_pagination.html.twig');
$pagination->setSortableTemplate('my_sortable.html.twig');
```

or in view

``` html
{% do pagination.setTemplate('my_pagination.html.twig') %}
```

### In render method

```twig
{{ knp_pagination_render(pagination, 'my_pagination.html.twig') }}
```

or by specifying path to your custom template that is located under your project's `templates` directory:
```twig
{{ knp_pagination_sortable(pagination, 'date', 'c.publishedAt', {}, {}, 'KnpPaginator/Pagination/bootstrap_v4_sortable_link.html.twig') }}
{{ knp_pagination_render(pagination, 'KnpPaginator/Pagination/bootstrap_v4_pagination.html.twig') }}
```

## Other useful parameters

By default when render method is triggered, pagination renders the template
with standard arguments provided:

- pagination parameters, like pages in range, current page and so on..
- route - which is used to generate page, sorting urls
- request query, which contains all GET request parameters
- extra pagination template parameters

Except from pagination parameters, others can be modified or adapted to some
use cases. Usually its possible, you might need setting a route if default is not
matched correctly (because of rendering in sub requests). Or adding additional
query or view parameters.

### Setting a route and query parameters to use for pagination urls

``` php
<?php
$paginator = $this->get('knp_paginator');
$pagination = $paginator->paginate($target, $page);
$pagination->setUsedRoute('blog_articles');
```

In case if route requires additional parameters

``` php
<?php
$pagination->setParam('category', 'news');
```

This would set additional query parameter

### Additional pagination template parameters

If you need custom parameters in pagination template, use:

``` php
<?php
// set an array of custom parameters
$pagination->setCustomParameters([
    'align' => 'center', # center|right (for template: twitter_bootstrap_v4_pagination and foundation_v6_pagination)
    'size' => 'large', # small|large (for template: twitter_bootstrap_v4_pagination)
    'style' => 'bottom',
    'span_class' => 'whatever',
]);
```

### You can also change the page range

Default page range is 5 pages in sliding pagination. Doing it in controller:

``` php
<?php
$pagination->setPageRange(7);
```

In template:

``` php
{% do pagination.setPageRange(7) %}
```

### Setting a page limit

The default page limit is unlimited, but if for some reason you want to limit
the number of pages you can do so. Doing it in controller:

``` php
<?php
$pagination->setPageLimit(25);
```

In template:

``` php
{% do pagination.setPageLimit(25) %}
```

## Choose the sorting direction

The `knp_pagination_sortable()` template switch automatically the sorting direction but sometimes you need to propose to your users to select the sorting direction of you list.
You can add an array at the end of `knp_pagination_sortable()` to choose the direction.

``` html
{{ knp_pagination_sortable(pagination, 'Title A-Z', 'a.title', {}, {'direction': 'asc'}) }}
{{ knp_pagination_sortable(pagination, 'Title Z-A', 'a.title', {}, {'direction': 'desc'}) }}
```
(Assuming you use the default configuration value of sort_direction_name)

<a name="query-parameters"></a>

## Query parameters

If you need to change query parameters for paginator or use multiple paginators for the same page.
You can customize these parameter names through [configuration](http://github.com/KnpLabs/KnpPaginatorBundle/blob/master/README.md#configuration)
or manually with paginator options.

``` php
<?php // controller

// will change "page" query parameter into "section" and sort direction "direction" into "dir"
$paginator = $this->get('knp_paginator');
$pagination = $paginator->paginate(
    $query, // target to paginate
    $this->get('request')->query->getInt('section', 1), // page parameter, now section
    10, // limit per page
    ['pageParameterName' => 'section', 'sortDirectionParameterName' => 'dir']
);
```

Or even in Twig:

```jinja
    {{ knp_pagination_render(
            pagination,
            '@KnpPaginator/Pagination/twitter_bootstrap_v4_pagination.html.twig',
            {
                'queryParam1': 'param1 value',
                'queryParam2': 'param2 value'
            },
            {
                'viewParam1': 'param1 value',
                'viewParam2': 'param2 value'
            },
        ) }}
```

## Filter your query

Only include this lines and enjoy the pagination :
``` html
{{ knp_pagination_filter(pagination, {
        'entity.name': 'Name',
    }) }}
```

## Customize rendering

### Bulma

You can configure the position, the size, and make the buttons rounded or not:
- `align`: `'left'`, `'center'`, or `'right'`. By default align is not modified
- `size`: `'small'`, `'medium'`, or `'large'`. By default, size is not modified
- `rounded`: `true` or `false`. By default it's `false`

In your controller:
```php
$pagination->setCustomParameters([
    'align' => 'center',
    'size' => 'large',
    'rounded' => true,
]);
```

or in the view:
```twig
{{ knp_pagination_render(pagination, null, {}, {
   'align': 'center',
   'size': 'large',
   'rounded': true,
}) }}
```