View Source Pageantry.Input (Pageantry v0.5.2)

User input for paging/sorting/filtering.

Fields

  • off : Page offset start; 0 to start with the first item.
  • max : Maximum items per page, eg 10.
  • sort : Keyword list of fields to sort by, eg [asc: :name, desc: :created].
  • filter : Keyword list of fields to filter by, eg [name: "foo", active: true]. ALL is a special field that means filter across all fields, eg [ALL: "today"].

Summary

Functions

Adds filter parameter to map of paging params.

Adds items-per-page parameter to map of paging params.

Adds offset parameter to map of paging params.

Adds paging to existing params map.

Adds sort parameter to map of paging params.

Creates new Input struct.

Creates new Input struct.

Parses request parameters into Input struct.

Parses request parameters into Input struct with defaults.

Extracts "field" and "q" parameters as filter keyword list.

Extracts "max" parameter as positive integer.

Extracts "off" parameter as non-negative integer.

Extracts "sort" parameter as sort keyword list.

Builds paging params map.

Builds URL with paging params in query string.

Types

@type t() :: %Pageantry.Input{
  filter: keyword(atom()),
  max: integer(),
  off: integer(),
  sort: keyword(atom())
}

Functions

Link to this function

add_filter_param(params, map)

View Source
@spec add_filter_param(map(), t()) :: map()

Adds filter parameter to map of paging params.

Examples

iex> import Pageantry.Input
iex> alias Pageantry.Input
iex> add_filter_param(%{}, %Input{filter: [created: "today"]})
%{"field" => "created", "q" => "today"}
iex> add_filter_param(%{}, %Input{filter: [ALL: "today"]})
%{"q" => "today"}
iex> add_filter_param(%{}, %Input{})
%{}
Link to this function

add_max_param(params, map, default_max)

View Source
@spec add_max_param(map(), t(), integer()) :: map()

Adds items-per-page parameter to map of paging params.

Examples

iex> import Pageantry.Input
iex> alias Pageantry.Input
iex> add_max_param(%{}, %Input{max: 100}, 10)
%{"max" => "100"}
iex> add_max_param(%{}, %Input{max: 100}, 100)
%{}
Link to this function

add_off_param(params, map)

View Source
@spec add_off_param(map(), t()) :: map()

Adds offset parameter to map of paging params.

Examples

iex> import Pageantry.Input
iex> alias Pageantry.Input
iex> add_off_param(%{}, %Input{off: 10})
%{"off" => "10"}
iex> add_off_param(%{}, %Input{off: 0})
%{}
Link to this function

add_params(params, input, default_max \\ 10)

View Source
@spec add_params(map(), t(), integer()) :: map()

Adds paging to existing params map.

Examples

iex> import Pageantry.Input
iex> alias Pageantry.Input
iex> add_params(%{}, %Input{off: 10, max: 20, sort: [asc: :name], filter: [ALL: "today"]})
%{"max" => "20", "off" => "10", "q" => "today", "sort" => "name"}
iex> add_params(%{}, %Input{})
%{}
Link to this function

add_sort_param(params, map)

View Source
@spec add_sort_param(map(), t()) :: map()

Adds sort parameter to map of paging params.

Examples

iex> import Pageantry.Input
iex> alias Pageantry.Input
iex> add_sort_param(%{}, %Input{sort: [asc: :name]})
%{"sort" => "name"}
iex> add_sort_param(%{}, %Input{sort: [desc: :name]})
%{"sort" => "-name"}
iex> add_sort_param(%{}, %Input{})
%{}
@spec new(integer()) :: t()

Creates new Input struct.

Examples

iex> import Pageantry.Input
iex> new(100)
%Pageantry.Input{off: 0, max: 100, sort: [], filter: []}
Link to this function

new(max, sort \\ [], filter)

View Source
@spec new(integer(), keyword(), keyword()) :: t()

Creates new Input struct.

Examples

iex> import Pageantry.Input
iex> new(100, [desc: :created], [created: "today"])
%Pageantry.Input{off: 0, max: 100, sort: [desc: :created], filter: [created: "today"]}
Link to this function

