Paging TagHelper

Sample : Cultures Table

Culture Id English name Native name Two letter ISO language name
1030 Danish (Denmark) dansk (Danmark) da
140 Dari درى prs
1164 Dari (Afghanistan) درى (افغانستان) prs
101 Divehi ދިވެހިބަސް dv
1125 Divehi (Maldives) ދިވެހިބަސް (ދިވެހި ރާއްޖެ) dv
19 Dutch Nederlands nl
2067 Dutch (Belgium) Nederlands (België) nl
1043 Dutch (Netherlands) Nederlands (Nederland) nl
9 English English en
3081 English (Australia) English (Australia) en
38 pages376 records

Minimum settings

Only two parameters is required, total records and current page number. Page size will be set to default value (10).

HTML Code

    <paging total-records="Model.TotalRecords" page-no="Model.PageNo">
    </paging>
Result

Previous-next buttons

Add buttons for Previous and Next buttons

HTML Code

    <paging total-records="Model.TotalRecords"
            page-no="Model.PageNo"
            show-prev-next="true">
    </paging>
Result

First-last buttons

Add buttons for goto First, Last, Previous and Next buttons

  • show-first-last: value is "false" by default, but the butons will show if the total number of pages is larger than the displayed number of pages.
HTML Code

    <paging total-records="Model.TotalRecords"
            page-no="Model.PageNo"
            show-prev-next="true"
            show-first-last="true">
    </paging>
Result

Info badges

Add info badges; total pages and total records

HTML Code

    <paging total-records="Model.TotalRecords"
            page-no="Model.PageNo"
            show-prev-next="true"
            show-total-pages="true"
            show-total-records="true">
    </paging>
Result

Page size dropdown

  • show-page-size-nav: Show/hide navigation dropdown to change page size.
  • page-size: Page size value, should be defined as model property
HTML Code

    <paging total-records="Model.TotalRecords"
            page-no="Model.PageNo"
            show-prev-next="true"
            show-total-pages="true"
            show-total-records="true"
            show-page-size-nav="true"
            page-size="Model.PageSize">
    </paging>
Result
38 pages376 records

First-last numbered pages

Show first and last numbered page when the gap size is more than a specified value.

  • gap-size: The amount of pages between first page and first displayed page, or the amount of pages between last page (total pages) and last displayed page. if the gap size is larger than the specified amount then the most first page (1) or the most last page (total pages) will be displayed.
HTML Code

    <paging total-records="Model.TotalRecords"
            page-no="Model.PageNo"
            page-size="Model.PageSize"
            show-prev-next="true"
            show-total-pages="true"
            show-total-records="true"
            show-page-size-nav="true"
            show-first-numbered-page="true"
            show-last-numbered-page="true"
            gap-size="2">
    </paging>
Result
38 pages376 records

Maximum displayed pages

Change the amount of displayed page numbers.

HTML Code

    <paging total-records="Model.TotalRecords"
            page-no="Model.PageNo"
            page-size="Model.PageSize"
            show-prev-next="true"
            show-total-pages="true"
            show-total-records="true"
            show-page-size-nav="true"
            show-first-numbered-page="true"
            show-last-numbered-page="true"
            gap-size="2"
            max-displayed-pages="3">
    </paging>
Result
38 pages376 records

Query string key names

  • query-string-key-page-no: query string parameter name for current page number.
  • query-string-key-page-size: query string parameter name for page size.
  • query-string-value: the escaped query string with the leading '?', this is important if you have multiple query string parameters such as search filters.

Specify query string key names for page size and current page. Default query string key names are, "p" for current page number and "s" for page size.

HTML Code

    <paging total-records="Model.TotalRecords"
            page-no="Model.PageNo"
            page-size="Model.PageSize"
            show-prev-next="true"
            show-total-pages="true"
            show-total-records="true"
            show-page-size-nav="true"
            show-first-numbered-page="true"
            show-last-numbered-page="true"
            gap-size="2"
            max-displayed-pages="3"
            query-string-key-page-no="p"
            query-string-key-page-size="s"
            query-string-value="@(Request.QueryString.Value)">
    </paging>
Result
38 pages376 records

Page size dropdown navigation options

  • page-size: defines how many items-per-page will be displayed, default page size is 10.
  • page-size-nav-block-size: defines the block size for page size dropdown list values. default value is 10. for accurate result sets this value must be equal to page-size value.
  • page-size-nav-max-items: how many options should be listed in page-size dropdown navigation. each item will be a mutilplier for page-size-nav-block-size value.
