# `Backpex.ItemAction`
[🔗](https://github.com/naymspace/backpex/blob/0.18.3/lib/backpex/item_actions/item_action.ex#L1)

Behaviour implemented by all item actions.

# `base_schema`

```elixir
@callback base_schema(assigns :: map()) ::
  Ecto.Schema.t()
  | Ecto.Changeset.t()
  | {Ecto.Changeset.data(), Ecto.Changeset.types()}
```

The base item / schema to use for the changeset. The result will be passed as the first parameter to `c:changeset/3` each time it is called.

This function is optional and can be used to use changesets with schemas in item actions. If this function is not provided,
a schemaless changeset will be created with the provided types from `c:fields/0`.

# `cancel_label`
*optional* 

```elixir
@callback cancel_label(assigns :: map()) :: binary()
```

cancel button label

# `changeset`
*optional* 

```elixir
@callback changeset(
  change ::
    Ecto.Schema.t()
    | Ecto.Changeset.t()
    | {Ecto.Changeset.data(), Ecto.Changeset.types()},
  attrs :: map(),
  metadata :: keyword()
) :: Ecto.Changeset.t()
```

The changeset to be used in the item action. It is used to validate form inputs.

Additional metadata is passed as a keyword list via the metadata parameter.

The list of metadata:
- `:assigns` - the assigns
- `:target` - the name of the `form` target that triggered the changeset call. Defaults to `nil` if the call was not triggered by a form field.

# `confirm`
*optional* 

```elixir
@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.

# `confirm_label`
*optional* 

```elixir
@callback confirm_label(assigns :: map()) :: binary()
```

Confirm button label

# `fields`
*optional* 

```elixir
@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:

- `Backpex.Fields.BelongsTo`
- `Backpex.Fields.HasMany`
- `Backpex.Fields.HasManyThrough`
- `Backpex.Fields.Upload`

# `handle`
*optional* 

```elixir
@callback handle(
  socket :: Phoenix.LiveView.Socket.t(),
  items :: [map()],
  params :: map() | struct()
) ::
  {:ok, Phoenix.LiveView.Socket.t()} | {:error, Ecto.Changeset.t()}
```

Performs the action. It takes the socket, the list of affected items, and the casted and validated data (received from [`Ecto.Changeset.apply_action/2`](https://hexdocs.pm/ecto/Ecto.Changeset.html#apply_action/2)).

Exactly one of `c:handle/3` or `c:link/2` must be implemented for each item action.
If `c:link/2` is implemented, `c:handle/3` must not be defined, and vice versa. Link-based actions navigate directly without a server round-trip.

You must return either `{:ok, socket}` or `{:error, changeset}`.

If `{:ok, socket}` is returned, the action is considered successful by Backpex and the action modal is closed. However, you can add an error flash message to the socket to indicate that something has gone wrong.

If `{:error, changeset}` is returned, the changeset is used to update the form to display the errors. Note that Backpex already validates the form for you.
Therefore it is only necessary in rare cases to perform additional validation and return a changeset from `c:handle/3`.
For example, if you are building a duplicate action and can only check for a unique constraint when inserting the duplicate element.

You are only allowed to return `{:error, changeset}` if the action has a form. Otherwise Backpex will throw an ArgumentError.

# `icon`

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

Action icon

# `label`

```elixir
@callback label(assigns :: map(), item :: struct() | nil) :: binary()
```

Action label (Show label on hover)

# `link`
*optional* 

```elixir
@callback link(assigns :: map(), item :: struct()) :: binary()
```

Returns a URL path for the item action. When implemented, the action renders as a `<.link navigate={path}>`
instead of a `<button>`. This enables standard browser link behavior such as Ctrl+click to open in a new tab
and right-click context menus.

# `__using__`
*macro* 

Defines `Backpex.ItemAction` behaviour and provides default implementations.

# `assign_action_changeset`

Prepares the socket for opening an action confirmation modal.

If the action has a form, it creates a changeset and assigns it along with the base schema.
Otherwise, it assigns an empty changeset.

# `default_actions`

Returns default item actions.

# `handle_item_action`

Handles an item action by executing the action's handle function.

This function filters items based on authorization, executes the action,
and allows customization of post-action behavior via the `after_handle` callback.

# `has_confirm_modal?`

Checks whether item action has confirmation modal.

# `has_form?`

Checks whether item action has form.

# `has_link?`

Checks whether item action has a link callback.

---

*Consult [api-reference.md](api-reference.md) for complete listing*