# flask-paginate 2024.4.12 documentation

## Overview

Latest version: 2024.04.12

flask-paginate is a simple paginate extension for flask which is reference to will_paginate, and supports several css frameworks.

2024.04.12 update: fix bug url not unquoted for bulma

2024.03.28 update: include_first_page_number parameter was added, and some parameters got from config

2023.10.24 update: rel parameters was added

2021.10.26 update: bootstrap5 is now supported

0.6.0 update: bulma is now supported (use css_framework parameter):

    pagination = Pagination(..., css_framework='bulma', **kwargs)

0.5.4 update: `semantic`_ is now supported (use css_framework parameter):

    pagination = Pagination(..., css_framework='semantic', **kwargs)

0.2 update: foundation is now supported (use css_framework parameter):

    pagination = Pagination(..., css_framework='foundation', **kwargs)

Note: Python 2.6+ is required (string.format is used to format text)

    {{ pagination.info }}

or

    {{ pagination.links }}

## Installation

Install the extension with one of the following commands:

    $ easy_install -U flask-paginate

or alternatively if you have pip installed:

    $ pip install -U flask-paginate

## Configuration

If you want to show the pagination information, add below lines to your css file.

    .pagination-page-info {
        padding: .6em;
        padding-left: 0;
        width: 40em;
        margin: .5em;
        margin-left: 0;
        font-size: 12px;
    }
    .pagination-page-info b {
        color: black;
        background: #6aa6ed;
        padding-left: 2px;
        padding: .1em .25em;
        font-size: 150%;
    }

## Test

Test file was added in 0.4.6 (thanks to Rdbaker):

    $ pip install -r test-requirements.txt
    $ cd tests
    $ pytest tests.py

## How to use

In your flask views file (e.g. views/users.py):

    from flask import Blueprint
    from flask_paginate import Pagination, get_page_parameter

    mod = Blueprint('users', __name__)

    @mod.route('/')
    def index():
        search = False
        q = request.args.get('q')
        if q:
            search = True

        page = request.args.get(get_page_parameter(), type=int, default=1)

        users = User.find(...)
        pagination = Pagination(page=page, total=users.count(), search=search, record_name='users')
        # 'page' is the default name of the page parameter, it can be customized
        # e.g. Pagination(page_parameter='p', ...)
        # or set PAGE_PARAMETER in config file
        # also likes page_parameter, you can customize for per_page_parameter
        # you can set PER_PAGE parameter in config file
        # e.g. Pagination(per_page_parameter='pp')

        return render_template(
            "index.html",
            users=users,
            pagination=pagination,
        )

In the users/index.html:

    {{ pagination.info }}
    {{ pagination.links }}
    <table>
      <thead>
        <tr>
          <th>#</th>
          <th>Name</th>
          <th>Email</th>
        </tr>
      </thead>
      <tbody>
        {% for user in users %}
          <tr>
            <td>{{ loop.index + pagination.skip }}</td>
            <td>{{ user.name }}</td>
            <td>{{ user.email }}</td>
          </tr>
        {% endfor %}
      </tbody>
    </table>
    {{ pagination.links }}

## Example

Note: 0.2.9 requires click to run this example.

    $cd example
    $python sql.py --help
    $python sql.py init-db
    $python sql.py fill-data --total=300
    $cp app.cfg.example app.cfg
    $echo edit app.cfg
    $python app.py --port 5000

Open http://localhost:5000 to see the example page.

## Deep into the Pagination

Below are the parameters for Pagination.__init__(). You can change the settings here.

> found: used when searching

> page: current page

> per_page: how many records to display on one page

> page_parameter: a name(string) of a GET parameter that holds a page index. Use it if you want to iterate over multiple Pagination objects simultaneously. defautl is ‘page’.

> per_page_parameter: a name for per_page likes page_parameter. default is ‘per_page’.

> inner_window: how many links arround current page

> outer_window: how many links near first/last link

> prev_label: text for previous page, default is ‘&laquo;’

> next_label: text for next page, default is ‘&raquo;’

> search: search or not?

> total: total records for pagination

> display_msg: text for pagation information

> search_msg: text for search information

> record_name: record name shown in pagination information

> link_size: font size of page links

> alignment: the alignment of pagination links

