=============================================================================

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

=============================================================================