Download the PHP package data-dog/pager-bundle without Composer

Pager bundle

This paginator is different in the following ways:

• it has only one general class with around 300 lines of commented code. All the rest of the source code is specific to symfony2 framework, twig helpers and templates.
• it allows to create custom pagination filters - search, select.. and modify the database query based on the specific use cases.
• it also handles sorting in the traditional way.
• it is very small and may be reused in other frameworks with the modifications needed.
• it can only paginate Doctrine2 ORM QueryBuilder. Nothing else will be supported to maintain this library small and backward compatible. For your own customizations just fork or copy the source code.
• there may be only one pagination per request, because url query parameters are constant.

Demo

The best way to see features is to see the actual demo. Just clone the bundle and run:

make

Visit http://localhost:8000 to see the paginated fake projects with custom filters and sorters.

The demo application source is available in example directory and it is a basic symfony application.

Install

First, install it with composer:

composer require data-dog/pager-bundle

Then, add it in your AppKernel bundles.

Usage

The general usage example in your controller:

All you need is to construct Pagination with doctrine query builder and the request. The Pagination object acts like an array, so you can pass it to the view and iterate over paginated items.

The view:

There are twig helper functions used:

• sorter_link - which uses the twig template to generate a link with the sorting order class and such.
• pagination - which creates a pagination html code to navigate pages.

These templates may be modified in standard symfony ways, see the configuration section.

Filters

In order to filter paginated results in different kinds of ways, you may extend the code. In the controller, provide some pagination options.

Now here we have added three filters:

$languages and $spentTimeGroups will be used as filter_select options. The language options are simple and they refer to direct values, so the where statement does not need to be modified. But spent time groups are custom so we use custom options. In that case we need an applyFilter option to be set as a callable so the QueryBuilder could be modified accordingly based on our custom options.

NOTE: if you manage custom filtering, be sure to use parameters or use $qb->expr()->literal("string") to prevent SQL injections. Also if you have custom filter handler, you must manage all your filters, the default handler will not be active.

So how the view has changed:

We have used two new twig functions for filters:

• filter_search - for searching projects by name.
• filter_select - for basic option filters.

These functions are rendering twig templates for our filters.

Links

In case if you need to make a link and maintain search filters and sorters applied, use the $pagination->query() function to get all the necessary url parameters and merge it with your link parameters.

The demo example handles enable and disable toggling for projects in a separate controller action and maintains all pagination properties.

Configuration

There is no necessary configuration for a general usage. But in order to customize pagination there may be global options set in app.php for example:

Templates

The default templates for filters and pagination are based on twitter bootstrap and fontawesome. You can customize them same as any other bundle template, for example:

• pagination - app/Resources/DataDogPagerBundle/views/pagination.html.twig
• search filter - app/Resources/DataDogPagerBundle/views/filters/search.html.twig

Extending with more filters

The best way to customize your filters is to extend twig extension, or create a new extension. If we would provide many options, that would confuse people in the end, so instead we add a little boilerplate. In your bundle services.yml update parameters:

Then create a class:

And finally copy and modify the template based on your needs

Screenshots

License

The pager is free to use and is licensed under the MIT license