Developed with love by KnpLabs Hire us for your project!
18

PaginatorBundle

by NadiaLabs

Yet another Pagination bundle

NadiaPaginatorBundle

NadiaPaginatorBundle can help you build pagination UI quickly. You can design your filter and search UI with Symfony Form component, and easily validate input parameters with Form.

Example Image

Installation

Install with composer , run:

composer require nadialabs/paginator-bundle

Register Bundle to AppKernel

// app/AppKernel.php
public function registerBundles()
{
    return array(
        // ...
        new Nadia\Bundle\PaginatorBundle\NadiaPaginatorBundle(),
        // ...
    );
}

Bundle Configuration

nadia_paginator:
    default_options:
        input_key_class: Nadia\Bundle\PaginatorBundle\Input\InputKeys
        default_page_size: 10
        default_page_range: 8
        session_enabled: false
        default_translation_domain: null
    templates:
        pages: '@NadiaPaginator/templates/bootstrap4/pages.html.twig'
        searches: '@NadiaPaginator/templates/bootstrap4/searches.html.twig'
        filters: '@NadiaPaginator/templates/bootstrap4/filters.html.twig'
        sorts: '@NadiaPaginator/templates/bootstrap4/sorts.html.twig'
        sort_link: '@NadiaPaginator/templates/bootstrap4/sort_link.html.twig'
        page_sizes: '@NadiaPaginator/templates/bootstrap4/page_sizes.html.twig'
  • default_options
    • input_key_class: The class that define the http request parameter keys.
    • default_page_size: Default page size
    • default_page_range: Default page range (control page link amounts)
    • session_enabled: Enable session support, store input data in session. You can use a clean URL without query string when enabled it. Otherwise the filter, search, sort, page size, and page parameters will be part of URL query string, or transfer by POST request body.
    • default_translation_domain: Default translation-domain value for each Form.
  • templates
    • pages: Template for rendering pages
    • searches: Template for rendering searches block
    • filters: Template for rendering filters block
    • sorts: Template for rendering sort selection block
    • sort_link: Template for rendering sort link
    • page_sizes: Template for rendering page size selection block

Create PaginatorType class

Define a Paginator configuration.

Example class: AppBundle\Paginator\Movies\PaginatorType

You can implement these methods to define a PaginatorType class:

buildSearch

Use SearchBuilder to setup search form elements with Symfony FormType styles.

buildFilter

Use FilterBuilder to setup filter form elements with Symfony FormType styles.

buildSort

Use SortBuilder to setup sorting methods.

buildPageSize

Use PageSizeBuilder to setup page size list.

getFormOptions

Setup the paginator form options, return an array contain form options.

configureOptions

Setup the paginator options, you can define custom options to injecting extra data into PaginatorType. PaginatorType will use this options in these methods: buildSearch buildFilter buildSort buildPageSize getFormOptions.

Create SearchQueryCompiler class

Define a QueryCompiler to build custom search criteria.

Example class for Doctrine QueryBuilder: AppBundle\Paginator\Movies\FilterQueryCompiler

Create FilterQueryCompiler class

Define a QueryCompiler to build custom filter criteria.

Example class for Doctrine QueryBuilder: AppBundle\Paginator\Movies\FilterQueryCompiler

Create Pagination instance with PaginatorType

Example controller: MovieController

Example entities: Movie, People

To get a Pagination instance, the process as below:

  1. Use PaginatorTypeContainer to generate a PaginatorType instance.
  2. Use PaginatorFactory to generate a Paginator instance with a PaginatorType instance.
  3. Create a query instance (in this example is a Doctrine ORM QueryBuilder instance)
  4. Do paginate with Paginator, and get a Pagination instance
  5. Render a view with Pagination instance
// Example controller action

$options = [
    'movieCompanies' => [
        'Warner Bros.',
        'Sony Pictures',
        'Walt Disney',
        'Universal Pictures',
        '20th Century Fox',
        'Paramount Pictures',
        'Lionsgate Films',
        'The Weinstein Company',
        'DreamWorks Pictures',
    ],
];
$paginator = $this->get('nadia_paginator.paginator_factory')->create(PaginatorType::class, $options);

$qb = $this->getDoctrine()->getRepository(Movie::class)
    ->createQueryBuilder('movie')
    ->select(['movie', 'director'])
    ->leftJoin('movie.director', 'director')
;
/** @var Movie[]|Collection|Pagination $pagination */
$pagination = $paginator->paginate($qb);

Rendering HTML with Twig

You can easily render a list page with this template @NadiaPaginator/templates/bootstrap4/pagination.html.twig

Use twig embed tag to overwrite tableContent block and put your table contents in tableContent block.

Example twig file: index.html.twig

