# `AshPhoenix.Form.Auto`
[🔗](https://github.com/ash-project/ash_phoenix/blob/v2.3.21/lib/ash_phoenix/form/auto.ex#L5)

A tool to automatically generate available nested forms based on a resource and action.

To use this, specify `forms: [auto?: true]` when creating the form.

Keep in mind, you can always specify these manually when creating a form by simply specifying the `forms` option.

There are two things that this builds forms for:

1. Attributes/arguments who's type is an embedded resource.
2. Arguments that have a corresponding `change manage_relationship(..)` configured.

For more on relationships see the documentation for `Ash.Changeset.manage_relationship/4`.

When building forms, you can switch on the action type and/or resource of the form, in order to have different
fields depending on the form. For example, if you have a simple relationship called `:comments` with
`on_match: :update` and `on_no_match: :create`, there are two types of forms that can be in `inputs_for(form, :comments)`.

In which case you may have something like this:

```elixir
<%= for comment_form <- inputs_for(f, :comments) do %>
  <%= hidden_inputs_for(comment_form) %>
  <%= if comment_form.source.type == :create do %>
    <%= text_input comment_form, :text %>
    <%= text_input comment_form, :on_create_field %>
  <% else %>
    <%= text_input comment_form, :text %>
    <%= text_input comment_form, :on_update_field %>
  <% end %>

  <button phx-click="remove_form" phx-value-path="<%= comment_form.name %>">Remove Comment</button>
  <button phx-click="add_form" phx-value-path="<%= comment_form.name %>">Add Comment</button>
<% end %>
```

This also applies to adding forms of different types manually. For instance, if you had a "search" field
to allow them to search for a record (e.g in a liveview), and you had an `on_lookup` read action, you could
render a search form for that read action, and once they've selected a record, you could render the fields
to update that record (in the case of `on_lookup: :relate_and_update` configurations).

## Options

* `:relationship_fetcher` (`t:term/0`) - A two argument function that receives the parent data, the relationship to fetch.
  The default simply fetches the relationship value, and if it isn't loaded, it uses `[]` or `nil`.

* `:sparse_lists?` (`t:boolean/0`) - Sets all list type forms to `sparse?: true` by default. Has no effect on forms derived for embedded resources. The default value is `false`.

* `:include_non_map_types?` (`t:boolean/0`) - Creates form for non map or array of map type inputs The default value is `false`.

## Special Considerations

### `on_lookup: :relate_and_update`

For `on_lookup: :relate_and_update` configurations, the "read" form for that relationship will use the appropriate read action.
However, you may also want to include the relevant fields for the update that would subsequently occur. To that end, a special
nested form called `:_update` is created, that uses an empty instance of that resource as the base of its changeset. This may require
some manual manipulation of that data before rendering the relevant form because it assumes all the default values. To solve for this,
if you are using liveview, you could actually look up the record using the input from the read action, and then use `AshPhoenix.Form.update_form/3`
to set that looked up record as the data of the `_update` form.

### Many to Many Relationships

In the case that a manage_change option points to a join relationship, that form is presented via a special nested form called
`_join`. So the first form in `inputs_for(form, :relationship)` would be for the destination, and then inside of that you could say
`inputs_for(nested_form, :_join)`. The parameters are merged together during submission.

# `auto`

# `embedded`

# `related`

# `unions`

---

*Consult [api-reference.md](api-reference.md) for complete listing*