Backpex.LiveResource behaviour (Backpex v0.12.0)

A LiveResource makes it easy to manage existing resources in your application. It provides extensive configuration options in order to meet everyone's needs. In connection with Backpex.Components you can build an individual admin dashboard on top of your application in minutes.

`use Backpex.LiveResource`

When you use Backpex.LiveResource, the Backpex.LiveResource module will set @behavior Backpex.LiveResource. Additionally it will create a LiveView based on the given configuration in order to create fully functional index, show, new and edit views for a resource. It will also insert fallback functions that can be overridden.

Summary

Callbacks

can?(assigns, action, item)

The function that can be used to restrict access to certain actions. It will be called before performing an action and aborts when the function returns false.

fields()

A list of fields defining your resource. See Backpex.Field.

filters()

A optional keyword list of filters to be used on the index view.

filters(assigns)

A optional keyword list of filters to be used on the index view.

index_row_class(assigns, item, selected, index)

An extra class to be added to table rows on the index view.

item_actions(default_actions)

A list of item_actions that may be performed on (selected) items.

metrics()

A list of metrics shown on the index view of your resource.

on_item_created(socket, item)

This function is executed when an item has been created.

on_item_deleted(socket, item)

This function is executed when an item has been deleted.

on_item_updated(socket, item)

This function is executed when an item has been updated.

panels()

A list of panels to group certain fields together.

plural_name()

The plural name of the resource used for translations and titles.

render_resource_slot(assigns, action, position)

The function that can be used to add content to certain positions on Backpex views. It may also be used to overwrite content.

resource_actions()

A list of resource_actions that may be performed on the given resource.

return_to(socket, assigns, live_action, form_action, item)

This function navigates to the specified path when an item has been created or updated. Defaults to the previous resource path (index or show).

singular_name()

The singular name of the resource used for translations and titles.

translate(msg)

This function can be used to provide custom translations for texts. See the translations guide for detailed information.

Functions

__using__(opts)

Uses LiveResource in the current module to make it a LiveResource.

active_filters(assigns)

Returns list of active filters.

assign_items(socket)

calculate_total_pages(items_length, per_page)

Calculates the total amount of pages.

empty_filter_key()

filter_field_by_action(field_options, action)

Filters a field by a given action. It checks whether the field contains the only or except key and decides whether or not to keep the field.

filter_options(arg1, filter_configs)

Returns all filter options.

filtered_fields_by_action(fields, assigns, action)

Returns filtered fields by a certain action.

get_filter_options(query_options)

Returns list of filter options from query options

order_options_by_params(params, fields, init_order, assigns)

Returns order options by params.

orderable?(field)

Checks whether a field is orderable or not.

orderable_fields(fields)

Returns all orderable fields. A field is orderable by default.

parse_integer(map, key, default)

Parses integer text representation map value of the given key. If the map does not contain the given key or parsing fails the default value is returned.

primary_value(item, live_resource)

pubsub(live_resource)

Returns the pubsub settings for the current LiveResource.

resolve_init_order(init_order, assigns)

Resolves the initial order configuration.

search_options(params, fields, schema)

Returns all search options.

searchable_fields(fields)

Returns all searchable fields. A field is not searchable by default.

subscribe_to_topic(socket, list)

Subscribes to pubsub topic.

validate_page(page, total_pages)

Validates a page number.

validated_fields(live_resource)

Returns the fields of the given Backpex.LiveResource validated against each fields config schema.

value_in_permitted_or_default(value, permitted, default)

Checks whether the given value is in a list of permitted values. Otherwise return default value.

Callbacks

can?(assigns, action, item)

@callback can?(assigns :: map(), action :: atom(), item :: map() | nil) :: boolean()

The function that can be used to restrict access to certain actions. It will be called before performing an action and aborts when the function returns false.

fields()

@callback fields() :: list()

A list of fields defining your resource. See Backpex.Field.

filters()

@callback filters() :: keyword()

A optional keyword list of filters to be used on the index view.

filters(assigns)

@callback filters(assigns :: map()) :: keyword()

A optional keyword list of filters to be used on the index view.

index_row_class(assigns, item, selected, index)

@callback index_row_class(
  assigns :: map(),
  item :: map(),
  selected :: boolean(),
  index :: integer()
) ::
  binary() | nil

An extra class to be added to table rows on the index view.

item_actions(default_actions)

@callback item_actions(default_actions :: [map()]) :: list()

A list of item_actions that may be performed on (selected) items.

metrics()

@callback metrics() :: keyword()

A list of metrics shown on the index view of your resource.

on_item_created(socket, item)

@callback on_item_created(socket :: Phoenix.LiveView.Socket.t(), item :: map()) ::
  Phoenix.LiveView.Socket.t()

This function is executed when an item has been created.