HTML Code

    <paging total-records="Model.TotalRecords"
            page-no="Model.PageNo"
            page-size="Model.PageSize"
            show-prev-next="true"
            show-total-pages="true"
            show-total-records="true"
            show-page-size-nav="true"        
            show-first-numbered-page="true"
            show-last-numbered-page="true"
            gap-size="2"
            max-displayed-pages="3"
            query-string-key-page-no="p"
            query-string-key-page-size="s"
            query-string-value="@(Request.QueryString.Value)"
            page-size-nav-block-size="10"
            page-size-nav-max-items="3"
            page-size-nav-on-change="get"
            page-size-nav-form-method="this.form.submit();">
    </paging>
Result
38 pages376 records

Styling

Paging tag helper uses bootstrap 4.1 by default for styling, but you can override all styling classes for the main div and inner html elements.
The default html strcuture for the paging helper is like below:


    <div class="row">
        <div class="col"><!--pagination control--></div>
        <div class="col"><!-- info badges (total pages, total records) --></div>
        <div class="col"><!-- page size dropdown navigation--></div>
    </div>
  • class: The class name for the main div <div class="row">
  • class-paging-control-div: The class name for <div class="col"> that contains the pagination control
  • class-info-div: The class name for <div class="col"> that contains the info badges (total pages, total records)
  • class-page-size-div: The class name for <div class="col"> that contains the pag size dropdown navigation
  • class-active-page: The class name for currently selected page, default: "active".
  • class-disabled-jumping-button: The class name for disabled jumping buttos (go first, last, previous and next buttons), default: "disabled".
  • class-total-pages: The class name for total pages badge, default: "badge badge-light".
  • class-total-records: The class name for total records badge, default: "badge badge-light"
HTML Code

    <paging total-records="Model.TotalRecords"
            page-no="Model.PageNo"
            page-size="Model.PageSize"
            show-prev-next="true"
            show-total-pages="true"
            show-total-records="true"
            show-page-size-nav="true"
            show-first-numbered-page="true"
            show-last-numbered-page="true"
            gap-size="2"
            max-displayed-pages="3"
            query-string-key-page-no="p"
            query-string-key-page-size="s"
            query-string-value="@(Request.QueryString.Value)"
            page-size-nav-block-size="10"
            page-size-nav-max-items="3"
            page-size-nav-on-change="get"
            page-size-nav-form-method="this.form.submit();"
            class="row"
            class-paging-control-div="col"
            class-info-div="col"
            class-page-size-div="col"
            class-paging-control="pagination pagination-lg"
            class-active-page="disabled"
            class-disabled-jumping-button="d-none"
            class-total-pages="badge badge-secondary"
            class-total-records="badge badge-info">
    </paging>
Result
38 pages376 records

Text Localization/Customization

It is possible to localize/customize all texts for info badges (total records, total pages), page size dropdown text (items per page) and jumping buttons (goto first, last, previous and next buttons). Override the below values to have your own values shown:

  • text-page-size: Display text for page size dropdown navigation. default: "Show"
  • text-total-pages: Display text for total pages, this text will appear right after the number e.g. 25 pages
  • text-total-records: Display text for total records, this text will appear right after the number e.g. 156 records
  • text-first: Display text for goto first page button, default: &laquo; («)
  • text-last: Display text for goto last page button, default: &raquo; (»)
  • text-previous: Display text for goto previous page button, default: &lsaquo; (‹)
  • text-next: Display text for goto next page button, default: &rsaquo; (›)
HTML Code

    <paging total-records="Model.TotalRecords"
            page-no="Model.PageNo"
            page-size="Model.PageSize"
            show-prev-next="true"
            show-total-pages="true"
            show-total-records="true"
            show-page-size-nav="true"
            show-first-numbered-page="true"
            show-last-numbered-page="true"
            gap-size="2"
            max-displayed-pages="3"
            query-string-key-page-no="p"
            query-string-key-page-size="s"
            query-string-value="@(Request.QueryString.Value)"
            page-size-nav-block-size="10"
            page-size-nav-max-items="3"
            page-size-nav-on-change="get"
            page-size-nav-form-method="this.form.submit();"
            class="row"
            class-paging-control-div="col"
            class-info-div="col"
            class-page-size-div="col"
            class-paging-control="pagination"
            class-active-page="disabled"
            class-disabled-jumping-button="disabled"
            class-total-pages="badge badge-secondary"
            class-total-records="badge badge-info"
            text-page-size="@Localizer.Text("Items per page")"
            text-total-pages="@Localizer.Text("pages")"
            text-total-records="@Localizer.Text("records")"
            text-first="@Localizer.Text("First")"
            text-last="@Localizer.Text("Last")"
            text-previous="@Localizer.Text("Previous")"
            text-next="@Localizer.Text("Next")>
    </paging>

Notices:

  1. This sample is based on localization using shared resource files.
    Read more about localization in these articles: Developing Multicultural Web Application
  2. To see localized texts on the below paging control try changing the language from the top navigation bar :)
