PaginationEx.HTML (PaginationEx v0.1.0)

HTML helpers for pagination rendering with support for custom templates. Default implementation uses Tailwind CSS.

This module provides functions to generate HTML pagination components for Phoenix applications. It supports:

  • Standard pagination with next/previous links
  • Numbered page links
  • Customization through template modules
  • Internationalization through Gettext
  • Tailwind CSS styling by default

The pagination component is designed to work with data already paginated using PaginationEx.Core and stored in conn.assigns.pagination.

Summary

Functions

build_url(conn, path, page)

Builds a URL for pagination links.

next_path(conn, path, current_page, total_pages)

Generates HTML for the "Next" pagination link.

page_links(conn, path, map)

Generates HTML for numbered page links.

paginate(conn, path, opts \\ [])

Renders pagination controls for the current page.

previous_path(conn, path, current_page)

Generates HTML for the "Previous" pagination link.

translate(text)

Translates text using the configured Gettext module.

Functions

build_url(conn, path, page)

@spec build_url(Plug.Conn.t(), atom() | String.t(), integer()) :: String.t()

Builds a URL for pagination links.

This function handles both router helper functions (atoms) and URL strings, creating a properly formatted link with the page parameter.

Parameters

  • conn - The connection struct
  • path - Either a router helper function name (atom) or a URL string
  • page - The page number to link to

Returns

  • URL string with page parameter

Examples 

iex> PaginationEx.HTML.build_url(conn, :post_path, 2)
"/posts?page=2"

iex> PaginationEx.HTML.build_url(conn, "/posts", 2)
"/posts?page=2"

iex> PaginationEx.HTML.build_url(conn, "/posts?sort=asc", 2)
"/posts?sort=asc&page=2"

next_path(conn, path, current_page, total_pages)

@spec next_path(Plug.Conn.t(), atom() | String.t(), integer(), integer()) ::
  Phoenix.HTML.safe()

Generates HTML for the "Next" pagination link.

Creates either an active link to the next page or a disabled button if the current page is the last page.

Parameters

  • conn - The connection struct
  • path - Either a router helper function name (atom) or a URL string
  • current_page - The current page number
  • total_pages - The total number of pages

Returns

  • HTML markup for the next page link

Examples 

<%= PaginationEx.HTML.next_path(@conn, :post_path, 1, 5) %>

page_links(conn, path, map)

@spec page_links(Plug.Conn.t(), atom() | String.t(), map()) :: [Phoenix.HTML.safe()]

Generates HTML for numbered page links.

Creates a list of links for all pages, with the current page highlighted.

Parameters

  • conn - The connection struct
  • path - Either a router helper function name (atom) or a URL string
  • pagination - A map containing :page_number (current page) and :pages (total pages)

Returns

  • List of HTML markup for page links with interspersed spaces

Examples 

<%= for link <- PaginationEx.HTML.page_links(@conn, :post_path, %{page_number: 2, pages: 5}) do %>
  <%= link %>
<% end %>

paginate(conn, path, opts \\ [])

@spec paginate(Plug.Conn.t(), atom() | String.t(), keyword()) ::
  Phoenix.HTML.safe() | nil

Renders pagination controls for the current page.

This function generates HTML pagination controls for the current page. It uses the pagination data stored in conn.assigns.pagination.

Parameters

  • conn - The connection struct containing pagination data in conn.assigns.pagination
  • path - Either a router helper function name (atom) or a URL string
  • opts - Options for customization (optional)
    • :template_module - A module that implements render_pagination/3 for custom rendering

Returns

  • HTML markup for pagination controls or nil if total entries is less than per_page

Examples 

# Using a path helper
<%= PaginationEx.HTML.paginate(@conn, :post_path) %>

# Using a URL string
<%= PaginationEx.HTML.paginate(@conn, "/posts") %>

# Using a custom template
<%= PaginationEx.HTML.paginate(@conn, :post_path, template_module: MyApp.PaginationTemplate) %>

previous_path(conn, path, current_page)

@spec previous_path(Plug.Conn.t(), atom() | String.t(), integer()) ::
  Phoenix.HTML.safe()

Generates HTML for the "Previous" pagination link.

Creates either an active link to the previous page or a disabled button if the current page is the first page.

Parameters

  • conn - The connection struct
  • path - Either a router helper function name (atom) or a URL string
  • current_page - The current page number

Returns

  • HTML markup for the previous page link

Examples 

<%= PaginationEx.HTML.previous_path(@conn, :post_path, 2) %>

translate(text)

@spec translate(String.t()) :: String.t()

Translates text using the configured Gettext module.

If a Gettext module is configured, the text is passed through gettext for translation. Otherwise, the original text is returned unchanged.

Parameters

  • text - The text to translate

Returns

  • Translated text if a Gettext module is configured, otherwise the original text

Examples 

iex> PaginationEx.HTML.translate("Next")
"Next"

# With configured Gettext module:
iex> PaginationEx.HTML.translate("Next")
"Próximo"  # If the locale is set to Portuguese