OpenParable
Skip to content
← Back to skills

Create Filter

Development
create-filter

Create Filter 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 adding a filter to a Backpex LiveResource, creating a filter module, or the user asks about filtering data in Backpex index views.

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-filter/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/create-filter, 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 Filters

When the user wants to add a filter:

  1. Pick the right filter type from the quick reference
  2. Generate the filter module
  3. Wire it into the LiveResource's filters/0 callback

Quick Reference

TypeUse foruse moduleKey callbacks
BooleanCheckbox predicates (published yes/no)Backpex.Filters.Booleanoptions/1 returning %{label, key, predicate} maps
SelectSingle-value dropdownBackpex.Filters.Selectprompt/0, options/1 returning {label, value} tuples
MultiSelectMulti-value dropdown with checkboxesBackpex.Filters.MultiSelectprompt/0, options/1 returning {label, value} tuples
RangeDate, datetime, or number rangesBackpex.Filters.Rangetype/0 returning :date, :datetime, or :number
CustomAnything elseBackpex.Filterquery/4, render/1, render_form/1

All built-in filters auto-implement query/4, render/1, and render_form/1. Do NOT re-implement those unless you need custom behavior.

All filters have these overridable callbacks with defaults:

  • label/0: filter label (optional callback, can also be set in filters/0 map)
  • can?/1: visibility control, receives assigns, default true
  • type/1: Ecto type for validation (default :string), receives assigns
  • changeset/3: custom changeset validation (default: no-op)
  • validate/2: public validation API, builds changeset from type/1 and changeset/3

Boolean Filter

Multiple options selectable via checkboxes, combined with OR. Predicates use Ecto.Query.dynamic/2.

defmodule MyAppWeb.Filters.PostPublished do
  use Backpex.Filters.Boolean

  import Ecto.Query

  @impl Backpex.Filter
  def label, do: "Published?"

  @impl Backpex.Filters.Boolean
  def options(_assigns) do
    [
      %{label: "Published", key: "published", predicate: dynamic([x], x.published)},
      %{label: "Not published", key: "not_published", predicate: dynamic([x], not x.published)}
    ]
  end
end

Select Filter

Single-value dropdown. Default query/4 does WHERE field = value.

defmodule MyAppWeb.Filters.PostCategorySelect do
  use Backpex.Filters.Select

  import Ecto.Query

  alias MyApp.Repo

  @impl Backpex.Filter
  def label, do: "Category"

  @impl Backpex.Filters.Select
  def prompt, do: "Select category ..."

  @impl Backpex.Filters.Select
  def options(_assigns) do
    from(c in MyApp.Category, select: {c.name, c.id}, order_by: c.name) |> Repo.all()
  end
end

MultiSelect Filter

Same as Select but allows multiple values. Default query/4 does WHERE field IN values. Uses prompt/0 (implement with @impl Backpex.Filters.Select) and options/1 (implement with @impl Backpex.Filters.MultiSelect). Note: MultiSelect internally sets @behaviour Backpex.Filters.Select for the prompt callback.

Range Filter

Renders "From" and "To" inputs. Note: type/0 is arity 0, not arity 1.

defmodule MyAppWeb.Filters.PostLikeRange do
  use Backpex.Filters.Range

  @impl Backpex.Filters.Range
  def type, do: :number

  @impl Backpex.Filter
  def label, do: "Likes"
end

For dates use def type, do: :date. For datetimes use def type, do: :datetime.

Custom Filter

Use Backpex.Filter directly when no built-in type fits. You must implement query/4, render/1, and render_form/1. Note: use Backpex.Filter does not import HEEx sigils. You need use Phoenix.Component for ~H support.

defmodule MyAppWeb.Filters.PostCustom do
  use Phoenix.Component
  use Backpex.Filter

  import Ecto.Query

  @impl Backpex.Filter
  def label, do: "Custom"

  @impl Backpex.Filter
  def query(query, attribute, value, _assigns) do
    where(query, [x], field(x, ^attribute) == ^value)
  end

  @impl Backpex.Filter
  def render(assigns) do
    ~H"{@value}"
  end

  @impl Backpex.Filter
  def render_form(assigns) do
    ~H"""
    <input type="text" name={@form[@field].name} value={@value} class="input input-sm" />
    """
  end
end

Wiring Into a LiveResource

filters/0 returns a keyword list. Each key is the schema field atom being filtered.

@impl Backpex.LiveResource
def filters do
  [
    published: %{
      module: MyAppWeb.Filters.PostPublished
    },
    category_id: %{
      module: MyAppWeb.Filters.PostCategorySelect,
      label: "Category"
    },
    likes: %{
      module: MyAppWeb.Filters.PostLikeRange,
      label: "Likes",
      presets: [
        %{label: "Over 100", values: fn -> %{"start" => 100, "end" => nil} end},
        %{label: "1-99", values: fn -> %{"start" => 1, "end" => 99} end}
      ]
    }
  ]
end

Filter map keys

KeyRequiredDescription
:moduleyesThe filter module
:labelnoOverrides the module's label/0
:defaultnoPre-selected value on initial page load
:presetsnoQuick-select shortcuts: [%{label: String.t(), values: (-> value)}]

Conventions

  • Module naming: MyAppWeb.Filters.<Resource><FilterName> (e.g. MyAppWeb.Filters.PostPublished)
  • File location: lib/my_app_web/filters/<snake_case_name>.ex
  • The keyword list key in filters/0 must match the database column or foreign key
  • Always import Ecto.Query when using dynamic/2 or writing custom queries
  • Database queries in options/1 are fine since it runs at render time