on_item_deleted(socket, item)

@callback on_item_deleted(socket :: Phoenix.LiveView.Socket.t(), item :: map()) ::
  Phoenix.LiveView.Socket.t()

This function is executed when an item has been deleted.

on_item_updated(socket, item)

@callback on_item_updated(socket :: Phoenix.LiveView.Socket.t(), item :: map()) ::
  Phoenix.LiveView.Socket.t()

This function is executed when an item has been updated.

panels()

@callback panels() :: list()

A list of panels to group certain fields together.

plural_name()

@callback plural_name() :: binary()

The plural name of the resource used for translations and titles.

render_resource_slot(assigns, action, position)

@callback render_resource_slot(assigns :: map(), action :: atom(), position :: atom()) ::
  %Phoenix.LiveView.Rendered{
    caller: term(),
    dynamic: term(),
    fingerprint: term(),
    root: term(),
    static: term()
  }

The function that can be used to add content to certain positions on Backpex views. It may also be used to overwrite content.

See the following list for the available positions and the corresponding actions:

all actions
- :before_page_title
- :page_title
- :before_main
- :main
- :after_main
:index action
- :before_actions
- :actions
- :before_filters
- :filters
- :before_metrics
- :metrics

resource_actions()

@callback resource_actions() :: list()

A list of resource_actions that may be performed on the given resource.

return_to(socket, assigns, live_action, form_action, item)

@callback return_to(
  socket :: Phoenix.LiveView.Socket.t(),
  assigns :: map(),
  live_action :: atom(),
  form_action :: atom(),
  item :: map()
) :: binary()

This function navigates to the specified path when an item has been created or updated. Defaults to the previous resource path (index or show).

singular_name()

@callback singular_name() :: binary()

The singular name of the resource used for translations and titles.

translate(msg)

@callback translate(msg :: tuple()) :: binary()

This function can be used to provide custom translations for texts. See the translations guide for detailed information.

Examples

# in your LiveResource

@impl Backpex.LiveResource
def translate({"Cancel", _opts}), do: gettext("Go back")
def translate({"Save", _opts}), do: gettext("Continue")
def translate({"New %{resource}", opts}), do: gettext("Create %{resource}", opts)

Functions

using(opts)

(macro)

Uses LiveResource in the current module to make it a LiveResource.

use Backpex.LiveResource,
  adapter_config: [
    schema: MyApp.User,
    repo: MyApp.Repo,
    update_changeset: &MyApp.User.update_changeset/3,
    create_changeset: &MyApp.User.create_changeset/3
  ],
  layout: {MyAppWeb.LayoutView, :admin}
  # ...

Options

:adapter (atom/0) - The data layer adapter to use. The default value is Backpex.Adapters.Ecto.
:adapter_config (keyword/0) - Required. The configuration for the data layer. See corresponding adapter for possible configuration values.
:primary_key (atom/0) - The primary key used for identifying items. The default value is :id.
:layout - Required. Layout to be used by the LiveResource.
:pubsub (keyword/0) - PubSub configuration.
- :server (atom/0) - PubSub server of the project.
- :topic (String.t/0) - The topic for PubSub.
  By default a stringified version of the live resource module name is used.
:per_page_options (list of integer/0) - The page size numbers you can choose from. The default value is [15, 50, 100].
:per_page_default (integer/0) - The default page size number. The default value is 15.
:init_order - Order that will be used when no other order options are given. The default value is {:%{}, [], [by: :id, direction: :asc]}.
:fluid? (boolean/0) - If the layout fills out the entire width. The default value is false.
:full_text_search (atom/0) - The name of the generated column used for full text search. The default value is nil.
:save_and_continue_button? (boolean/0) - If the "Save & Continue editing" button is shown on form views. The default value is false.

active_filters(assigns)

Returns list of active filters.

assign_items(socket)

calculate_total_pages(items_length, per_page)

Calculates the total amount of pages.

Examples

iex> Backpex.LiveResource.calculate_total_pages(1, 2)
1
iex> Backpex.LiveResource.calculate_total_pages(10, 10)
1
iex> Backpex.LiveResource.calculate_total_pages(20, 10)
2
iex> Backpex.LiveResource.calculate_total_pages(25, 6)
5

empty_filter_key()

filter_field_by_action(field_options, action)

Filters a field by a given action. It checks whether the field contains the only or except key and decides whether or not to keep the field.

Examples

iex> Backpex.LiveResource.filter_field_by_action(%{only: [:index]}, :index)
true
iex> Backpex.LiveResource.filter_field_by_action(%{only: [:edit]}, :index)
false
iex> Backpex.LiveResource.filter_field_by_action(%{except: [:edit]}, :index)
true
iex> Backpex.LiveResource.filter_field_by_action(%{except: [:index]}, :index)
false