parse(params, prefs \\ %Prefs{})

View Source
@spec parse(map(), Pageantry.Prefs.t()) :: t()

Parses request parameters into Input struct.

Examples

iex> import Pageantry.Input
iex> parse(%{"off" => "100"})
%Pageantry.Input{off: 100, max: 10, sort: [], filter: []}
iex> parse(%{"sort" => "name-created", "q" => "today"})
%Pageantry.Input{off: 0, max: 10, sort: [asc: :name, desc: :created], filter: [ALL: "today"]}
Link to this function

parse(input, params, prefs)

View Source
@spec parse(t(), map(), Pageantry.Prefs.t()) :: t()

Parses request parameters into Input struct with defaults.

Examples

iex> import Pageantry.Input
iex> parse(%Pageantry.Input{max: 20}, %{"off" => "100"}, %Pageantry.Prefs{})
%Pageantry.Input{off: 100, max: 20, sort: [], filter: []}
iex> input = %Pageantry.Input{max: 20, sort: [desc: :created]}
iex> params = %{"max" => "100", "field" => "name", "q" => "foo"}
iex> parse(input, params, %Pageantry.Prefs{})
%Pageantry.Input{off: 0, max: 100, sort: [desc: :created], filter: [name: "foo"]}
Link to this function

parse_filter(params, default \\ [], prefs \\ %Prefs{})

View Source
@spec parse_filter(map(), keyword(String.t()), Pageantry.Prefs.t()) ::
  keyword(String.t())

Extracts "field" and "q" parameters as filter keyword list.

Examples

iex> import Pageantry.Input
iex> parse_filter(%{"field" => "created", "q" => "today"})
[created: "today"]
iex> parse_filter(%{"q" => "today"})
[ALL: "today"]
iex> parse_filter(%{"q" => ""})
[]
Link to this function

parse_max(params, default \\ 10, prefs \\ %Prefs{})

View Source
@spec parse_max(map(), integer(), Pageantry.Prefs.t()) :: integer()

Extracts "max" parameter as positive integer.

Examples

iex> import Pageantry.Input
iex> parse_max(%{"max" => "100"})
100
iex> parse_max(%{"max" => ""}, 10)
10
Link to this function

parse_off(params, default \\ 0, prefs \\ %Prefs{})

View Source
@spec parse_off(map(), integer(), Pageantry.Prefs.t()) :: integer()

Extracts "off" parameter as non-negative integer.

Examples

iex> import Pageantry.Input
iex> parse_off(%{"off" => "100"})
100
iex> parse_off(%{"off" => ""})
0
Link to this function

parse_sort(params, default \\ [], prefs \\ %Prefs{})

View Source
@spec parse_sort(map(), keyword(atom()), Pageantry.Prefs.t()) :: keyword(atom())

Extracts "sort" parameter as sort keyword list.

Examples

iex> import Pageantry.Input
iex> parse_sort(%{"sort" => "name"})
[asc: :name]
iex> parse_sort(%{"sort" => "-name"})
[desc: :name]
iex> parse_sort(%{"sort" => ""})
[]
Link to this function

to_params(input, default_max \\ 10)

View Source
@spec to_params(t(), integer()) :: map()

Builds paging params map.

Examples

iex> import Pageantry.Input
iex> alias Pageantry.Input
iex> to_params(%Input{off: 10, max: 20, sort: [asc: :name], filter: [ALL: "today"]})
%{"max" => "20", "off" => "10", "q" => "today", "sort" => "name"}
iex> to_params(%Input{})
%{}
Link to this function

to_url(input, default_max \\ 10)

View Source
@spec to_url(t(), integer()) :: String.t()

Builds URL with paging params in query string.

Examples

iex> import Pageantry.Input
iex> alias Pageantry.Input
iex> to_url(%Input{off: 10, max: 20, sort: [asc: :name], filter: [ALL: "today"]})
"?max=20&off=10&q=today&sort=name"
iex> to_url(%Input{})
""