View Source Backpex.ItemAction behaviour (Backpex v0.1.1)

Behaviour implemented by all item actions.

An Item Action defines an action (such as deleting a user) that can be performed on one or more items. Unlike resource actions, item actions are not automatically performed on all items in a resource. First, items must be selected.

There are multiple ways to perform an Item Action:

  • use the checkboxes in the first column of the resource table to select 1-n items and trigger the action later on
  • use an icon in the last column of the resource table to perform the Item Action for one item
  • use the corresponding icon in the show view to perform the Item Action for the corresponding item

If you use the first method, you must trigger the item action using the button above the resource action. If you use the second or third method, the item action is triggered immediately.

Therefore, you need to provide a label and an icon in your code. The label is displayed above the resource table and the icon is displayed for each element in the table and in the show view. This gives the user multiple ways to trigger your item action.

Optionally, there can be a confirmation modal. You can enable this by specifying a text to be displayed in the modal via the confirm function. You can also specify a changeset and a list of fields. The fields are displayed in the confirm modal as well. For example, a field could be a reason for deleting a user.

In the list of fields, each field needs a type. This is because we cannot infer a type from a schema.

To add an item action to your resource you can use the item_actions function. This must be a keyword list. The keyword defines the name of the action. In addition, each keyword must define a map as a value. This map must at least provide the module for the item action with the module key. The "default" Item Actions (Delete, Edit and Show) are passed as parameters to the item_actions and may be appended to your item actions.

Furthermore, you can specify which ways of triggering the item action are enabled with the only key.

The only key must provide a list and accepts the following options

  • :row - display an icon for each element in the table that can trigger the Item Action for the corresponding element
  • :index - display a button at the top of the resource table, which triggers the Item Action for selected items
  • :show - display an icon in the show view that triggers the Item Action for the corresponding item

The following example shows how to define a soft delete item action and replace it with the default delete Item Action.

Example

defmodule DemoWeb.ItemAction.SoftDelete do
  use BackpexWeb, :item_action

  alias Backpex.Resource

  @impl Backpex.ItemAction
  def icon(assigns) do
    ~H"""
    <Heroicons.eye class="h-5 w-5 cursor-pointer transition duration-75 hover:scale-110 hover:text-green-600" />
    """
  end

  @impl Backpex.ItemAction
  def fields do
    [
      reason: %{
        module: Backpex.Fields.Textarea,
        label: "Reason",
        type: :string
      }
    ]
  end

  @required_fields ~w[reason]a

  @impl Backpex.ItemAction
  def changeset(change, attrs) do
    change
    |> cast(attrs, @required_fields)
    |> validate_required(@required_fields)
  end

  @impl Backpex.ItemAction
  def label(_assigns), do: Backpex.translate("Delete")

  @impl Backpex.ItemAction
  def confirm_label(_assigns), do: Backpex.translate("Delete")

  @impl Backpex.ItemAction
  def cancel_label(_assigns), do: Backpex.translate("Cancel")

  @impl Backpex.ItemAction
  def handle(socket, items, params) do
    datetime = DateTime.truncate(DateTime.utc_now(), :second)
    socket =
      try do
        {:ok, _items} =
          Backpex.Resource.update_all(
            socket.assigns,
            items,
            [set: [deleted_at: datetime, reason: Map.get(params, "reason")]],
            "deleted"
          )

        socket
        |> clear_flash()
        |> put_flash(:info, "Item(s) successfully deleted.")
      rescue
          socket
          |> clear_flash()
          |> put_flash(:error, error)
      end

    {:noreply, socket}
end

# in your resource configuration file

@impl Backpex.LiveResource
def item_actions([show, edit, _delete]) do
  Enum.concat([show, edit],
    soft_delete: %{module: DemoWeb.ItemAction.SoftDelete}
  )
end

Summary

Callbacks

cancel button label

The changeset to be used in the resource action. It may be used to validate form inputs.

This text is being displayed in the confirm dialog.

Confirm button label

A list of fields to be displayed in the item action. See Backpex.Field. In addition you have to provide a type for each field in order to support changeset generation.

Performs the action.

Action icon

Initial change. The result will be passed to Backpex.ItemAction.changeset/2 in order to generate a changeset.

Action label (Show label on hover)

Functions

Defines Backpex.ItemAction behaviour and provides default implementations.

Callbacks

Link to this callback

cancel_label(assigns)

View Source (optional)
@callback cancel_label(assigns :: map()) :: binary()

cancel button label

Link to this callback

changeset(change, attrs)

View Source (optional)
@callback changeset(
  change ::
    Ecto.Schema.t()
    | Ecto.Changeset.t()
    | {Ecto.Changeset.data(), Ecto.Changeset.types()},
  attrs :: map()
) :: Ecto.Changeset.t()

The changeset to be used in the resource action. It may be used to validate form inputs.

Link to this callback

confirm(assigns)

View Source (optional)
@callback confirm(assigns :: map()) :: binary()

This text is being displayed in the confirm dialog.

There won't be any confirmation when this function is not defined.

Link to this callback

confirm_label(assigns)

View Source (optional)
@callback confirm_label(assigns :: map()) :: binary()

Confirm button label

@callback fields() :: list()

A list of fields to be displayed in the item action. See Backpex.Field. In addition you have to provide a type for each field in order to support changeset generation.

The following fields are currently not supported:

Link to this callback

handle(socket, items, params)

View Source
@callback handle(socket :: Phoenix.LiveView.Socket.t(), items :: [map()], params :: map()) ::
  {:noreply, Phoenix.LiveView.Socket.t()}
  | {:reply, map(), Phoenix.LiveView.Socket.t()}

Performs the action.

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

Action icon

@callback init_change() ::
  Ecto.Schema.t()
  | Ecto.Changeset.t()
  | {Ecto.Changeset.data(), Ecto.Changeset.types()}

Initial change. The result will be passed to Backpex.ItemAction.changeset/2 in order to generate a changeset.

This function is optional and can be used to use changesets with schemas in item actions. If this function is not provided a changeset will be generated automatically based on the provided types in Backpex.ItemAction.fields/0.

@callback label(assigns :: map()) :: binary()

Action label (Show label on hover)

Functions

Defines Backpex.ItemAction behaviour and provides default implementations.