AshPhoenix.Form (ash_phoenix v0.5.7) View Source

A module to allow you to fluidly use resources with phoenix forms.

The general workflow is, with either liveview or phoenix forms:

  1. Create a form with AshPhoenix.Form
  2. Render that form with Phoenix's form_for (or, if using surface, <Form>)
  3. To validate the form (e.g with on-change for liveview), pass the input to AshPhoenix.Form.validate(form, params)
  4. On form submission, pass the input to AshPhoenix.Form.validate(form, params) and then use AshPhoenix.Form.submid(form, ApiModule)

If your resource action accepts related data, (for example a managed relationship argument, or an embedded resource attribute), you can use Phoenix's inputs_for for that field, but you must explicitly configure the behavior of it using the forms option. See Form.for_create/3 for more.

For example:

form =
  user
  |> AshPhoenix.Form.for_update(:update,
    api: MyApi,
    forms: [
      profile: [
        resource: MyApp.Profile,
        data: user.profile,
        create_action: :create,
        update_action: :update
        forms: [
          emails: [
            data: user.profile.emails,
            resource: MyApp.UserEmail,
            create_action: :create,
            update_action: :update
          ]
        ]
      ]
    ])

LiveView

AshPhoenix.Form (unlike ecto changeset based forms) expects to be reused throughout the lifecycle of the liveview.

You can use phoenix events to add and remove form entries and submit/2 to submit the form, like so:

alias MyApp.MyApi.{Comment, Post}

def render(assigns) do
  ~L"""
  <%= f = form_for @form, "#", [phx_change: :validate, phx_submit: :save] %>
    <%= label f, :text %>
    <%= text_input f, :text %>
    <%= error_tag f, :text %>

    <%= for comment_form <- inputs_for(f, :comments) do %>
      <%= hidden_inputs_for(comment_form) %>
      <%= text_input comment_form, :text %>

      <%= for sub_comment_form <- inputs_for(comment_form, :sub_comments) do %>
        <%= hidden_inputs_for(sub_comment_form) %>
        <%= text_input sub_comment_form, :text %>
        <button phx-click="remove_form" phx-value-path="<%= sub_comment_form.name %>">Add Comment</button>
      <% end %>

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

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

    <%= submit "Save" %>
  </form>
  """
end

def mount(%{"post_id" => post_id}, _session, socket) do
  post =
    Post
    |> MyApp.MyApi.get!(post_id)
    |> MyApi.load!(comments: [:sub_comments])

  form = AshPhoenix.Form.for_update(post,
    api: MyApp.MyApi,
    forms: [
      comments: [
        resource: Comment,
        data: post.comments,
        create_action: :create,
        update_action: :update
        forms: [
          sub_comments: [
            resource: Comment,
            data: &(&1.sub_comments),
            create_action: :create,
            update_action: :update
          ]
        ]
      ]
    ])

  {:ok, assign(socket, form: form)}
end

# In order to use the `add_form` and `remove_form` helpers, you
# need to make sure that you are validating the form on change
def handle_event("validate", %{"form" => params}, socket) do
  form = AshPhoenix.Form.validate(socket.assigns.form, params)
  # You can also skip errors by setting `errors: false` if you only want to show errors on submit
  # form = AshPhoenix.Form.validate(socket.assigns.form, params, errors: false)

  {:ok, assign(socket, :form, form)}
end

def handle_event("save", _params, socket) do
  case AshPhoenix.Form.submit(socket.assigns.form) do
    {:ok, result} ->
      # Do something with the result, like redirect
    {:error, form} ->
      assign(socket, :form, form)
  end
end

def handle_event("add_form", %{"path" => path}, socket) do
  form = AshPhoenix.Form.add_form(socket.assigns.form, path)
  {:noreply, assign(socket, :form, form)}
end

def handle_event("remove_form", %{"path" => path}) do
  form = AshPhoenix.Form.remove_form(socket.assigns.form, path)
  {:noreply, assign(socket, :form, form)}
end

Link to this section Summary

Functions

Adds a new form at the provided path.

A utility to get the list of arguments the action underlying the form accepts

A utility to get the list of attributes the action underlying the form accepts

Returns the errors on the form.

Calls the corresponding for_* function depending on the action type

Creates a form corresponding to a create action on a resource.

Creates a form corresponding to a destroy action on a record.

Creates a form corresponding to a read action on a resource.

Creates a form corresponding to an update action on a record.