> href: Add custom href for links - this supports forms with post method. MUST contain {0} to format page number

> show_single_page: decide whether or not a single page returns pagination

> bs_version: the version of bootstrap, default is 4

> css_framework: the css framework, default is ‘bootstrap4’

> anchor: anchor parameter, appends to page href

> format_total: number format total, like 1,234, default is False

> format_number: number format start and end, like 1,234, default is False

> url_coding: coding for url encoding, default is utf-8

> bulma_style: page link style for bulma css framework

> prev_rel: rel of previous page

> next_rel: rel of next page

> include_first_page_number: show first page number or not

## API

class flask_paginate.Pagination(found=0, **kwargs)

  A simple pagination extension for flask.

  property info

    Get the pagination information.

  property links

    Get all the pagination links.

## Contributors

- AlessandroPoletti

- DYFeng

- DoctorMalboro

- MasterMind2k

- Rdbaker

- alcaras

- andodet

- dp92987

- ilya-il

- mkaplenko

- mozillazg

- skybber

- tark-hidden

- trein

- voltterra

- wong2

## Changelog

## Version 2024.04.12

- fix a bug url not unquoted for bulma issue 112 <https://github.com/lixxu/flask-paginate/issues/112>

## Version 2024.03.28

- add include_first_page_number issue 111 <https://github.com/lixxu/flask-paginate/issues/111>

- some parameters got from config

## Version 2023.10.24

- add rel issue 109 <https://github.com/lixxu/flask-paginate/issues/109>

## Version 2023.10.08

- fix typos PR 104 <https://github.com/lixxu/flask-paginate/pull/104>

## Version 2022.01.08

- make bs_version only for bootstrap

## Version 2021.12.28

- set bs_version to integer

## Version 2021.10.29

- bs_version is from css_framework if css_framework was set

## Version 2021.10.26

- Add bootstrap5 support

- use YYYY.mm.dd format for version number

- Add type conversion for page and per_page args: issue 90

## Version 0.8.0

- fix bug: issue 87

- fix bug: issue 89

- jump to new version due to upload to pypi by mistake.

## Version 0.7.1

- fix bug: issue 76

## Version 0.7.0

- Support Materialize framework

## Version 0.6.0

- support for bulma css framework

- use black for code format

## Version 0.5.5

- add option for url encoding or not

## Version 0.5.4

- support for SemanticUI

## Version 0.5.3

- update for bootstrp 3.3

## Version 0.5.2

- add skip attribute to fix error in docs

- read version from source file instead of hard code in setup file

## Version 0.5.1

- add bootstrap4 support

## Version 0.5.0

- Make clear and easy customized for page/per_page parameter per on issue 50

- add get_page_parameter and get_per_page_parameter for customization

## Version 0.4.6

(bug fix release, released on May 31th 2017)

- bug fix: - Incorrect right-most window value on outer_window=0 issue 51

- add tests file

## Version 0.4.5

Added new parameter page_parameter to simultaneously interate over multiple Pagination objects. See documentation

## Version 0.4.4

bug fix: - TypeError: url_for() got multiple values for keyword argument ‘page’ issue 47

## Version 0.4.3

use flask_paginate insetad of flask.ext.paginate for new version of flask

## Version 0.4.2

add get_page_args() function, and change the way to get url args

## Version 0.4.1

remove href for disabled links to prevent navigating to top of page when clicks

## Version 0.3.2

0.3.1 file upload failed, increase the version number.

## Version 0.3.1

(bug fix release, released on Apr 18th 2015)

- URL has no necessary to unquote for links issue 26

## Version 0.3.0

(small feature release, released on Apr 14th 2015)

- Add option to number format total issue 29, and also can format start and end

## Version 0.2.9

(bugfix release, released on Apr 13th 2015)

- Last release did not fix the bug bug 24 actually. Thanks MasterMind2k fix it finally.

- Use click for example code

## Version 0.2.8

(bugfix release, released on Nov 2nd 2014)

- Flat args for non-multi values style urls. This is used to fix the bug https://github.com/lixxu/flask-paginate/issues/24 when generated url likes this (http://xxxxxx/something/[u’param’]?page=2)

- Use http://flask.pocoo.org/docs/0.10/api/#flask.Markup when generating url so that template no need to use safe filter any more.