View Source Backpex.LiveResource behaviour (Backpex v0.6.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.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).
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.
Calculates the total amount of pages.
Calls the changeset function with the given change and target.
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
List all items for current page with filters and search applied.
Maybe subscribes to pubsub.
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.
Returns pubsub settings based on configuration.
Returns all search options.
Returns all searchable fields. A field is not searchable by default.
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 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,
layout: {MyAppWeb.LayoutView, :admin},
schema: MyApp.User,
repo: MyApp.Repo,
update_changeset: &MyApp.User.update_changeset/3,
create_changeset: &MyApp.User.create_changeset/3Options
:layout- Layout to be used by the LiveResource.:schema- Schema for the resource.:repo- Ecto repo that will be used to perform CRUD operations for the given schema.:update_changeset- Changeset to use when updating items. Additional metadata is passed as a keyword list via the third parameter.The list of metadata:
:assigns- the assigns:target- the name of theformtarget that triggered the changeset call. Default tonilif the call was not triggered by a form field.
:create_changeset- Changeset to use when creating items. Additional metadata is passed as a keyword list via the third parameter.The list of metadata:
:assigns- the assigns:target- the name of theformtarget that triggered the changeset call. Default tonilif the call was not triggered by a form field.
:pubsub- PubSub name of the project.:topic- The topic for PubSub.:event_prefix- The event prefix for Pubsub, to differentiate between events of different resources when subscribed to multiple resources.:per_page_options- The page size numbers you can choose from. Defaults to[15, 50, 100].:per_page_default- The default page size number. Defaults to the first element of theper_page_optionslist.:init_order- Order that will be used when no other order options are given. Defaults to%{by: :id, direction: :asc}.
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)
5call_changeset_function(item, changeset_function, change, assigns, target \\ nil)
View SourceCalls the changeset function with the given change and target.
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.
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 SourceList all items for current page with filters and search applied.
Maybe subscribes to pubsub.
order_options_by_params(params, fields, init_order, 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)
1Returns pubsub settings based on configuration.
Returns 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}])
[]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