Backpex.Filters.MultiSelect behaviour (Backpex v0.18.0)

The multi select filter renders checkboxes for a given list of options, hence allowing the user to select multiple values.

See the following example for an implementation of a multi select user filter.

defmodule MyAppWeb.Filters.MultiUserSelect do
  use Backpex.Filters.MultiSelect

  @impl Backpex.Filter
  def label, do: "User"

  @impl Backpex.Filters.MultiSelect
  def prompt, do: "Select user ..."

  @impl Backpex.Filters.MultiSelect
  def options, do: [
    {"John Doe", "acdd1860-65ce-4ed6-a37c-433851cf68d7"},
    {"Jane Doe", "9d78ce5e-9334-4a6c-a076-f1e72522de2"}
  ]
end

`use Backpex.Filters.MultiSelect`

When you use Backpex.Filters.MultiSelect, the Backpex.Filters.MultiSelect module will set @behavior Backpex.Filters.Select. In addition it will add a render and render_form function in order to display the corresponding filter.

Summary

Callbacks

options(assigns)

The list of options for the multi select filter.

Functions

changeset(changeset, field, options)

Validates that all selected values exist in the options list.

find_option_label(options, key)

Finds the label for a given option key.

option_value_to_label(options, values)

Converts a list of option values to their corresponding labels.

query(query, attribute, values, assigns)

render(assigns)

render_form(assigns)

Callbacks

options(assigns)

@callback options(assigns :: map()) :: [{String.t() | atom(), String.t() | atom()}]

The list of options for the multi select filter.

Functions

changeset(changeset, field, options)

Validates that all selected values exist in the options list.

Returns the changeset unchanged if all values are valid, or adds an error if any value is not found in options.

find_option_label(options, key)

Finds the label for a given option key.

Returns empty string if the key is not found.

Examples

iex> options = [{"John Doe", "uuid-1"}, {"Jane Doe", "uuid-2"}]
iex> Backpex.Filters.MultiSelect.find_option_label(options, "uuid-1")
"John Doe"

iex> options = [{"John Doe", "uuid-1"}]
iex> Backpex.Filters.MultiSelect.find_option_label(options, "unknown")
""

iex> options = [{"Active", :active}, {"Inactive", :inactive}]
iex> Backpex.Filters.MultiSelect.find_option_label(options, :active)
"Active"

iex> options = [{"Active", :active}]
iex> Backpex.Filters.MultiSelect.find_option_label(options, "active")
"Active"

iex> Backpex.Filters.MultiSelect.find_option_label([{"Test", "value"}], nil)
""

option_value_to_label(options, values)

Converts a list of option values to their corresponding labels.

Returns a list with labels interspersed with commas for display.

Examples

iex> options = [{"John Doe", "uuid-1"}, {"Jane Doe", "uuid-2"}]
iex> Backpex.Filters.MultiSelect.option_value_to_label(options, ["uuid-1", "uuid-2"])
["John Doe", ", ", "Jane Doe"]

iex> options = [{"John Doe", "uuid-1"}]
iex> Backpex.Filters.MultiSelect.option_value_to_label(options, ["uuid-1"])
["John Doe"]

iex> options = [{"John Doe", "uuid-1"}]
iex> Backpex.Filters.MultiSelect.option_value_to_label(options, [])
[]

iex> options = [{"John Doe", "uuid-1"}]
iex> Backpex.Filters.MultiSelect.option_value_to_label(options, ["unknown-uuid"])
[""]

iex> options = [{"John Doe", "uuid-1"}, {"Jane Doe", "uuid-2"}, {"Bob Smith", "uuid-3"}]
iex> Backpex.Filters.MultiSelect.option_value_to_label(options, ["uuid-1", "uuid-2", "uuid-3"])
["John Doe", ", ", "Jane Doe", ", ", "Bob Smith"]

query(query, attribute, values, assigns)

render(assigns)

Attributes

value (:any) (required)
options (:list) (required)

render_form(assigns)

Attributes

form (:any) (required)
field (:atom) (required)
value (:any) (required)
options (:list) (required)
prompt (:string) (required)
errors (:list) - Defaults to [].