scrivener v0.8.0 → Overview → Scrivener

Scrivener

Scrivener allows you to paginate your Ecto queries. It gives you useful information such as the total number of pages, the current page, and the current page’s entries. It works nicely with Phoenix as well.

First, you’ll want to use Scrivener in your application’s Repo. This will add a paginate function to your Repo. This paginate function expects to be called with, at a minimum, an Ecto query. It will then paginate the query and execute it, returning a Scrivener.Page. Defaults for page_size can be configued when you use Scrivener. If no page_size is provided, Scrivener will use 10 by default.

You may also want to call paginate with a params map along with your query. If provided with a params map, Scrivener will use the values in the keys "page" and "page_size" before using any configured defaults.

defmodule MyApp.Repo do
  use Ecto.Repo, otp_app: :my_app
  use Scrivener, page_size: 10
end

defmodule MyApp.Person do
  use Ecto.Model

  schema "people" do
    field :name, :string
    field :age, :integer

    has_many :friends, MyApp.Person
  end
end

def index(conn, params) do
  page = MyApp.Person
  |> where([p], p.age > 30)
  |> order_by([p], desc: p.age)
  |> preload(:friends)
  |> MyApp.Repo.paginate(params)

  render conn, :index,
    people: page.entries,
    page_number: page.page_number,
    page_size: page.page_size,
    total_pages: page.total_pages,
    total_entries: page.total_entries
end

page = MyApp.Person
|> where([p], p.age > 30)
|> order_by([p], desc: p.age)
|> preload(:friends)
|> MyApp.Repo.paginate(page: 2, page_size: 5)

Summary↑

__using__(opts)

Scrivener is meant to be used by an Ecto repository. When used, an optional default for page_size can be provided. If page_size is not provided a default of 10 will be used
paginate(query, config)

The paginate function can also be called with a Scrivener.Config for more fine-grained configuration. In this case, it is called directly on the Scrivener module
paginate(repo, defaults, query, opts)

This method is not meant to be called directly, but rather will be delegated to by calling paginate/2 on the repository that uses Scrivener

Functions

paginate(query, config)
(function) # ↑

Specs:

The paginate function can also be called with a Scrivener.Config for more fine-grained configuration. In this case, it is called directly on the Scrivener module.

config = %Scrivener.Config{
  page_size: 5,
  page_number: 2,
  repo: MyApp.Repo
}

MyApp.Model
|> where([m], m.field == "value")
|> Scrivener.paginate(config)
paginate(repo, defaults, query, opts)
(function) # ↑

Specs:

This method is not meant to be called directly, but rather will be delegated to by calling paginate/2 on the repository that uses Scrivener.

defmodule MyApp.Repo do
  use Ecto.Repo, ...
  use Scrivener
end

MyApp.Model |> where([m], m.field == "value") |> MyApp.Repo.paginate

When calling your repo’s paginate function, you may optionally specify page and page_size. These values can be specified either as a Keyword or map. The values should be integers or string representations of integers.

MyApp.Model |> where([m], m.field == "value") |> MyApp.Repo.paginate(page: 2, page_size: 10)

MyApp.Model |> where([m], m.field == "value") |> MyApp.Repo.paginate(%{"page" => "2", "page_size" => "10"})

The ability to call paginate with a map with string key/values is convenient because you can pass your Phoenix params map to paginate.

Macros

__using__(opts)
(macro) # ↑

Scrivener is meant to be used by an Ecto repository. When used, an optional default for page_size can be provided. If page_size is not provided a default of 10 will be used.

defmodule MyApp.Repo do
  use Ecto.Repo, ...
  use Scrivener
end

defmodule MyApp.Repo do
  use Ecto.Repo, ...
  use Scrivener, page_size: 5
end

When use is called a paginate function is defined in the Ecto repo. See the paginate documentation for more information.