filtered_fields_by_action(fields, assigns, action)

Returns filtered fields by a certain action.

Example

iex> Backpex.LiveResource.filtered_fields_by_action([field1: %{label: "Field1"}, field2: %{label: "Field2"}], %{}, :index)
[field1: %{label: "Field1"}, field2: %{label: "Field2"}]
iex> Backpex.LiveResource.filtered_fields_by_action([field1: %{label: "Field1", except: [:show]}, field2: %{label: "Field2"}], %{}, :show)
[field2: %{label: "Field2"}]
iex> Backpex.LiveResource.filtered_fields_by_action([field1: %{label: "Field1", only: [:index]}, field2: %{label: "Field2"}], %{}, :show)
[field2: %{label: "Field2"}]

get_filter_options(query_options)

Returns list of filter options from query options

order_options_by_params(params, fields, init_order, assigns)

Returns order options by params.

Examples

iex> Backpex.LiveResource.order_options_by_params(%{"order_by" => "field", "order_direction" => "asc"}, [field: %{}], %{by: :id, direction: :asc}, %{})
%{order_by: :field, order_direction: :asc}
iex> Backpex.LiveResource.order_options_by_params(%{}, [field: %{}], %{by: :id, direction: :desc}, %{})
%{order_by: :id, order_direction: :desc}
iex> Backpex.LiveResource.order_options_by_params(%{"order_by" => "field", "order_direction" => "asc"}, [field: %{orderable: false}], %{by: :id, direction: :asc}, %{})
%{order_by: :id, order_direction: :asc}

orderable?(field)

Checks whether a field is orderable or not.

Examples

iex> Backpex.LiveResource.orderable?({:name, %{orderable: true}})
true
iex> Backpex.LiveResource.orderable?({:name, %{orderable: false}})
false
iex> Backpex.LiveResource.orderable?({:name, %{}})
true
iex> Backpex.LiveResource.orderable?(nil)
false

orderable_fields(fields)

Returns all orderable fields. A field is orderable by default.

Example

iex> Backpex.LiveResource.orderable_fields([field1: %{orderable: true}])
[:field1]
iex> Backpex.LiveResource.orderable_fields([field1: %{}])
[:field1]
iex> Backpex.LiveResource.orderable_fields([field1: %{orderable: false}])
[]

parse_integer(map, key, default)

Parses integer text representation map value of the given key. If the map does not contain the given key or parsing fails the default value is returned.

Examples

iex> Backpex.LiveResource.parse_integer(%{number: "1"}, :number, 2)
1
iex> Backpex.LiveResource.parse_integer(%{number: "abc"}, :number, 1)
1

primary_value(item, live_resource)

pubsub(live_resource)

Returns the pubsub settings for the current LiveResource.

resolve_init_order(init_order, assigns)

Resolves the initial order configuration.

Examples

iex> Backpex.LiveResource.resolve_init_order(%{by: :name, direction: :asc}, %{})
%{by: :name, direction: :asc}

iex> Backpex.LiveResource.resolve_init_order(fn _ -> %{by: :age, direction: :desc} end, %{})
%{by: :age, direction: :desc}

iex> Backpex.LiveResource.resolve_init_order(fn assigns -> fn _ -> %{by: assigns.sort_by, direction: :asc} end end, %{sort_by: :date})
** (ArgumentError) init_order function should not return another function

iex> Backpex.LiveResource.resolve_init_order(:invalid, %{})
** (ArgumentError) init_order must be a map with keys :by and :direction, or a function returning such a map. Got: :invalid

search_options(params, fields, schema)

Returns all search options.

searchable_fields(fields)

Returns all searchable fields. A field is not searchable by default.

Example

iex> Backpex.LiveResource.searchable_fields([field1: %{searchable: true}])
[:field1]
iex> Backpex.LiveResource.searchable_fields([field1: %{}])
[]
iex> Backpex.LiveResource.searchable_fields([field1: %{searchable: false}])
[]

subscribe_to_topic(socket, list)

Subscribes to pubsub topic.

validate_page(page, total_pages)

Validates a page number.

Examples

iex> Backpex.LiveResource.validate_page(1, 5)
1
iex> Backpex.LiveResource.validate_page(-1, 5)
1
iex> Backpex.LiveResource.validate_page(6, 5)
5

validated_fields(live_resource)

Returns the fields of the given Backpex.LiveResource validated against each fields config schema.

value_in_permitted_or_default(value, permitted, default)

Checks whether the given value is in a list of permitted values. Otherwise return default value.

Examples

iex> Backpex.LiveResource.value_in_permitted_or_default(3, [1, 2, 3], 5)
3
iex> Backpex.LiveResource.value_in_permitted_or_default(3, [1, 2], 5)
5