OpenParable
Skip to content
← Back to skills

Create Resource Action

Development
create-resource-action

Create Resource Action is an Agent Skill for development published in the naymspace/backpex repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when creating Backpex resource actions for global operations like bulk exports, invitations, imports, or any action that applies to the resource as a whole rather than individual items.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/naymspace/backpex/blob/HEAD/skills/create-resource-action/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/create-resource-action, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Creating Backpex Resource Actions

You are an expert at creating resource actions for Backpex. Resource actions operate on the resource as a whole (not individual items) and appear as buttons in the index toolbar. They open a slide-over with a form.

Required Callbacks

CallbackSignatureDescription
title/0-> stringSlide-over title
label/0-> stringButton text in index toolbar
fields/0-> keyword listForm field definitions
changeset/3(change, attrs, metadata) -> changesetValidate form data. metadata has :assigns and :target keys
handle/2(socket, data) -> {:ok, socket} | {:error, changeset}Execute the action with validated data

Optional Callbacks

CallbackDefaultDescription
base_schema/1schemaless changesetOverride to use a real Ecto schema

Example: Simple Resource Action

defmodule MyAppWeb.ResourceActions.InviteUser do
  use Backpex.ResourceAction

  import Ecto.Changeset

  @impl Backpex.ResourceAction
  def title, do: "Invite User"

  @impl Backpex.ResourceAction
  def label, do: "Invite"

  @impl Backpex.ResourceAction
  def fields do
    [
      email: %{
        module: Backpex.Fields.Text,
        label: "Email",
        type: :string
      },
      role: %{
        module: Backpex.Fields.Select,
        label: "Role",
        options: [Admin: "admin", User: "user"],
        prompt: "Select role...",
        type: :string
      }
    ]
  end

  @impl Backpex.ResourceAction
  def changeset(change, attrs, _metadata) do
    change
    |> cast(attrs, [:email, :role])
    |> validate_required([:email, :role])
    |> validate_format(:email, ~r/@/)
  end

  @impl Backpex.ResourceAction
  def handle(socket, data) do
    case MyApp.Accounts.send_invitation(data.email, data.role) do
      :ok ->
        {:ok, Phoenix.LiveView.put_flash(socket, :info, "Invitation sent to #{data.email}.")}

      {:error, reason} ->
        {:ok, Phoenix.LiveView.put_flash(socket, :error, "Failed: #{reason}")}
    end
  end
end

Example: Export Action

defmodule MyAppWeb.ResourceActions.ExportPosts do
  use Backpex.ResourceAction

  import Ecto.Changeset

  @impl Backpex.ResourceAction
  def title, do: "Export Posts"

  @impl Backpex.ResourceAction
  def label, do: "Export"

  @impl Backpex.ResourceAction
  def fields do
    [
      format: %{
        module: Backpex.Fields.Select,
        label: "Format",
        options: [CSV: "csv", JSON: "json"],
        prompt: "Select format...",
        type: :string
      }
    ]
  end

  @impl Backpex.ResourceAction
  def changeset(change, attrs, _metadata) do
    change
    |> cast(attrs, [:format])
    |> validate_required([:format])
    |> validate_inclusion(:format, ["csv", "json"])
  end

  @impl Backpex.ResourceAction
  def handle(socket, data) do
    # Trigger export...
    {:ok, Phoenix.LiveView.put_flash(socket, :info, "Export started in #{data.format} format.")}
  end
end

Wiring Into a LiveResource

@impl Backpex.LiveResource
def resource_actions do
  [
    invite: %{module: MyAppWeb.ResourceActions.InviteUser},
    export: %{module: MyAppWeb.ResourceActions.ExportPosts}
  ]
end

The keyword key (e.g. :invite) is used as the action identifier for routing and authorization via can?/3.

Key Differences From Item Actions

AspectResource ActionItem Action
ScopeWhole resourceSelected items
UISlide-over formModal dialog
Callbackstitle/0, label/0, handle/2icon/2, label/2, handle/3
FormAlways has fieldsOptional
LocationIndex toolbar onlyRow, index toolbar, show page

Conventions

  • File location: lib/my_app_web/resource_actions/<snake_case_name>.ex
  • Module naming: MyAppWeb.ResourceActions.<ActionName>
  • Always include type: key in each field map (e.g. type: :string). This is required for the schemaless changeset to work.
  • Authorization is handled via can?(assigns, :action_key, nil) in the LiveResource (item is always nil)
  • Return {:error, changeset} from handle/2 to keep the form open and show validation errors