View Source Backpex.LiveResource behaviour (Backpex v0.8.2)
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.LiveResourceWhen you
use Backpex.LiveResource, theBackpex.LiveResourcemodule 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.
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
Returns order options by params.
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
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.
A optional keyword list of filters to be used on the index view.
@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.
A list of item_actions that may be performed on (selected) items.
@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.
@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.
@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.
@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.
@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.
@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".
@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
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 isBackpex.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 ofinteger/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 is15.: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 isfalse.:full_text_search(atom/0)
TODO: make private?
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)
5Checks 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.
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)
falseReturns all filter options.
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"}]Returns list of active filters.
Returns list of filter options from query options
get_valid_filters_from_params(params, valid_filters, empty_filter_key)
View Sourceorder_options_by_params(params, fields, init_order, assigns, permitted_order_directions)
View SourceReturns 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)
falseReturns 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}])
[]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)
1Resolves 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: :invalidReturns all search options.
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}])
[]Subscribes to pubsub topic.
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)
5Checks 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