Returns the parameters from the form that would be submitted to the action.

A utility for parsing paths of nested forms in query encoded format.

Removes a form at the provided path.

Sets the data of the form, in addition to the data of the underlying source, if applicable.

Submits the form by calling the appropriate function on the configured api.

Same as submit/3, but raises an error if the submission fails.

Validates the parameters against the form.

Link to this section Types

Specs

t() :: %AshPhoenix.Form{
  action: atom(),
  api: term(),
  data: nil | Ash.Resource.record(),
  data_updates: [prepend: [atom() | integer()], remove: [atom() | integer()]],
  errors: boolean(),
  form_keys: Keyword.t(),
  forms: map(),
  id: term(),
  just_submitted?: boolean(),
  method: String.t(),
  name: term(),
  opts: Keyword.t(),
  params: map(),
  resource: Ash.Resource.t(),
  source: Ash.Changeset.t() | Ash.Query.t(),
  submit_errors: Keyword.t() | nil,
  submitted_once?: boolean(),
  transform_errors:
    nil
    | (Ash.Changeset.t() | Ash.Query.t(), error :: Ash.Error.t() ->
         [
           {field :: atom(), message :: String.t(),
            substituations :: Keyword.t()}
         ]),
  type: :create | :update | :destroy | :read,
  valid?: boolean()
}

Link to this section Functions

Link to this function

add_form(form, path, opts \\ [])

View Source

Specs

add_form(t(), String.t() | [atom() | integer()], Keyword.t()) :: t()

Adds a new form at the provided path.

Doing this requires that the form has a create_action and a resource configured.

path can be one of two things:

  1. A list of atoms and integers that lead to a form in the forms option provided. [:posts, 0, :comments] to add a comment to the first post.
  2. The html name of the form, e.g form[posts][0][comments] to mimic the above
  • :prepend - If specified, the form is placed at the beginning of the list instead of the end of the list The default value is false.

  • :params - The initial parameters to add the form with. The default value is %{}.

  • :type - If type is set to :read, the form will be created for a read action. A hidden field will be set in the form called _form_type to track this information. The default value is :create.

A utility to get the list of arguments the action underlying the form accepts

A utility to get the list of attributes the action underlying the form accepts

Link to this function

errors(form, opts \\ [])

View Source

Specs

errors(t(), Keyword.t()) ::
  [{atom(), {String.t(), Keyword.t()}}] | [String.t()] | [{atom(), String.t()}]

Returns the errors on the form.

By default, only errors on the form being passed in (not nested forms) are provided. Use for_path to get errors for nested forms.

  • :format - :raw - [field:, {message, substitutions}}] (for translation) :simple - [field: "message w/ variables substituted"] :plaintext - ["field: message w/ variables substituted"] The default value is:simple`.

  • :for_path - The path of the form you want errors for, either as a list or as a string, e.g [:comments, 0] or form[comments][0] Passing :all will cause this function to return a map of path to its errors, like so:

    %{[:comments, 0] => [body: "is invalid"], ...}
    ``` The default value is `[]`.
Link to this function

errors_for(form, path, type \\ :raw)

View Source
This function is deprecated. Use errors/2 instead.

Specs

errors_for(
  t(),
  [atom() | integer()] | String.t(),
  type :: :simple | :raw | :plaintext
) :: [{atom(), {String.t(), Keyword.t()}}] | [String.t()] | map() | nil
Link to this function

for_action(resource_or_data, action, opts)

View Source

Calls the corresponding for_* function depending on the action type

Link to this function

for_create(resource, action, opts \\ [])

View Source

Specs

for_create(Ash.Resource.t(), action :: atom(), opts :: Keyword.t()) :: t()

Creates a form corresponding to a create action on a resource.

Options:

  • :forms - Nested form configurations. See for_create/3 docs for more.

  • :api - The api module to use for form submission. If not set, calls to Form.submit/2 will fail

  • :as - The name of the form in the submitted params. You will need to pull the form params out using this key. The default value is "form".

  • :id - The html id of the form. Defaults to the value of :as if provided, otherwise "form"

  • :transform_errors - Allows for manual manipulation and transformation of errors.

    If possible, try to implement AshPhoenix.FormData.Error for the error (if it as a custom one, for example). If that isn't possible, you can provide this function which will get the changeset and the error, and should return a list of ash phoenix formatted errors, e.g [{field :: atom, message :: String.t(), substituations :: Keyword.t()}]

  • :method - The http method to associate with the form. Defaults to post for creates, and put for everything else.