Result
38 Microsoft.AspNetCore.Mvc.Localization.LocalizedHtmlString376 Microsoft.AspNetCore.Mvc.Localization.LocalizedHtmlString

Screen readers

It is important to provide text values for screen readers when using icons on the buttons, so the screen reader can read that value. The four jumping buttons can have values for screen readers as below:

  • sr-text-first: Screen reader text for goto first page button, default: "First"
  • sr-text-last: Screen reader text for goto last page button, default: "Last"
  • sr-text-previous: Screen reader text for goto previous page button, default: "Previous"
  • text-next-sr: Screen reader text for goto next page button, default: "Next"
HTML Code

    <paging total-records="Model.TotalRecords"
            page-no="Model.PageNo"
            page-size="Model.PageSize"
            show-prev-next="true"
            show-total-pages="true"
            show-total-records="true"
            show-page-size-nav="true"
            show-first-numbered-page="true"
            show-last-numbered-page="true"
            gap-size="2"
            max-displayed-pages="3"
            query-string-key-page-no="p"
            query-string-key-page-size="s"
            query-string-value="@(Request.QueryString.Value)"
            page-size-nav-block-size="10"
            page-size-nav-max-items="3"
            page-size-nav-on-change="get"
            page-size-nav-form-method="this.form.submit();"
            class="row"
            class-paging-control-div="col"
            class-info-div="col"
            class-page-size-div="col"
            class-paging-control="pagination"
            class-active-page="disabled"
            class-disabled-jumping-button="disabled"
            class-total-pages="badge badge-secondary"
            class-total-records="badge badge-info"
            text-page-size="Items per page:"
            text-total-pages="pages"
            text-total-records="records"
            text-first="&laquo;"
            text-last="&raquo;"
            text-previous="&lsaquo;"
            text-next="&rsaquo;"
            sr-text-first="First"
            sr-text-last="Last"
            sr-text-previous="Previous"
            sr-text-next="Next">
    </paging>
Result
38 pages376 records

Json Settings

All default settings can be overrided in appsettings.json file and it will affect all paging tag helpers in the application. Any settings defined inside the tag helper will override the default and json settings.

the default json settings can be overrided in appSettings.json, below is a full list of all settings in json format:


{
    "lazziya": {
        "pagingTagHelper": {
          "default": {
            "page-no": 1,
            "page-size": 10,
            "total-records": 0,
            "max-displayed-pages": 10,
            "gap-size": 3,
            "page-size-nav-form-method": "get",
            "page-size-nav-on-change": "this.form.submit();",
            "page-size-nav-block-size": 10,
            "page-size-nav-max-items": 5,
            "query-string-key-page-no": "p",
            "query-string-key-page-size": "s",
            "query-string-value": "",
            "show-first-last": false,
            "show-prev-next": false,
            "show-page-size-nav": false,
            "show-total-pages": false,
            "show-total-records": false,
            "show-first-numbered-page": false,
            "show-last-numbered-page": false,
            "text-page-size": "Items per page",
            "text-first": "«",
            "text-last": "»",
            "text-previous": "‹",
            "text-next": "›",
            "text-total-pages": "pages",
            "text-total-records": "records",
            "sr-text-first": "First",
            "sr-text-last": "Last",
            "sr-text-previous": "Previous",
            "sr-text-next": "Next",
            "class": "row",
            "class-info-div": "col",
            "class-page-size-div": "col",
            "class-paging-control-div": "col",
            "class-paging-control": "pagination",
            "class-active-page": "active",
            "class-disabled-jumping-button": "disabled",
            "class-total-pages": "badge badge-secondary",
            "class-total-records": "badge badge-info"
          }
        }
    }
}

More than one settings collection can be defined inside appSettings.json file, so each paging helper element can read settings from different collection.

it is not necessary to override all the settings inside json file, it is possible to mention only the settings we want to override.

e.g. below there is two settings collections "basic" and "custom", each can be applied to different set of paging helpers inside your application.


{
    "lazziya": {
        "pagingTagHelper": {
            "basic": {
                "show-first-last": true,
                "max-displayed-pages": 7,
                "class-active-aage": "disabled"
              },
              "custom": {
                "show-first-last": true,
                "show-prev-next": true,
                "show-first-numbered-page": true,
                "show-last-numbered-page": true,
                "max-displayed-pages": 2,
                "text-first": "go first",
                "text-last": "go last",
                "text-previous": "one step back",
                "text-next": "one step forward",
                "class-paging-control": "pagination pagination-lg"
              }
        }
    }
}
HTML Code

    <!-- basic settings -->
    <paging total-records="Model.TotalRecords"
            page-no="Model.PageNo"
            settings-json="basic">
    </paging>

    <!-- custom settings -->
    <paging total-records="Model.TotalRecords"
            page-no="Model.PageNo"
            settings-json="custom">
    </paging>
Result for "basic" settings
Result for "custom" settings