zf v0.5.0 Zf.Pagination

For use with Phoenix.HTML, configure the :routes_helper module like the following:

config :zf,
  routes_helper: MyApp.Router.Helpers

Import to you view.

defmodule MyApp.UserView do
  use MyApp.Web, :view
  use Zf.Pagination
end

Use in your template.

<%= zf_pagination @conn, @page %>

Where @page is a %Scrivener.Page{} struct returned from Repo.paginate/2.

Customize output. Below are the defaults.

<%= zf_pagination @conn, @page, distance: 5, next: ">>", previous: "<<", first: true, last: true %>

See Zf.Pagination.raw_pagination/2 for option descriptions.

For custom HTML output, see Zf.Pagination.raw_pagination/2.

For SEO related functions, see Zf.Pagination.SEO (these are automatically imported).

Link to this section Summary

Functions

defaults()

find_path_fn(entries, path_args)

raw_pagination(paginator, options \\ [])

Returns the raw data in order to generate the proper HTML for pagination links. Data is returned in a {text, page_number} format where text is intended to be the text of the link and page_number is the page it should go to. Defaults are already supplied and they are as follows

zf_pagination(paginator)

zf_pagination(paginator, opts)

zf_pagination(conn, paginator, opts)

zf_pagination(conn, paginator, args, opts)

Generates the HTML pagination links for a given paginator returned by Scrivener.

Link to this section Functions

defaults()

find_path_fn(entries, path_args)

raw_pagination(paginator, options \\ [])

[distance: 5, next: ">>", previous: "<<", first: true, last: true, ellipsis: {:safe, "&hellip;"}]

distance must be a positive non-zero integer or an exception is raised. next and previous should be strings but can be anything you want as long as it is truthy, falsey values will remove them from the output. first and last are only booleans, and they just include/remove their respective link from output. An example of the data returned:

iex> Zf.Pagination.raw_pagination(%{total_pages: 10, page_number: 5})
[{"<<", 4}, {1, 1}, {2, 2}, {3, 3}, {4, 4}, {5, 5}, {6, 6}, {7, 7}, {8, 8}, {9, 9}, {10, 10}, {">>", 6}]
iex> Zf.Pagination.raw_pagination(%{total_pages: 20, page_number: 10}, first: ["←"], last: ["→"])
[{"<<", 9}, {["←"], 1}, {:ellipsis, {:safe, "&hellip;"}}, {5, 5}, {6, 6},{7, 7}, {8, 8}, {9, 9}, {10, 10}, {11, 11}, {12, 12}, {13, 13}, {14, 14},{15, 15}, {:ellipsis, {:safe, "&hellip;"}}, {["→"], 20}, {">>", 11}]

Simply loop and pattern match over each item and transform it to your custom HTML.

zf_pagination(paginator)

zf_pagination(paginator, opts)

zf_pagination(conn, paginator, opts)

zf_pagination(conn, paginator, args, opts)

Generates the HTML pagination links for a given paginator returned by Scrivener.

The default options are:

#{inspect @defaults}

In order to generate links with nested objects (such as a list of comments for a given post) it is necessary to pass those arguments. All arguments in the args parameter will be directly passed to the path helper function. Everything within opts which are not options will passed as params to the path helper function. For example, @post, which has an index of paginated @comments would look like the following:

Zf.Pagination.zf_pagination(@conn, @comments, [@post], my_param: "foo")

You'll need to be sure to configure :zf with the :routes_helper module (ex. MyApp.Routes.Helpers) in Phoenix. With that configured, the above would generate calls to the post_comment_path(@conn, :index, @post.id, my_param: "foo", page: page) for each page link.

In times that it is necessary to override the automatic path function resolution, you may supply the correct path function to use by adding an extra key in the opts parameter of :path. For example:

Zf.Pagination.zf_pagination(@conn, @comments, [@post], path: &post_comment_path/4)

Be sure to supply the function which accepts query string parameters (starts at arity 3, +1 for each relation), because the page parameter will always be supplied. If you supply the wrong function you will receive a function undefined exception.