# =============================================================================
# ASH FORM BUILDER - RELATIONSHIPS GUIDE
# =============================================================================
# has_many vs many_to_many: Dynamic forms, filtering, and conditions
# =============================================================================
# =============================================================================
# PART 1: HAS_MANY (Nested Forms - Dynamic Add/Remove)
# =============================================================================
#
# Use `has_many` when:
# - Child records have their own lifecycle
# - You need to manage child attributes (not just the relationship)
# - Examples: Task → Subtasks, Order → OrderItems, Post → Comments
#
# =============================================================================
defmodule MyApp.Todos.Task do
use Ash.Resource,
domain: MyApp.Todos,
data_layer: AshPostgres.DataLayer,
extensions: [AshFormBuilder]
attributes do
uuid_primary_key :id
attribute :title, :string, allow_nil?: false
attribute :status, :atom, constraints: [one_of: [:pending, :in_progress, :done]]
end
relationships do
# ─────────────────────────────────────────────────────────────────────────
# HAS_MANY: Subtasks
# ─────────────────────────────────────────────────────────────────────────
# Each subtask is a full record with its own attributes
has_many :subtasks, MyApp.Todos.Subtask do
destination_attribute_on_join_resource :task_id
# Optionally set default on_create actions
end
# HAS_MANY: Checklists (another example)
has_many :checklist_items, MyApp.Todos.ChecklistItem
end
actions do
create :create do
accept [:title, :status]
# Manage nested records
manage_relationship :subtasks, :subtasks, type: :create
manage_relationship :checklist_items, :checklist_items, type: :create
end
update :update do
accept [:title, :status]
manage_relationship :subtasks, :subtasks, type: :create_and_destroy
manage_relationship :checklist_items, :checklist_items, type: :create_and_destroy
end
end
# ===========================================================================
# FORM DSL - HAS_MANY WITH NESTED FORMS
# ===========================================================================
form do
action :create
field :title do
label "Task Title"
required true
end
field :status do
type :select
options: [{"Pending", :pending}, {"In Progress", :in_progress}, {"Done", :done}]
end
# ─────────────────────────────────────────────────────────────────────────
# NESTED FORM: Subtasks (has_many)
# ─────────────────────────────────────────────────────────────────────────
#
# Features:
# - Dynamic add/remove buttons
# - Each subtask is a full form with its own fields
# - Can set min/max items
# - Can pre-populate with existing records
# ─────────────────────────────────────────────────────────────────────────
nested :subtasks do
label "Subtasks"
cardinality :many # ← :many = add/remove buttons, :one = single nested form
# Button labels
add_label "Add Subtask"
remove_label "Remove"
# Optional: Limit number of items
# min_items 1 # ← At least 1 subtask required
# max_items 10 # ← Maximum 10 subtasks
# Optional: CSS customization
# class "nested-subtasks border rounded p-4"
# Subtask fields
field :title do
label "Subtask"
placeholder "e.g., Research competitors"
required true
end
field :description do
label "Notes"
type :textarea
rows 2
end
field :completed do
label "Done?"
type :checkbox
end
field :priority do
label "Priority"
type :select
options: [
{"Low", :low},
{"Medium", :medium},
{"High", :high}
]
end
end
# ─────────────────────────────────────────────────────────────────────────
# NESTED FORM: Checklist Items (has_many - simple)
# ─────────────────────────────────────────────────────────────────────────
nested :checklist_items do
label "Checklist"
cardinality :many
add_label "Add Item"
field :text do
label "Item"
required true
end
field :checked do
label "Checked"
type :checkbox
end
end
end
end
# ─────────────────────────────────────────────────────────────────────────────
# SUBTASK RESOURCE
# ─────────────────────────────────────────────────────────────────────────────
defmodule MyApp.Todos.Subtask do
use Ash.Resource,
domain: MyApp.Todos,
data_layer: AshPostgres.DataLayer
attributes do
uuid_primary_key :id
attribute :title, :string, allow_nil?: false
attribute :description, :text
attribute :completed, :boolean, default: false
attribute :priority, :atom, constraints: [one_of: [:low, :medium, :high]]
attribute :position, :integer, default: 0 # For ordering
end
relationships do
belongs_to :task, MyApp.Todos.Task
end
actions do
create :create do
accept [:title, :description, :completed, :priority, :position]
end
update :update do
accept [:title, :description, :completed, :priority, :position]
end
destroy :destroy do
primary? true
end
end
end
# =============================================================================
# PART 2: MANY_TO_MANY (Combobox - Select from Existing)
# =============================================================================
#
# Use `many_to_many` when:
# - Linking to existing records
# - The related record has independent lifecycle
# - Examples: Task → Users (assignees), Task → Tags, Product → Categories
#
# =============================================================================
defmodule MyApp.Todos.Task do
# ... (previous code)
relationships do
# ─────────────────────────────────────────────────────────────────────────
# MANY_TO_MANY: Assignees (Users)
# ─────────────────────────────────────────────────────────────────────────
# Select from existing users, cannot create users from task form
many_to_many :assignees, MyApp.Accounts.User do
through MyApp.Todos.TaskAssignee
source_attribute_on_join_resource :task_id
destination_attribute_on_join_resource :user_id
end
# ─────────────────────────────────────────────────────────────────────────
# MANY_TO_MANY: Tags (Creatable!)
# ─────────────────────────────────────────────────────────────────────────
# Select existing OR create new tags on-the-fly
many_to_many :tags, MyApp.Todos.Tag do
through MyApp.Todos.TaskTag
source_attribute_on_join_resource :task_id
destination_attribute_on_join_resource :tag_id
end
# ─────────────────────────────────────────────────────────────────────────
# MANY_TO_MANY: Related Tasks
# ─────────────────────────────────────────────────────────────────────────
# Self-referential: tasks can link to other tasks
many_to_many :related_tasks, MyApp.Todos.Task do
through MyApp.Todos.TaskRelation
source_attribute_on_join_resource :from_task_id
destination_attribute_on_join_resource :to_task_id
end
end
# ===========================================================================
# FORM DSL - MANY_TO_MANY FIELDS
# ===========================================================================
form do
action :create
# ─────────────────────────────────────────────────────────────────────────
# STANDARD COMBOBOX: Select from existing users
# ─────────────────────────────────────────────────────────────────────────
field :assignees do
type :multiselect_combobox
label "Assignees"
placeholder "Search users..."
opts [
# Search event for LiveView handler
search_event: "search_users",
debounce: 300,
# Field mappings
label_key: :name, # Display user.name
value_key: :id, # Use user.id as value
# Optional: Preload options (for small datasets < 100)
# preload_options: fn -> MyApp.Accounts.list_users() |> Enum.map(&{&1.name, &1.id}) end
hint: "Who should work on this task?"
]
end
# ─────────────────────────────────────────────────────────────────────────
# CREATABLE COMBOBOX: Tags (create on-the-fly)
# ─────────────────────────────────────────────────────────────────────────
field :tags do
type :multiselect_combobox
label "Tags"
placeholder "Search or create tags..."
opts [
# ★ Enable creating new tags
creatable: true,
create_action: :create,
create_label: "Create \"",
search_event: "search_tags",
debounce: 300,
label_key: :name,
value_key: :id,
hint: "Add tags or create new ones instantly"
]
end
# ─────────────────────────────────────────────────────────────────────────
# FILTERED COMBOBOX: Related Tasks
# ─────────────────────────────────────────────────────────────────────────
# Only show tasks that meet certain criteria
field :related_tasks do
type :multiselect_combobox
label "Related Tasks"
placeholder "Search tasks..."
opts [
search_event: "search_related_tasks",
debounce: 300,
label_key: :title,
value_key: :id,
# Pass metadata for filtering
filter_params: [
exclude_completed: true,
exclude_self: true # Don't show current task
],
hint: "Link to related tasks"
]
end
end
end
# =============================================================================
# PART 3: LIVEVIEW - HANDLING SEARCH & FILTERING
# =============================================================================
defmodule MyAppWeb.TaskLive.Form do
use MyAppWeb, :live_view
alias MyApp.Todos
alias MyApp.Todos.Task
# ───────────────────────────────────────────────────────────────────────────
# MOUNT - With Preloaded Options
# ───────────────────────────────────────────────────────────────────────────
def mount(%{"id" => id}, _session, socket) do
# EDIT: Load existing task with relationships
task = Todos.get_task!(id, load: [:assignees, :tags, :subtasks, :checklist_items])
form = Task.Form.for_update(task, actor: socket.assigns.current_user)
{:ok,
socket
|> assign(:form, form)
|> assign(:task, task)
# Preload some combobox options if needed
|> assign(:user_options, load_user_options())}
end
def mount(_params, _session, socket) do
# CREATE: New task
form = Task.Form.for_create(actor: socket.assigns.current_user)
{:ok,
socket
|> assign(:form, form)
|> assign(:user_options, load_user_options())}
end
# ───────────────────────────────────────────────────────────────────────────
# SEARCH HANDLERS - With Filtering Logic
# ───────────────────────────────────────────────────────────────────────────
@impl true
def handle_event("search_users", %{"query" => query}, socket) do
# FILTER: Only active users, search by name/email
users =
MyApp.Accounts.User
|> Ash.Query.filter(status == :active) # ← Condition 1
|> Ash.Query.filter(contains(name: ^query) or contains(email: ^query))
|> Ash.Query.limit(20) # ← Limit results
|> Todos.read!(actor: socket.assigns.current_user)
options = Enum.map(users, &{&1.name, &1.id})
{:noreply, push_event(socket, "update_combobox_options", %{
field: "assignees",
options: options
})}
end
@impl true
def handle_event("search_tags", %{"query" => query}, socket) do
# For creatable combobox - search existing tags
tags =
MyApp.Todos.Tag
|> Ash.Query.filter(contains(name: ^query))
|> Ash.Query.limit(50)
|> Todos.read!(actor: socket.assigns.current_user)
options = Enum.map(tags, &{&1.name, &1.id})
{:noreply, push_event(socket, "update_combobox_options", %{
field: "tags",
options: options
})}
end
@impl true
def handle_event("search_related_tasks", %{"query" => query, "filter_params" => filter_params}, socket) do
# FILTER: Complex query with multiple conditions
query_builder = MyApp.Todos.Task |> Ash.Query.filter(id != ^socket.assigns.task.id)
# Apply filters from filter_params
query_builder =
if filter_params["exclude_completed"] == "true" do
Ash.Query.filter(query_builder, status != :done)
else
query_builder
end
query_builder =
if filter_params["exclude_self"] == "true" do
Ash.Query.filter(query_builder, id != ^socket.assigns.task.id)
else
query_builder
end
# Search by title
tasks =
query_builder
|> Ash.Query.filter(contains(title: ^query))
|> Ash.Query.order_by(created_at: :desc)
|> Ash.Query.limit(20)
|> Todos.read!(actor: socket.assigns.current_user)
options = Enum.map(tasks, &{&1.title, &1.id})
{:noreply, push_event(socket, "update_combobox_options", %{
field: "related_tasks",
options: options
})}
end
# ───────────────────────────────────────────────────────────────────────────
# CREATE NEW ITEM (Creatable Combobox)
# ───────────────────────────────────────────────────────────────────────────
@impl true
def handle_event("create_combobox_item", %{
"field" => "tags",
"creatable_value" => tag_name
}, socket) do
# Create new tag on-the-fly
case Todos.create_tag(%{name: tag_name}, actor: socket.assigns.current_user) do
{:ok, new_tag} ->
# Add to current selection
form = socket.assigns.form.source
current_tags = AshPhoenix.Form.value(form, :tags) || []
updated_tags = Enum.uniq(current_tags ++ [new_tag.id])
form = AshPhoenix.Form.validate(form, %{tags: updated_tags})
{:noreply, assign(socket, form: to_form(form))}
{:error, changeset} ->
# Handle error (e.g., duplicate name)
{:noreply, put_flash(socket, :error, "Could not create tag: #{inspect(changeset.errors)}")}
end
end
# ───────────────────────────────────────────────────────────────────────────
# SUCCESS HANDLER
# ───────────────────────────────────────────────────────────────────────────
@impl true
def handle_info({:form_submitted, Task, task}, socket) do
{:noreply,
socket
|> put_flash(:info, "Task saved successfully!")
|> push_navigate(to: ~p"/tasks/#{task.id}")}
end
# ───────────────────────────────────────────────────────────────────────────
# HELPERS
# ───────────────────────────────────────────────────────────────────────────
defp load_user_options do
# Preload active users for small teams
MyApp.Accounts.User
|> Ash.Query.filter(status == :active)
|> Ash.Query.limit(100)
|> Todos.read!()
|> Enum.map(&{&1.name, &1.id})
end
end
# =============================================================================
# PART 4: ADVANCED - CONDITIONAL & DYNAMIC BEHAVIOR
# =============================================================================
# ─────────────────────────────────────────────────────────────────────────────
# 4.1 CONDITIONAL NESTED FORMS
# ─────────────────────────────────────────────────────────────────────────────
# Show/hide nested forms based on parent field value
defmodule MyApp.Todos.Project do
use Ash.Resource,
domain: MyApp.Todos,
extensions: [AshFormBuilder]
attributes do
uuid_primary_key :id
attribute :name, :string, allow_nil?: false
attribute :type, :atom, constraints: [one_of: [:simple, :complex]]
end
relationships do
has_many :phases, MyApp.Todos.Phase
has_many :tasks, MyApp.Todos.Task
end
actions do
create :create do
accept [:name, :type]
manage_relationship :phases, :phases, type: :create
manage_relationship :tasks, :tasks, type: :create
end
end
form do
action :create
field :name do
label "Project Name"
required true
end
field :type do
label "Project Type"
type :select
options: [
{"Simple (No Phases)", :simple},
{"Complex (With Phases)", :complex}
]
# This will trigger conditional rendering in LiveView
phx_change: "type_changed"
end
# ────────────────────────────────────────────────────────────────────────
# CONDITIONAL: Only show phases for complex projects
# ────────────────────────────────────────────────────────────────────────
#
# In LiveView, you can conditionally render:
#
# <%= if @form.source.data.type == :complex do %>
# <.nested_form :for={phase <- @form[:phases]} ... />
# <% end %>
#
# Or use phx-change to show/hide dynamically
nested :phases do
label "Project Phases"
cardinality :many
field :name do
label "Phase Name"
required true
end
field :order do
label "Order"
type :number
end
end
end
end
# ─────────────────────────────────────────────────────────────────────────────
# 4.2 DYNAMIC LIMITS - Min/Max Nested Items
# ─────────────────────────────────────────────────────────────────────────────
defmodule MyApp.Todos.Event do
use Ash.Resource,
domain: MyApp.Todos,
extensions: [AshFormBuilder]
attributes do
uuid_primary_key :id
attribute :name, :string, allow_nil?: false
end
relationships do
has_many :speakers, MyApp.Todos.Speaker
end
form do
action :create
field :name do
label "Event Name"
required true
end
# ────────────────────────────────────────────────────────────────────────
# NESTED WITH LIMITS
# ────────────────────────────────────────────────────────────────────────
nested :speakers do
label "Speakers"
cardinality :many
# ★ Enforce minimum 1 speaker
# Note: You'll need to validate this in your action
# validate present(:speakers) or length(:speakers) >= 1
# ★ Hide add button after max reached
# In LiveView:
# <%= if length(@form[:speakers].value) < 5 do %>
# <button phx-click="add_form">Add Speaker</button>
# <% end %>
field :name do
label "Speaker Name"
required true
end
field :title do
label "Title"
placeholder "e.g., CEO at Acme Corp"
end
end
end
end
# ─────────────────────────────────────────────────────────────────────────────
# 4.3 FILTERED OPTIONS - Query-Based Limiting
# ─────────────────────────────────────────────────────────────────────────────
defmodule MyApp.Todos.Meeting do
use Ash.Resource,
domain: MyApp.Todos,
extensions: [AshFormBuilder]
attributes do
uuid_primary_key :id
attribute :title, :string, allow_nil?: false
attribute :meeting_type, :atom, constraints: [one_of: [:internal, :external, :all_hands]]
end
relationships do
# Only show users from same organization
many_to_many :attendees, MyApp.Accounts.User do
through MyApp.Todos.MeetingAttendee
end
# Only show rooms that are available
many_to_many :rooms, MyApp.Resources.Room do
through MyApp.Todos.MeetingRoom
end
end
form do
action :create
field :title do
label "Meeting Title"
required true
end
field :meeting_type do
label "Meeting Type"
type :select
options: [
{"Internal", :internal},
{"External", :external},
{"All Hands", :all_hands}
]
# Trigger filter update when changed
phx_change: "meeting_type_changed"
end
# ────────────────────────────────────────────────────────────────────────
# FILTERED: Attendees by organization
# ────────────────────────────────────────────────────────────────────────
field :attendees do
type :multiselect_combobox
label "Attendees"
placeholder "Search attendees..."
opts [
search_event: "search_attendees",
debounce: 300,
label_key: :name,
value_key: :id,
# Pass filter params to search handler
filter_params: [
organization_id: :current_user_org, # Special value resolved in LiveView
active_only: true
]
]
end
# ────────────────────────────────────────────────────────────────────────
# FILTERED: Rooms by capacity and availability
# ────────────────────────────────────────────────────────────────────────
field :rooms do
type :multiselect_combobox
label "Rooms"
placeholder "Search rooms..."
opts [
search_event: "search_rooms",
debounce: 300,
label_key: :name,
value_key: :id,
filter_params: [
min_capacity: 10, # Could be dynamic based on attendee count
available: true
]
]
end
end
end
# LiveView handler for filtered attendees
defmodule MyAppWeb.MeetingLive.Form do
use MyAppWeb, :live_view
@impl true
def handle_event("search_attendees", %{"query" => query}, socket) do
# Get current user's organization
current_user = socket.assigns.current_user
org_id = current_user.organization_id
# Filter by organization and active status
users =
MyApp.Accounts.User
|> Ash.Query.filter(organization_id == ^org_id)
|> Ash.Query.filter(status == :active)
|> Ash.Query.filter(contains(name: ^query) or contains(email: ^query))
|> Ash.Query.limit(50)
|> MyApp.Accounts.read!()
options = Enum.map(users, &{&1.name, &1.id})
{:noreply, push_event(socket, "update_combobox_options", %{
field: "attendees",
options: options
})}
end
@impl true
def handle_event("search_rooms", %{"query" => query}, socket) do
# Get filter params from form
# In real app, calculate based on attendee count
min_capacity = 10
rooms =
MyApp.Resources.Room
|> Ash.Query.filter(capacity >= ^min_capacity)
|> Ash.Query.filter(available == true)
|> Ash.Query.filter(contains(name: ^query))
|> Ash.Query.limit(20)
|> MyApp.Resources.read!()
options = Enum.map(rooms, &{&1.name, &1.id})
{:noreply, push_event(socket, "update_combobox_options", %{
field: "rooms",
options: options
})}
end
end
# ─────────────────────────────────────────────────────────────────────────────
# 4.4 DYNAMIC PRELOADING - Load Options on Mount
# ─────────────────────────────────────────────────────────────────────────────
defmodule MyAppWeb.TaskLive.Form do
use MyAppWeb, :live_view
@impl true
def mount(_params, _session, socket) do
form = Task.Form.for_create(actor: socket.assigns.current_user)
# Preload options for small datasets
# This avoids initial empty combobox
{:ok,
socket
|> assign(:form, form)
|> assign(:initial_tag_options, preload_tags(""))
|> assign(:initial_user_options, preload_active_users(""))}
end
@impl true
def handle_event("search_tags", %{"query" => query}, socket) do
# For creatable combobox, always allow creating even if no results
tags = preload_tags(query)
options = Enum.map(tags, &{&1.name, &1.id})
{:noreply, push_event(socket, "update_combobox_options", %{
field: "tags",
options: options,
# Tell frontend this is creatable
creatable: true
})}
end
defp preload_tags(query) do
MyApp.Todos.Tag
|> Ash.Query.filter(contains(name: ^query))
|> Ash.Query.limit(50)
|> MyApp.Todos.read!()
end
defp preload_active_users(query) do
MyApp.Accounts.User
|> Ash.Query.filter(status == :active)
|> Ash.Query.filter(contains(name: ^query))
|> Ash.Query.limit(100)
|> MyApp.Accounts.read!()
end
end
# =============================================================================
# PART 5: SUMMARY - HAS_MANY vs MANY_TO_MANY
# =============================================================================
#
# ┌─────────────────────────────────────────────────────────────────────────┐
# │ HAS_MANY (Nested Forms) │
# ├─────────────────────────────────────────────────────────────────────────┤
# │ • Child records have independent lifecycle │
# │ • You manage child attributes in the form │
# │ • Dynamic add/remove with nested forms │
# │ • Examples: Subtasks, OrderItems, Comments │
# │ │
# │ Usage: │
# │ nested :subtasks do │
# │ cardinality :many │
# │ field :title, required: true │
# │ end │
# └─────────────────────────────────────────────────────────────────────────┘
#
# ┌─────────────────────────────────────────────────────────────────────────┐
# │ MANY_TO_MANY (Combobox) │
# ├─────────────────────────────────────────────────────────────────────────┤
# │ • Link to existing independent records │
# │ • Select from searchable dropdown │
# │ • Can be creatable (create on-the-fly) │
# │ • Examples: Tags, Assignees, Categories │
# │ │
# │ Usage: │
# │ field :tags do │
# │ type :multiselect_combobox │
# │ opts [creatable: true, search_event: "search_tags"] │
# │ end │
# └─────────────────────────────────────────────────────────────────────────┘
#
# ┌─────────────────────────────────────────────────────────────────────────┐
# │ FILTERING & LIMITING │
# ├─────────────────────────────────────────────────────────────────────────┤
# │ • Search handlers filter results via Ash.Query │
# │ • Pass filter_params through combobox opts │
# │ • Limit results with Ash.Query.limit() │
# │ • Conditional rendering in LiveView based on field values │
# │ • Min/max items enforced in UI and validated in actions │
# └─────────────────────────────────────────────────────────────────────────┘
#
# =============================================================================
# END OF RELATIONSHIPS GUIDE
# =============================================================================