// Render view
$this->render('@App/Movie/index.html.twig', ['pagination' => $pagination]);
{# Example view file #}

{% use '@NadiaPaginator/templates/bootstrap4/pagination.html.twig' %}

<div class="container-fluid">
    {{ block('pagination') }}
</div>

{% block tableContent %}
    <table class="table table-bordered table-striped">
        <thead>
        <tr>
            <th>
                {{ nadia_paginator_sort_link(pagination, 'title', 'movie.title', 'ASC') }}
            </th>
            <th>
                {{ nadia_paginator_sort_link(pagination, 'description', 'movie.description', 'ASC') }}
            </th>
            <th>
                {{ nadia_paginator_sort_link(pagination, 'releasedAt', 'movie.releasedAt', 'DESC') }}
            </th>
            <th>Director</th>
            <th>Company</th>
        </tr>
        </thead>
        <tbody>
        {% for movie in pagination %}
            <tr>
                <td>{{ movie.title }}</td>
                <td>{{ movie.description }}</td>
                <td>{{ movie.releasedAt|date('Y-m-d') }}</td>
                <td>{{ movie.director.name }}</td>
                <td>{{ movie.company }}</td>
            </tr>
        {% endfor %}
        </tbody>
    </table>
{% endblock tableContent %}

Rendering searches block in Twig

Use nadia_paginator_searches method to render search block in Twig template.

{{ nadia_paginator_searches(pagination, {attributes: {class: 'col-md-6 col-xl-4 search'}}) }}

Rendering filters block in Twig

Use nadia_paginator_filters method to render filter block in Twig template.

{{ nadia_paginator_filters(pagination, {attributes: {class: 'col-md-4 col-xl-3 mb-1 filter'}}) }}

Rendering sorts block in Twig

Use nadia_paginator_sorts method to render sorting block in Twig template.

{{ nadia_paginator_sorts(pagination) }}

Rendering page sizes block in Twig

Use nadia_paginator_page_sizes method to render page sizes block in Twig template.

{{ nadia_paginator_page_sizes(pagination) }}

Rendering sort link in Twig

{{ nadia_paginator_sort_link(pagination, 'title', 'movie.title', 'ASC') }}
MIT License

Copyright (c) 2019 NadiaLabs

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
nadia_paginator:
default_options:
input_key_class: Nadia\Bundle\PaginatorBundle\Input\InputKeys
default_page_size: 10
default_page_range: 8
session_enabled: false
default_translation_domain: ~
default_paginator_translation_domain: nadia_paginator
templates:
pages: @NadiaPaginator/templates/bootstrap4/pages.html.twig
searches: @NadiaPaginator/templates/bootstrap4/searches.html.twig
filters: @NadiaPaginator/templates/bootstrap4/filters.html.twig
sorts: @NadiaPaginator/templates/bootstrap4/sorts.html.twig
sort_link: @NadiaPaginator/templates/bootstrap4/sort_link.html.twig
page_sizes: @NadiaPaginator/templates/bootstrap4/page_sizes.html.twig
  • Add "getBuilder" method for future use
    By LeoOnTheEarth, 4 months ago
  • Trigger "nadia_paginator.before" event in Paginator contructor
    By LeoOnTheEarth, 4 months ago
  • Fix session bugs
    By LeoOnTheEarth, 4 months ago
  • Fix filter parameters with submitted form
    By LeoOnTheEarth, 4 months ago
  • Merge pull request #1 from NadiaLabs/add-license-1
    By web-flow, 4 months ago
  • Create LICENSE
    By web-flow, 4 months ago
  • Add DefaultPaginatorType
    By LeoOnTheEarth, 4 months ago
  • Get paginator directly without get PaginatorTypeInterface instance first
    By LeoOnTheEarth, 4 months ago
  • Add common translation domain name for paginator
    By LeoOnTheEarth, 5 months ago
  • Fix bug when '.btn-display-filters' element is not exists
    By LeoOnTheEarth, 5 months ago
  • Auto submit form when changing filter, sort, or page size
    By LeoOnTheEarth, 5 months ago
  • Add default form id
    By LeoOnTheEarth, 5 months ago
  • Submit input values that input key is defined in the form
    By LeoOnTheEarth, 5 months ago
  • Add "default_translation_domain" configuration
    By LeoOnTheEarth, 5 months ago
  • Update bootstrap4 pagination template
    By LeoOnTheEarth, 5 months ago
  • Return default FormView when the form is not defined
    By LeoOnTheEarth, 5 months ago
  • Update README.md and examples
    By LeoOnTheEarth, 5 months ago
  • Refactor ContextProcessor with extensible parameters
    By LeoOnTheEarth, 5 months ago
  • Refactor the deprecated Twig classes
    By LeoOnTheEarth, 5 months ago
  • Refactor Pagination class
    By LeoOnTheEarth, 5 months ago
  • Fix bug for "This form should not contain extra fields." error
    By LeoOnTheEarth, 9 months ago
  • Make service "nadia_paginator.type_container" public
    By LeoOnTheEarth, 9 months ago
  • Make InputKeys values to be "read only"
    By LeoOnTheEarth, 1 year ago
  • Add symfony 4.0 support
    By LeoOnTheEarth, 1 year ago
  • Refactor QueryCompilerInterface
    By LeoOnTheEarth, 1 year ago
  • Update README.md
    By LeoOnTheEarth, 1 year ago
  • Update example image
    By LeoOnTheEarth, 1 year ago
  • Update example image
    By LeoOnTheEarth, 1 year ago
  • Add an example image
    By LeoOnTheEarth, 1 year ago
  • Add a tutorial for this PaginatorBundle
    By LeoOnTheEarth, 1 year ago