Pagination.Paginator (simple_pagination v0.2.0)

This module provides live pagination for a given query.

It is paired with helper components used to organize and present large sets of data in a user-friendly way. It also provides a mechanism for dividing data into smaller, more manageable chunks or pages and allows users to navigate through these pages using a set of controls such as "next page", "previous page," and page numbers.

In addition to pagination, this module offers features such as sorting, filtering, and search capabilities, allowing users to further refine and customize the data they see.

Here's a sample index.html.heex:

  <.search_filter_tag paginator={@things} label="Find" />
  <.page_tag paginator={@things} delta={1} />
  <table>
    <thead>
      <tr>
        <td style="width:15%"><.order_tag label="id" order_by={:id} paginator={@things} /></td>
        <td style="width:85%"><.order_tag label="title" order_by={:title} paginator={@things} /></td>
      </tr>
    </thead>
  <%= for t <- @things.data do %>
    <tr>
      <td><%= t.id %></td>
      <td><%= t.title %></td>
    </tr>
  <% end %>
  </table>

@things is a Pagination.PaginatorState that includes pagination parameters and the resulting dataset.

Do note that you can place filters_tag, page_tag and order_tag pretty much anywhere in your page code.

All changes are handled via event. The paginate event must be handled in index.ex

  def mount(params, _session, socket),
    do: {:ok, assign(socket, things: Things.paginate(params))}

  def handle_event("paginate" = event, params, socket),
    do: {:noreply, assign(socket, things: Things.paginate(socket.assigns.things, params))}

The Things context is the place where the initial query is fed to the paginator:any()

  def paginate(
        attrs,
        %PaginatorState{} = pg \ %PaginatorState{
          filters: [title: ""],
          per_page_items: [5, 25, 0],
          order_by: {:asc, :title}
        }
      ) do
    list_things_query()
    |> maybe_apply_advanced_filtering(attrs)
    |> Pagination.Paginator.paginate(Pagination.Paginator.change(pg, attrs))
  end

Check the Pagination.PaginatorState structure for more details about pagination parameters. If complex filtering is required, create and add maybe_apply_advanced_filtering/2 and refine the query as needed.

Link to this section Summary

Functions

Updates the PaginatorState using given data to change order, page and filters.

This function paginates and filters the given query and returns an updated Pagination.PaginatorState.

Link to this section Functions

Link to this function

change(pg, attrs)

Updates the PaginatorState using given data to change order, page and filters.

attrs is a map.

Link to this function

paginate(query, pg, repo)

This function paginates and filters the given query and returns an updated Pagination.PaginatorState.

repo is your application Ecto.Repo.

Please note that you can add your own pagination extensions or complex filters by modifying the query before feeding it to paginate/3.

list_things_query()
|> apply_my_own_filters(pg_or_my_own_attributes)
|> Pagination.Paginator.paginate(pg, Repo)