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

WhiteOctoberPagerfantaBundle

by sampart

Bundle to use Pagerfanta with Symfony

This project is no longer maintained. If you are using it with Symfony 3.4, 4.4 or 5, you may want to use this fork instead.

WhiteOctoberPagerfantaBundle

Build Status Scrutinizer Quality Score SensioLabsInsight

Bundle to use Pagerfanta with Symfony.

Note: If you are using a 2.0.x release of Symfony2, please use the symfony2.0 branch of this bundle. The master branch of this bundle tracks the Symfony master branch.

The bundle includes:

  • Twig function to render pagerfantas with views and options.
  • Way to use easily views.
  • Way to reuse options in views.
  • Basic CSS for the DefaultView.

Installation

1) Use Composer to download the library

php composer.phar require white-october/pagerfanta-bundle

2) Then add the WhiteOctoberPagerfantaBundle to your application:

In Symfony < 4:

// app/AppKernel.php
public function registerBundles()
{
    return array(
        // ...
        new WhiteOctober\PagerfantaBundle\WhiteOctoberPagerfantaBundle(),
        // ...
    );
}

In Symfony 4 with Symfony Flex this will be done automatically for you.

3) Configure and use things!

A) Creating a Pager is shown on the Pagerfanta documentation. If you're using the Doctrine ORM, you'll want to use the DoctrineORMAdapter

B) Rendering in Twig is shown below in the Rendering Pagerfantas section.

C) Configuration is shown through this document

Rendering Pagerfantas

First, you'll need to pass an instance of Pagerfanta as a parameter into your template.
For example:

$adapter = new DoctrineORMAdapter($queryBuilder);
$pagerfanta = new Pagerfanta($adapter);
return $this->render('@YourApp/Main/example.html.twig', [
    'my_pager' => $pagerfanta,
]);

You then call the the Pagerfanta Twig extension, passing in the Pagerfanta instance.
The routes are generated automatically for the current route using the variable "page" to propagate the page number.
By default, the bundle uses the DefaultView with the default name. The default syntax is:

<div class="pagerfanta">
    {{ pagerfanta(my_pager) }}
</div>

By default, the "page" variable is also added for the link to the first page. To
disable the generation of ?page=1 in the url, simply set the omitFirstPage option
to true when calling the pagerfanta twig function:

{{ pagerfanta(my_pager, 'default', { 'omitFirstPage': true}) }}

You can omit template parameter to make function call shorter, default template will be used:

{{ pagerfanta(my_pager, { 'omitFirstPage': true }) }}

If you have multiple pagers on one page, you'll need to change the name of the page parameter.
Here's an example:

<div class="pagerfanta">
    {{ pagerfanta(my_other_pager, 'default', {'pageParameter': '[page_other]'}) }}
</div>

Note the square brackets around page_other; this won't work without them.

Twitter Bootstrap

The bundle also has a Twitter Bootstrap view.

For Bootstrap 2:

<div class="pagerfanta">
    {{ pagerfanta(my_pager, 'twitter_bootstrap') }}
</div>

For Bootstrap 3:

<div class="pagerfanta">
    {{ pagerfanta(my_pager, 'twitter_bootstrap3') }}
</div>

For Bootstrap 4:

<div class="pagerfanta">
    {{ pagerfanta(my_pager, 'twitter_bootstrap4') }}
</div>

Custom template

If you want to use a custom template, add another argument:

<div class="pagerfanta">
    {{ pagerfanta(my_pager, 'my_template') }}
</div>

With options:

{{ pagerfanta(my_pager, 'default', { 'proximity': 2}) }}

See the Pagerfanta documentation for the list of possible parameters.

Rendering the page of items itself

The items can be retrieved using currentPageResults. For example:

{% for item in my_pager.currentPageResults %}
    <ul>
        <li>{{ item.id }}</li>
    </ul>
{% endfor %}

Translate in your language

The bundle also offers two views to translate the default and the
twitter bootstrap views.

{{ pagerfanta(my_pager, 'default_translated') }}

{{ pagerfanta(my_pager, 'twitter_bootstrap_translated') }}

Adding Views

The views are added to the container with the pagerfanta.view tag:

XML

<service id="pagerfanta.view.default" class="Pagerfanta\View\DefaultView" public="false">
    <tag name="pagerfanta.view" alias="default" />
</service>

YAML

services:
    pagerfanta.view.default:
        class: Pagerfanta\View\DefaultView
        public: false
        tags: [{ name: pagerfanta.view, alias: default }]

Reusing Options

Sometimes you want to reuse options of a view in your project, and you don't
want to write them all the times you render a view, or you can have different
configurations for a view and you want to save them in a place to be able to
change them easily.

For this you have to define views with the special view OptionableView:

