View Source Backpex.LiveResource behaviour (Backpex v0.8.1)

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

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.

Customizes the label of the button for creating a new item. Defaults to "New %{resource}".

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

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

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

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

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

The function that can be used to inject an ecto query. The query will be used when resources are being fetched. This happens on index, edit and show view. In most cases this function will be used to filter items on index view based on certain criteria, but it may also be used to join other tables on edit or show view.

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

This function is executed when an item has been created.

This function is executed when an item has been deleted.

This function is executed when an item has been updated.

A list of panels to group certain fields together.

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

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

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

Customizes the message in the flash message when a resource has been created successfully. Defaults to "New %{resource} has been created successfully".

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

Returns the schema of the live resource.

Replaces the default placeholder for the index search.

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

Functions

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

TODO: make private?

Calculates the total amount of pages.

Checks whether user is allowed to perform provided action or not

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.

Returns all filter options.

Returns filtered fields by a certain action.

Returns list of active filters.

Returns list of filter options from query options

Checks whether a field is orderable or not.

Returns all orderable fields. A field is orderable by 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.

Resolves the initial order configuration.

Returns all search options.

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

Subscribes to pubsub topic.

Validates a page number.

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

Callbacks

Link to this callback

can?(assigns, action, item)

View Source
@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.

@callback create_button_label() :: binary()

Customizes the label of the button for creating a new item. Defaults to "New %{resource}".

@callback fields() :: list()

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

@callback filters() :: keyword()

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

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

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

Link to this callback

index_row_class(assigns, item, selected, index)

View Source
@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.

Link to this callback

item_actions(default_actions)

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

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

Link to this callback

item_query(query, live_action, assigns)

View Source
@callback item_query(query :: Ecto.Query.t(), live_action :: atom(), assigns :: map()) ::
  Ecto.Query.t()

The function that can be used to inject an ecto query. The query will be used when resources are being fetched. This happens on index, edit and show view. In most cases this function will be used to filter items on index view based on certain criteria, but it may also be used to join other tables on edit or show view.

The function has to return an Ecto.Query. It is recommended to build your item_query on top of the incoming query. Otherwise you will likely get binding errors.

@callback metrics() :: keyword()

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

Link to this callback

on_item_created(socket, item)

View Source
@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.

Link to this callback

on_item_deleted(socket, item)

View Source
@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.

Link to this callback

on_item_updated(socket, item)

View Source
@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.

@callback panels() :: list()

A list of panels to group certain fields together.

@callback plural_name() :: binary()

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

Link to this callback

render_resource_slot(assigns, action, position)

View Source
@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.

The following actions are supported: :index, :show

The following positions are supported for the :index action: :page_title, :actions, :filters, :metrics and :main. The following positions are supported for the :show action: :page_title and :main.

In addition to this, content can be inserted between the main positions via the following extra spots: :before_page_title, :before_actions, :before_filters, :before_metrics and :before_main.

@callback resource_actions() :: list()

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

Link to this callback

resource_created_message()

View Source
@callback resource_created_message() :: binary()

Customizes the message in the flash message when a resource has been created successfully. Defaults to "New %{resource} has been created successfully".

Link to this callback

return_to(socket, assigns, action, item)

View Source
@callback return_to(
  socket :: Phoenix.LiveView.Socket.t(),
  assigns :: map(),
  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 edit).

@callback schema() :: module()

Returns the schema of the live resource.

@callback search_placeholder() :: binary()

Replaces the default placeholder for the index search.

@callback singular_name() :: binary()

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

Functions

Link to this macro

__using__(opts)

View Source (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) - Required. PubSub configuration.

    • :name (atom/0) - Required. PubSub name of the project.

    • :event_prefix (String.t/0) - Required. The event prefix for Pubsub, to differentiate between events of different resources when subscribed to multiple resources.

    • :topic (String.t/0) - Required. The topic for PubSub.

  • :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) - The default value is false.

  • :full_text_search (atom/0)

TODO: make private?

Link to this function

calculate_total_pages(items_length, per_page)

View Source

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
Link to this function

can?(assigns, action, item, module)

View Source

Checks whether user is allowed to perform provided action or not

Link to this function

filter_field_by_action(field_options, action)

View Source

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
Link to this function

filter_options(arg1, filter_configs)

View Source

Returns all filter options.

Link to this function

filtered_fields_by_action(fields, assigns, action)

View Source

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"}]
Link to this function

get_active_filters(module, assigns)

View Source

Returns list of active filters.

Link to this function

get_filter_options(module, query_options)

View Source

Returns list of filter options from query options

Link to this function

get_valid_filters_from_params(params, valid_filters, empty_filter_key)

View Source
Link to this function

maybe_put_empty_filter(filters, empty_filter_key)

View Source
Link to this function

order_options_by_params(params, fields, init_order, assigns, permitted_order_directions)

View Source

Returns order options by params.

Examples

iex> Backpex.LiveResource.order_options_by_params(%{"order_by" => "field", "order_direction" => "asc"}, [field: %{}], %{by: :id, direction: :asc}, %{}, [:asc, :desc])
%{order_by: :field, order_direction: :asc}
iex> Backpex.LiveResource.order_options_by_params(%{}, [field: %{}], %{by: :id, direction: :desc}, %{}, [:asc, :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}, %{}, [:asc, :desc])
%{order_by: :id, order_direction: :asc}

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
Link to this function

orderable_fields(fields)

View Source

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}])
[]
Link to this function

parse_integer(map, key, default)

View Source

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
Link to this function

resolve_init_order(init_order, assigns)

View Source

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
Link to this function

search_options(params, fields, schema)

View Source

Returns all search options.

Link to this function

searchable_fields(fields)

View Source

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}])
[]
Link to this function

subscribe_to_topic(socket, list)

View Source

Subscribes to pubsub topic.

Link to this function

validate_page(page, total_pages)

View Source

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
Link to this function

value_in_permitted_or_default(value, permitted, default)

View Source

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