Any additional options will be passed to the underlying call to Ash.Changeset.for_create/4. This means you can set things like the tenant/actor. These will be retained, and provided again when Form.submit/3 is called.

Nested Form Options

To automatically determine the nested forms available for a given form, use forms: [auto?: true]. You can add additional nested forms by including them in the forms config alongside auto?: true. See the module documentation of AshPhoenix.Forms.Auto for more information. If you want to do some manipulation of the auto forms, you can also call AshPhoenix.Forms.Auto.auto/2, and then manipulate the result and pass it to the forms option.

  • :type - The cardinality of the nested form. The default value is :single.

  • :forms - Forms nested inside the current nesting level in all cases

  • :for_type - What action types the form applies for. Leave blank for it to apply to all action types.

  • :merge? - When building parameters, this input will be merged with its parent input. This allows for combining multiple forms into a single input. The default value is false.

  • :for - When creating parameters for the action, the key that the forms should be gathered into. Defaults to the key used to configure the nested form. Ignored if merge? is true.

  • :resource - The resource of the nested forms. Unnecessary if you are providing the data key, and not adding additional forms to this path.

  • :create_action - The create action to use when building new forms. Only necessary if you want to use add_form/3 with this path.

  • :update_action - The update action to use when building forms for data. Only necessary if you supply the data key.

  • :data - The current value or values that should have update forms built by default.

    You can also provide a single argument function that will return the data based on the data of the parent form. This is important for multiple nesting levels of :list type forms, because the data depends on which parent is being rendered.

Link to this function

for_destroy(data, action, opts \\ [])

View Source

Specs

for_destroy(Ash.Resource.record(), action :: atom(), opts :: Keyword.t()) :: t()

Creates a form corresponding to a destroy action on a record.

Options:

  • :forms - Nested form configurations. See for_create/3 docs for more.

  • :api - The api module to use for form submission. If not set, calls to Form.submit/2 will fail

  • :as - The name of the form in the submitted params. You will need to pull the form params out using this key. The default value is "form".

  • :id - The html id of the form. Defaults to the value of :as if provided, otherwise "form"

  • :transform_errors - Allows for manual manipulation and transformation of errors.

    If possible, try to implement AshPhoenix.FormData.Error for the error (if it as a custom one, for example). If that isn't possible, you can provide this function which will get the changeset and the error, and should return a list of ash phoenix formatted errors, e.g [{field :: atom, message :: String.t(), substituations :: Keyword.t()}]

  • :method - The http method to associate with the form. Defaults to post for creates, and put for everything else.

Any additional options will be passed to the underlying call to Ash.Changeset.for_destroy/4. This means you can set things like the tenant/actor. These will be retained, and provided again when Form.submit/3 is called.

Link to this function

for_read(resource, action, opts \\ [])

View Source

Specs

for_read(Ash.Resource.t(), action :: atom(), opts :: Keyword.t()) :: t()

Creates a form corresponding to a read action on a resource.

Options:

  • :forms - Nested form configurations. See for_create/3 docs for more.

  • :api - The api module to use for form submission. If not set, calls to Form.submit/2 will fail

  • :as - The name of the form in the submitted params. You will need to pull the form params out using this key. The default value is "form".

  • :id - The html id of the form. Defaults to the value of :as if provided, otherwise "form"

  • :transform_errors - Allows for manual manipulation and transformation of errors.

    If possible, try to implement AshPhoenix.FormData.Error for the error (if it as a custom one, for example). If that isn't possible, you can provide this function which will get the changeset and the error, and should return a list of ash phoenix formatted errors, e.g [{field :: atom, message :: String.t(), substituations :: Keyword.t()}]

  • :method - The http method to associate with the form. Defaults to post for creates, and put for everything else.

Any additional options will be passed to the underlying call to Ash.Query.for_read/4. This means you can set things like the tenant/actor. These will be retained, and provided again when Form.submit/3 is called.

Keep in mind that the source of the form in this case is a query, not a changeset. This means that, very likely, you would not want to use nested forms here. However, it could make sense if you had a query argument that was an embedded resource, so the capability remains.

