Rummage.Ecto v2.0.0 Rummage.Ecto.CustomHook.SimpleSort View Source

Rummage.Ecto.CustomHook.SimpleSort is the default sort hook that comes with Rummage.Ecto.

This module provides a operations that can add sorting functionality to a pipeline of Ecto queries. This module works by taking the field that should be used to order_by, order which can be asc or desc.

This module doesn't support associations and hence is a simple alternative to Rummage's default search hook.

NOTE: This module doesn't return a list of entries, but a Ecto.Query.t. This module uses Rummage.Ecto.Hook.

ABOUT:

Arguments:

This Hook expects a queryable (an Ecto.Queryable) and sort_params (a Map). The map should be in the format: %{field: :field_name, order: :asc}

Details:

field: The field name (atom) to sorted by.
order: Specifies the type of order asc or desc.
ci : Case Insensitivity. Defaults to false

For example, if we want to sort products with descending price, we would do the following:

Rummage.Ecto.CustomHook.SimpleSort.run(Product, %{field: :price,
  order: :desc})

Assoications:

This module doesn't support assocations.

ASSUMPTIONS/NOTES:

This Hook has the default order of :asc.
This Hook assumes that the searched field is a part of the schema passed as the queryable.

USAGE:

For a regular sort:

This returns a queryable which upon running will give a list of Parent(s) sorted by ascending field_1

alias Rummage.Ecto.CustomHook.SimpleSort

sorted_queryable = SimpleSort.run(Parent, %{field: :name, order: :asc}})

For a case-insensitive sort:

This returns a queryable which upon running will give a list of Parent(s) sorted by ascending case insensitive field_1.

Keep in mind that case_insensitive can only be called for text fields

alias Rummage.Ecto.CustomHook.SimpleSort

sorted_queryable = SimpleSort.run(Parent, %{field: :name, order: :asc, ci: true}})

This module can be overridden with a custom module while using Rummage.Ecto in Ecto struct module.

In the Ecto module:

Rummage.Ecto.rummage(queryable, rummage, sort: CustomHook)

Globally for all models in config.exs:

config :rummage_ecto,
  Rummage.Ecto,
  sort: CustomHook

The CustomHook must use Rummage.Ecto.Hook. For examples of CustomHook, check out some custom_hooks that are shipped with Rummage.Ecto: Rummage.Ecto.CustomHook.SimpleSearch, Rummage.Ecto.CustomHook.SimpleSort, Rummage.Ecto.CustomHook.SimplePaginate

Link to this section Summary

Functions

format_params(queryable, params, opts)

Callback implementation for Rummage.Ecto.Hook.format_params/3.

run(queryable, params)

This is the callback implementation of Rummage.Ecto.Hook.run/2.

Link to this section Functions

format_params(queryable, params, opts)

Specs

format_params(Ecto.Query.t(), map(), keyword()) :: map()

format_params(Ecto.Query.t(), map(), keyword()) :: map()

Callback implementation for Rummage.Ecto.Hook.format_params/3.

This function ensures that params for each field have keys assoc, order1 which are essential for running this hook module.

Examples

iex> alias Rummage.Ecto.CustomHook.SimpleSort
iex> SimpleSort.format_params(Parent, %{}, [])
%{order: :asc}

run(queryable, params)

Specs

run(Ecto.Query.t(), map()) :: Ecto.Query.t()

run(Ecto.Query.t(), map()) :: Ecto.Query.t()

This is the callback implementation of Rummage.Ecto.Hook.run/2.

Builds a sort Ecto.Query.t on top of the given Ecto.Queryable variable using given params.

Besides an Ecto.Query.t an Ecto.Schema module can also be passed as it implements Ecto.Queryable

Params is a Map which is expected to have the keys field, order.

This funciton expects a field atom, order which can be asc or desc, ci which is a boolean indicating the case-insensitivity.

Examples

When an empty map is passed as params:

iex> alias Rummage.Ecto.CustomHook.SimpleSort
iex> SimpleSort.run(Parent, %{})
** (RuntimeError) Error in params, No values given for keys: field, order

When a non-empty map is passed as params, but with a missing key:

iex> alias Rummage.Ecto.CustomHook.SimpleSort
iex> SimpleSort.run(Parent, %{field: :name})
** (RuntimeError) Error in params, No values given for keys: order

When a valid map of params is passed with an Ecto.Schema module:

iex> alias Rummage.Ecto.CustomHook.SimpleSort
iex> SimpleSort.run(Rummage.Ecto.Product, %{field: :name, order: :asc})
#Ecto.Query<from p0 in subquery(from p0 in Rummage.Ecto.Product), order_by: [asc: p0.name]>

When the queryable passed is an Ecto.Query variable:

iex> alias Rummage.Ecto.CustomHook.SimpleSort
iex> import Ecto.Query
iex> queryable = from u in "products"
#Ecto.Query<from p0 in "products">
iex> SimpleSort.run(queryable, %{field: :name, order: :asc})
#Ecto.Query<from p0 in subquery(from p0 in "products"), order_by: [asc: p0.name]>

When the queryable passed is an Ecto.Query variable, with desc order:

iex> alias Rummage.Ecto.CustomHook.SimpleSort
iex> import Ecto.Query
iex> queryable = from u in "products"
#Ecto.Query<from p0 in "products">
iex> SimpleSort.run(queryable, %{field: :name, order: :desc})
#Ecto.Query<from p0 in subquery(from p0 in "products"), order_by: [desc: p0.name]>

When the queryable passed is an Ecto.Query variable, with ci true:

iex> alias Rummage.Ecto.CustomHook.SimpleSort
iex> import Ecto.Query
iex> queryable = from u in "products"
#Ecto.Query<from p0 in "products">
iex> SimpleSort.run(queryable, %{field: :name, order: :asc, ci: true})
#Ecto.Query<from p0 in subquery(from p0 in "products"), order_by: [asc: fragment("lower(?)", p0.name)]>