services:
    pagerfanta.view.my_view_1:
        class: Pagerfanta\View\OptionableView
        arguments:
            - @pagerfanta.view.default
            - { proximity: 2, prev_message: Anterior, next_message: Siguiente }
        public: false
        tags: [{ name: pagerfanta.view, alias: my_view_1 }]
    pagerfanta.view.my_view_2:
        class: Pagerfanta\View\OptionableView
        arguments:
            - @pagerfanta.view.default
            - { proximity: 5 }
        public: false
        tags: [{ name: pagerfanta.view, alias: my_view_2 }]

And using then:

{{ pagerfanta(my_pager, 'my_view_1') }}
{{ pagerfanta(my_pager, 'my_view_2') }}

The easiest way to render pagerfantas (or paginators!) ;)

Basic CSS for the default view

The bundles comes with basic CSS for the default view so you can get started with a good paginator faster.
Of course you can change it, use another one or create your own view.

<link rel="stylesheet" href="{{ asset('bundles/whiteoctoberpagerfanta/css/pagerfantaDefault.css') }}" type="text/css" media="all" />

Configuration

It's possible to configure the default view for all rendering in your
configuration file:

white_october_pagerfanta:
    default_view: my_view_1

Making bad page numbers return a HTTP 500

Right now when the page is out of range or not a number,
the server returns a 404 response by default.
You can set the following parameters to different than default value
to_http_not_found (ie. null) to show a 500 exception when the
requested page is not valid instead.

// app/config/config.yml
white_october_pagerfanta:
    exceptions_strategy:
        out_of_range_page:        ~
        not_valid_current_page:   ~

More information

For more advanced documentation, check the Pagerfanta documentation.

Contributing

We welcome contributions to this project, including pull requests and issues (and discussions on existing issues).

If you'd like to contribute code but aren't sure what, the issues list is a good place to start.
If you're a first-time code contributor, you may find Github's guide to forking projects helpful.

All contributors (whether contributing code, involved in issue discussions, or involved in any other way) must abide by our code of conduct.

Acknowledgements

Pablo Díez (pablodip@gmail.com) for most of the work on the first versions of this bundle.

This project was originally located at https://github.com/whiteoctober/WhiteOctoberPagerfantaBundle.

License

Pagerfanta is licensed under the MIT License. See the LICENSE file for full
details.

Copyright (c) 2011 White October Ltd
http://www.whiteoctober.co.uk/

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.
white_october_pagerfanta:
default_view: default
exceptions_strategy:
out_of_range_page: to_http_not_found
not_valid_current_page: to_http_not_found
  • Add details of original location
    By web-flow, 9 days ago
  • Updated version numbers in fork description (cf https://github.com/whiteoctober/WhiteOctoberPagerfantaBundle/issues/223)
    By sampart, 9 months ago
  • Merge pull request #222 from Florian-Merle/patch-1
    By web-flow, 10 months ago
  • Fix typo README.md
    By web-flow, 10 months ago
  • Add link to maintained fork
    By sampart, 11 months ago
  • Merge pull request #218 from jeroennoten/patch-1
    By web-flow, 11 months ago
  • Replace the use of deprecated get/setException() by get/setThrowable()
    By Jeroen Noten, 11 months ago
  • Replace the use of deprecated get/setException() by get/setThrowable()
    By web-flow, 11 months ago
  • Merge pull request #216 from mbabker/patch-1
    By web-flow, 1 year ago
  • Expand Twig version conflict
    By web-flow, 1 year ago
  • Merge pull request #214 from mynameisbogdan/master
    By web-flow, 1 year ago
  • bump minimum versions for php and twig
    By mynameisbogdan, 1 year ago
  • Switch to namespaced Twig classes
    By mynameisbogdan, 1 year ago
  • Add note about looking for maintainers
    By Sam Partington, 1 year ago
  • Merge pull request #211 from johnutzm/ro-translation-fix
    By web-flow, 1 year ago
  • fix Romanian translation file
    By web-flow, 1 year ago
  • Merge pull request #209 from rogamoore/patch-1
    By web-flow, 1 year ago
  • Update README regarding Symfony 4
    By web-flow, 1 year ago
  • Merge pull request #208 from mbabker/patch-1
    By web-flow, 1 year ago
  • Update bundle configuration for Symfony 4.2 change
    By web-flow, 1 year ago
  • Add swahili translation (#207)
    By Sam Partington, 2 years ago
  • Add PHP 7.3 to Travis (#206)
    By Sam Partington, 2 years ago
  • Merge pull request #205 from emodric/patch-1
    By web-flow, 2 years ago
  • Update PSR-4 configuration to fix Symfony Flex auto-registration
    By emodric, 2 years ago
  • Merge pull request #203 from gabiudrescu/patch-1
    By web-flow, 2 years ago
  • Explicitly require Symfony translator
    By web-flow, 2 years ago
  • Merge pull request #200 from AntoineLemaire/master
    By web-flow, 2 years ago
  • Add swedish translation
    By AntoineLemaire, 2 years ago
  • Add finnish translation
    By AntoineLemaire, 2 years ago
  • Merge pull request #196 from jhfyang/patch-1
    By web-flow, 2 years ago