Nested Form Options

  • :type - The cardinality of the nested form. The default value is :single.

  • :forms - Forms nested inside the current nesting level in all cases

  • :for_type - What action types the form applies for. Leave blank for it to apply to all action types.

  • :merge? - When building parameters, this input will be merged with its parent input. This allows for combining multiple forms into a single input. The default value is false.

  • :for - When creating parameters for the action, the key that the forms should be gathered into. Defaults to the key used to configure the nested form. Ignored if merge? is true.

  • :resource - The resource of the nested forms. Unnecessary if you are providing the data key, and not adding additional forms to this path.

  • :create_action - The create action to use when building new forms. Only necessary if you want to use add_form/3 with this path.

  • :update_action - The update action to use when building forms for data. Only necessary if you supply the data key.

  • :data - The current value or values that should have update forms built by default.

    You can also provide a single argument function that will return the data based on the data of the parent form. This is important for multiple nesting levels of :list type forms, because the data depends on which parent is being rendered.

Link to this function

for_update(data, action, opts \\ [])

View Source

Specs

for_update(Ash.Resource.record(), action :: atom(), opts :: Keyword.t()) :: t()

Creates a form corresponding to an update action on a record.

Options:

  • :forms - Nested form configurations. See for_create/3 docs for more.

  • :api - The api module to use for form submission. If not set, calls to Form.submit/2 will fail

  • :as - The name of the form in the submitted params. You will need to pull the form params out using this key. The default value is "form".

  • :id - The html id of the form. Defaults to the value of :as if provided, otherwise "form"

  • :transform_errors - Allows for manual manipulation and transformation of errors.

    If possible, try to implement AshPhoenix.FormData.Error for the error (if it as a custom one, for example). If that isn't possible, you can provide this function which will get the changeset and the error, and should return a list of ash phoenix formatted errors, e.g [{field :: atom, message :: String.t(), substituations :: Keyword.t()}]

  • :method - The http method to associate with the form. Defaults to post for creates, and put for everything else.

Any additional options will be passed to the underlying call to Ash.Changeset.for_update/4. This means you can set things like the tenant/actor. These will be retained, and provided again when Form.submit/3 is called.

Specs

params(t()) :: map()

Returns the parameters from the form that would be submitted to the action.

This can be useful if you want to get the parameters and manipulate them/build a custom changeset afterwards.

Link to this function

parse_path!(form, original_path)

View Source

A utility for parsing paths of nested forms in query encoded format.

For example:

parse_path!(form, "post[comments][0][sub_comments][0])

[:comments, 0, :sub_comments, 0]

Removes a form at the provided path.

See add_form/3 for more information on the path argument.

If you are not using liveview, and you want to support removing forms that were created based on the data option from the browser, you'll need to include in the form submission a custom list of strings to remove, and then manually iterate over them in your controller, for example:

Enum.reduce(removed_form_paths, form, &AshPhoenix.Form.remove_form(&2, &1))

Sets the data of the form, in addition to the data of the underlying source, if applicable.

Queries do not track data (because that wouldn't make sense), so this will not update the data for read actions

Link to this function

submit(form, opts \\ [])

View Source

Specs

submit(t(), Keyword.t()) :: {:ok, Ash.Resource.record()} | :ok | {:error, t()}

Submits the form by calling the appropriate function on the configured api.

For example, a form created with for_update/3 will call api.update(changeset), where changeset is the result of passing the Form.params/3 into Ash.Changeset.for_update/4.

If the submission returns an error, the resulting form can simply be rerendered. Any nested errors will be passed down to the corresponding form for that input.

Options:

  • :force? - Submit the form even if it is invalid in its current state. The default value is false.

  • :params - If specified, validate/3 is called with the new params before submitting the form.

    This is a shortcut to avoid needing to explicitly validate before every submit.

    For example:

    form
    |> AshPhoenix.Form.validate(params)
    |> AshPhoenix.Form.submit()

    Is the same as:

    form
    |> AshPhoenix.Form.submit(params: params)
  • :before_submit - A function to apply to the source (changeset or query) just before submitting the action. Must return the modified changeset.

Link to this function

submit!(form, api, opts \\ [])

View Source

Same as submit/3, but raises an error if the submission fails.

Link to this function

update_form(form, path, func)

View Source

Specs

update_form(t(), [atom() | integer()] | String.t(), (t() -> t())) :: t()
Link to this function

validate(form, new_params, opts \\ [])

View Source

Specs

validate(t(), map(), Keyword.t()) :: t()

Validates the parameters against the form.

Options:

  • :errors - Set to false to hide errors after validation The default value is true.