seblhaire/bootstrappaginator

A Laravel library to generate paginations

1.3.1 2024-03-13 18:24 UTC

This package is auto-updated.

Last update: 2024-10-13 19:54:10 UTC


README

By Sébastien L'haire

A Laravel library to generate paginations with Bootstrap 4 or 5 CSS Framework.

This library provides two different paginators:

  • a classical paginator with page numbers and previous and next button. paginator image
  • an alphabetical paginator with letters paginator alpha image

Both paginators can be used in same page.

Demo site available here.

Installation

  1. composer require seblhaire/bootstrappaginator

  2. Optionally install Boostrap using npm install bootstrap

  3. Composer will automatically link the package with Laravel. But you still can explicitely add provider and facade to your config/app.php:

  'providers' => [
    ...
      Seblhaire\BootstrapPaginator\BootstrapPaginatorServiceProvider::class,
      ...
    ],
    'aliases' => [
        ...
        'BootstrapPaginator' => Seblhaire\BootstrapPaginator\BootstrapPaginator::class,
      ]
  1. Publish package (optionally).
$ php artisan vendor:publish
  1. Add a translation to Laravel existing pagination.php translation file in directory resources/lang/en/. Simply add key:
'all' => 'All',

Usage

Declare Facade in Controller headers:

 use Seblhaire\BootstrapPaginator\BootstrapPaginator;

Your route must contain a parameter for page in last segment:

Route::get('/issues/{page?}', 'MainController@issues')->name('issues');

Eg: you can have a route https://test.site/issues/9, route https://test.site/issues should display page 1. Controller method can be declared like this:

function issues($page = 1){ ...}

If you include paginator alpha, last segment will be an initial:

Route::get('/authors/{initial?}', 'MainController@authors')->name('authors');

Eg: you can have a route https://test.site/authors/D would display all authors beginning with D. https://test.site/authors will display all items. Controller method can be declared like this:

public function authors($initial = config('bootstrappaginator.valueforall')){ ... }

You can combine both paginators in a single page. In this case, initial will be in the before last position and page parameter in the last position:

Route::get('/authors/{initial?}/{page?}', 'MainController@authors')->name('authors');

In this case https://test.site/authors displays first page of all items. https://test.site/authors/all/3 will display third page of all items. https://test.site/authors/D will display first page of items beginning with D. And https://test.site/authors/D/3 will display third page of items beginning with D. Initialize your method with default parameters and use them in your code:

public function authors($initial = null, $page =1){
  ....
   $initial = is_null($initial) ? config('bootstrappaginator.valueforall') : $initial;
   $route = 'authors';
   $options = ['nbpages' => 4, 'params' => ['initial' => $initial]];
   $optionalpha = ['type' => 'alpha'];
   $paginator = BootstrapPaginator::init($page, $route, $options);
   $paginatoralpha = BootstrapPaginator::init($initiale, $route, $optionalpha);
   ....
   return view('pages.authors', [
       ...
       'paginator' => $paginator,
       'paginatoralpha' => $paginatoralpha,
       ...
  ]);
}

In this example, numeric paginator will contain current initial in the link urls. Alpha paginator's links will direct web page users to the first page with the initial they contain. Then in the view, print your paginator like this:

{!! $paginator->render() !!}

or simply

{!! $paginator !!}

Parameters

  • $page : current page number or initial letter;
  • $route: current route id;
  • $options : array of values to replace default values in config file:
    • type: either numeric or alpha;
    • params : default []. Array of parameters used by route() helper to issue urls in paginator. See above examples;
    • getparams : default []. GET parameters that will be added to path. Eg: ['search' => 'dummy', 'type' => 'global'] will be translated into url?search=dummy&type=global
    • numeric paginator specific parameters:
      • pageparam : default page. Id of page parameter in route.
      • nbpages: Default 1. Number of pages that will be displayed.
      • withoutdots: default false. Display all pages without spacing ranges by dots;
      • max_pages_without_dots: default 9. Maximum number of pages without dot separation.
      • items_before_after_current: default 2. Number of pages to display before and after page item.
    • alpha paginator specific parameters:
      • initialparam: default initial. Id of initial parameter in route;
      • valueforall : delault all. Value used to display all items instead of items beginnig with a certain parameter.
    • class: default pagination justify-content-center. Class of <ul> surrounding pagination.
    • itemclass: default page-item. Class of <li> element.
    • linkclass: default page-link. Class of <a> element.
    • activelink: default active. Class added to current element.
    • disabledlink: default disabled. Class of disabled button.
    • srcurrent default: <span class="sr-only">(current)</span>- Element added to current element for speech aid tools.
    • previousbuttoncontent: default <span aria-hidden=\"true\">&laquo;</span>. Content for previous button.
    • nextbuttoncontent: default <span aria-hidden=\"true\">&raquo;</span>. Content for next button.

Config files

Config files are available, either in package directory in vendor\seblhaire/bootstrappaginator or in your app config directory if you publish config.

config('bootstrappaginator')

Questions? Contributions?

Feel free to send feature requests or merge request to the author or simply to ask questions.