Search Documentation

The Pagination Helper

The Trongate framework includes a built-in Pagination class for generating numbered navigation links when displaying multiple pages of content. Below is an example of the pagination output generated by Trongate:

How It Works

Trongate's pagination helper is available for immediate use and can be implemented in three steps:

1. Define Pagination Data - Create an array in the controller.
2. Pass Data to View - Send the pagination data to a view file.
3. Invoke Pagination - Call the pagination helper from the view file.

Defining Pagination Data

The following example demonstrates how to configure pagination data:

The pagination helper does not interact directly with the database. Instead, it uses predefined data from a results set.

Required Properties

The following properties must be included in the $pagination_data array. If any are missing or have an incorrect type, the script will terminate with an error message (e.g., "Pagination Error: Missing required property: total_rows (expected type: int)").

• total_rows: The total number of records available. Type: int

• limit: The maximum number of records per page. Type: int

• record_name_plural: Specifies the plural label for the records. Type: string

Optional Properties

These properties are optional and have default values if not specified. They allow customization of the pagination behavior and appearance.

• page_num_segment: The URL segment number indicating the current page. If not specified (default: null), the last URL segment is used if numeric; otherwise, it defaults to page 1. Type: int

• pagination_root: The base URL for pagination links. If not specified (default: null), it is derived from the current URL, removing the last segment if numeric, and ensuring a trailing slash. Type: string

• include_showing_statement: Determines whether a "Showing x to y of z" statement is displayed above the pagination links. Default: false. Type: bool

• include_css: Determines whether default CSS styles are included in the output as a <style> block. Default: false. If omitted or false, you must style the pagination links yourself. Type: bool

• num_links_per_page: The maximum number of numbered pagination links to display. Default: 10. Links are centered around the current page. Type: int

• settings: An array to customize the HTML structure, labels, and ARIA attributes of pagination links. Default: an empty array ([]), which uses predefined defaults (see "Customizing Pagination with settings"). Type: array

Customizing Pagination with settings

The settings property allows you to override the default appearance and behavior of pagination links. If not provided, the class uses a predefined $default_settings array. You can specify custom values for any of the following keys:

• pagination_open: Opening tag for the pagination container. Default: <div class="pagination">
• pagination_close: Closing tag for the pagination container. Default: </div>
• cur_link_open: Opening tag for the current page link. Default: <a class="active">
• cur_link_close: Closing tag for the current page link. Default: </a>
• num_link_open: Opening tag for numbered links. Default: '' (empty string)
• num_link_close: Closing tag for numbered links. Default: '' (empty string)
• first_link: Text for the "First" button. Default: First
• first_link_open: Opening tag for the "First" button. Default: ''
• first_link_close: Closing tag for the "First" button. Default: ''
• first_link_aria_label: ARIA label for the "First" button. Default: First page
• last_link: Text for the "Last" button. Default: Last
• last_link_open: Opening tag for the "Last" button. Default: ''
• last_link_close: Closing tag for the "Last" button. Default: ''
• last_link_aria_label: ARIA label for the "Last" button. Default: Last page
• prev_link: Text for the "Previous" button. Default: «
• prev_link_open: Opening tag for the "Previous" button. Default: ''
• prev_link_close: Closing tag for the "Previous" button. Default: ''
• prev_link_aria_label: ARIA label for the "Previous" button. Default: Previous page
• next_link: Text for the "Next" button. Default: »
• next_link_open: Opening tag for the "Next" button. Default: ''
• next_link_close: Closing tag for the "Next" button. Default: ''
• next_link_aria_label: ARIA label for the "Next" button. Default: Next page

Example:

If any required keys are missing from your custom settings array, the script will terminate with an error (e.g., "Pagination Error: Missing required settings property: pagination_open").

Default CSS with include_css

When include_css is set to true, the following CSS is injected into the HTML output as a <style> block:

This provides a clean, responsive design with hover effects, an active state, and larger touch targets on mobile devices. If you prefer custom styles, set include_css to false and define your own CSS.

Derived Properties

The Pagination class calculates the following properties automatically and adds them to $pagination_data. These are not set manually but are available for reference:

• root: The full base URL for pagination links (e.g., http://example.com/books/manage/).
• current_page: The current page number (e.g., 2).
• start: The first page number in the link range (e.g., 1).
• end: The last page number in the link range (e.g., 10).
• num_links_to_side: Half of num_links_per_page for link distribution (e.g., 5).
• num_pages: Total number of pages (e.g., ceil(total_rows / limit)).
• prev: Previous page number or empty string if on page 1.
• next: Next page number or last page number if on the last page.
• showing_statement: Text like "Showing 11 to 20 of 100 books." if include_showing_statement is true.

Passing Pagination Data to a View File

The example below demonstrates how to declare and pass pagination data in a controller:

Invoking Pagination from a View File

Once the pagination data has been passed into a view file, pagination elements can be rendered by invoking the display() method:

Mobile-Friendly Pagination

When viewed on smaller screens, pagination components can extend beyond the screen width, leading to usability issues. The default CSS (with include_css set to true) includes a media query for screens under 550px, increasing padding for touch targets. For further customization, consider these approaches:

• Using CSS media queries to hide or modify pagination elements on smaller screens.
• Implementing a simplified mobile format (e.g., "Previous" and "Next" buttons only).
• Using JavaScript to dynamically adjust pagination based on screen width.

Below is an example JavaScript solution for mobile pagination:

The JavaScript code shown above is structured around three main functions:

1. managePagination(): The central function that coordinates everything
   • Sets opacity to 0 during manipulation
   • Checks viewport width and applies the appropriate view
   • Reveals the pagination after changes are complete
2. applyMobileView(): Handles the mobile view (screens < 840px)
   • Adds the "pagination-mobile" class for styling hooks
   • Shows only essential elements: active page, previous («), and next (»)
   • Hides all other pagination links
3. applyDesktopView(): Handles the desktop view (screens ≥ 840px)
   • Removes the "pagination-mobile" class
   • Shows all pagination links

The code also includes debounced resize handling to prevent performance issues during browser resizing.

This approach gives us the best of both worlds - a fully featured pagination on desktop and a simplified, touch-friendly version on mobile, all while maintaining the core functionality of the Trongate framework.

Final Thoughts

Trongate's Pagination class provides a flexible way to add pagination to webpages. Recent enhancements include automatic URL segment detection, customizable settings, and ARIA attributes for accessibility. Whether using the default styles with include_css or tailoring the output with custom settings, the class offers a robust solution for developers.