AshPhoenix

By default, AshPhoenix ignores the args option in a resource's define block when building forms. To use positional arguments (which prevents certain values from being editable via the form), you must explicitly configure them in a forms block within the resource.

This is useful for passing values like user_id that should be part of the action but should not be user-editable in the UI.

# In your resource
resource MyApp.Accounts.User do
  # ...
  forms do
    form :register_with_password, args: [:email]
  end
end

# Usage in your domain/controller
MyApp.Accounts.form_to_register_with_password(email, ...opts)

AshPhoenix is an integration package designed to bridge the Ash Framework with the Phoenix Framework. It enables developers to leverage Phoenix's UI capabilities (such as Forms and LiveViews) while utilizing Ash's data management features.

Key integration points include:

• AshPhoenix.Form: Tools for integrating Ash resources with Phoenix forms.
• AshPhoenix.LiveView: Tools for integrating Ash resources with Phoenix LiveViews.

When building a form for a union type, you use inputs_for as you normally would. AshPhoenix handles the underlying complexity of the union automatically.

To track which member of the union is currently selected, AshPhoenix uses a hidden parameter named _union_type. You can use this parameter in your templates to conditionally render different input fields based on the active union type.

<.inputs_for :let={fc} field={@form[:content]}>
  <!-- Use fc[:_union_type] to determine which fields to show -->
  <%= case fc.params["_union_type"] do %>
    <% "normal" -> %>
      <.input type="text" field={fc[:body]} />
    <% "special" -> %>
      <.input type="text" field={fc[:text]} />
  <% end %>
</.inputs_for>

AshPhoenix is designed to be driven by your Ash resource configuration. To ensure forms and inputs work effectively, focus on defining well-structured resources. Specifically, ensure your resources have:

• Appropriate validations to handle input errors.
• Clear changes to manage data transformations and side effects.

By making the resource the 'source of truth' for business logic, AshPhoenix can automatically derive much of the UI behavior.

If your code interface defines custom_input with a transform block, the generated form functions will honor these transformations for the function arguments, but will NOT apply them to the params map.

This means if an argument is transformed from a struct to an ID, the form will expect the ID for that argument, while the params map remains a raw key-value store of input data.

# In your domain
resource MyApp.Blog.Comment do
  define :create_with_post do
    action :create_with_post_id
    args [:post]

    custom_input :post, :struct do
      constraints instance_of: MyApp.Blog.Post
      transform to: :post_id, using: & &1.id
    end
  end
end

# Usage: The post struct is transformed to post_id in the form,
# but the params remain unchanged.
form = MyApp.Blog.form_to_create_with_post(
  %MyApp.Blog.Post{id: "some-id"},
  params: %{"text" => "Hello world"}
)

When using AshPhoenix.Form within a Phoenix LiveView, you should handle the result of AshPhoenix.Form.submit/2 to manage both successful submissions and validation errors.

• On Success ({:ok, result}): Proceed with your success logic (e.g., redirecting or showing a success message).
• On Error ({:error, form}): Re-assign the returned form to the socket. This updated form contains the validation error messages, which can then be rendered in your template to show users what went wrong.

# In your LiveView
def handle_event("submit", %{"form" => params}, socket) do
  case AshPhoenix.Form.submit(socket.assigns.form, params: params) do
    {:ok, post} ->
      # Success path
      {:noreply, success_path(socket, post)}

    {:error, form} ->
      # Show validation errors
      {:noreply, assign(socket, form: form)}
  end
end