AshPhoenix.Form (ash_phoenix v0.6.0-rc.3) View Source
A module to allow you to fluidly use resources with phoenix forms.
The general workflow is, with either liveview or phoenix forms:
- Create a form with
AshPhoenix.Form
- Render that form with Phoenix's
form_for
(or, if using surface, <Form>) - To validate the form (e.g with
on-change
for liveview), pass the input toAshPhoenix.Form.validate(form, params)
- On form submission, pass the input to
AshPhoenix.Form.validate(form, params)
and then useAshPhoenix.Form.submit(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 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/2
, but raises an error if the submission fails.
Validates the parameters against the form.
Gets the value for a given field in the form.
Link to this section Types
Specs
t() :: %AshPhoenix.Form{ action: atom(), added?: term(), any_removed?: term(), api: term(), changed?: term(), data: nil | Ash.Resource.record(), errors: boolean(), form_keys: Keyword.t(), forms: map(), id: term(), just_submitted?: boolean(), manage_relationship_source_changeset: term(), method: String.t(), name: term(), opts: Keyword.t(), original_data: term(), params: map(), resource: Ash.Resource.t(), source: Ash.Changeset.t() | Ash.Query.t(), submit_errors: Keyword.t() | nil, submitted_once?: boolean(), touched_forms: term(), 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
Specs
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:
- 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. - 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 isfalse
.:params
- The initial parameters to add the form with. The default value is%{}
.:type
- Iftype
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
Specs
errors(t(), Keyword.t()) :: ([{atom(), {String.t(), Keyword.t()}}] | [String.t()] | [{atom(), String.t()}]) | %{ required(list()) => [{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
- Values::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]
orform[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 `[]`.
Specs
Calls the corresponding for_*
function depending on the action type
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. Seefor_create/3
"Nested Form Options" docs for more.:api
- The api module to use for form submission. If not set, calls toForm.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 implementAshPhoenix.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 topost
for creates, andput
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.Form.Auto
for more information. If you want to do some
manipulation of the auto forms, you can also call AshPhoenix.Form.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
.:sparse?
- If the nested form issparse
, the form won't expect all inputs for all forms to be present.
Has no effect if the type is:single
.
Normally, if you leave some forms out of a list of nested forms, they are removed from the parameters passed to the action. For example, if you had apost
with two comments[%Comment{id: 1}, %Comment{id: 2}]
and you passed down params likecomments[0][id]=1&comments[1][text]=new_text
, we would remove the second comment from the input parameters, resulting in the following being passed into the action:%{"comments" => [%{"id" => 1, "text" => "new"}]}
. By setting it to sparse, you have to explicitly useremove_form
for that removal to happen. So in the same scenario above, the parameters that would be sent would actually be%{"comments" => [%{"id" => 1, "text" => "new"}, %{"id" => 2}]}
.
One major difference withsparse?
is that the form actually ignores the index provided, e.gcomments[0]...
, and instead uses the primary key e.gcomments[0][id]
to match which form is being updated. This prevents you from having to find the index of the specific item you want to update. Which could be very gnarly on deeply nested forms. If there is no primary key, or the primary key does not match anything, it is treated as a new form.
REMEMBER: You need to usehidden_inputs_for
(orHiddenInputs
if using surface) for the id to be automatically placed into the form.: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 isfalse
.: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 ifmerge?
istrue
.:resource
- The resource of the nested forms. Unnecessary if you are providing thedata
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 useadd_form/3
with this path.:update_action
- The update action to use when building forms for data. Only necessary if you supply thedata
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.
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. Seefor_create/3
"Nested Form Options" docs for more.:api
- The api module to use for form submission. If not set, calls toForm.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 implementAshPhoenix.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 topost
for creates, andput
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.
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. Seefor_create/3
"Nested Form Options" docs for more.:api
- The api module to use for form submission. If not set, calls toForm.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 implementAshPhoenix.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 topost
for creates, andput
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
.:sparse?
- If the nested form issparse
, the form won't expect all inputs for all forms to be present.
Has no effect if the type is:single
.
Normally, if you leave some forms out of a list of nested forms, they are removed from the parameters passed to the action. For example, if you had apost
with two comments[%Comment{id: 1}, %Comment{id: 2}]
and you passed down params likecomments[0][id]=1&comments[1][text]=new_text
, we would remove the second comment from the input parameters, resulting in the following being passed into the action:%{"comments" => [%{"id" => 1, "text" => "new"}]}
. By setting it to sparse, you have to explicitly useremove_form
for that removal to happen. So in the same scenario above, the parameters that would be sent would actually be%{"comments" => [%{"id" => 1, "text" => "new"}, %{"id" => 2}]}
.
One major difference withsparse?
is that the form actually ignores the index provided, e.gcomments[0]...
, and instead uses the primary key e.gcomments[0][id]
to match which form is being updated. This prevents you from having to find the index of the specific item you want to update. Which could be very gnarly on deeply nested forms. If there is no primary key, or the primary key does not match anything, it is treated as a new form.
REMEMBER: You need to usehidden_inputs_for
(orHiddenInputs
if using surface) for the id to be automatically placed into the form.: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 isfalse
.: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 ifmerge?
istrue
.:resource
- The resource of the nested forms. Unnecessary if you are providing thedata
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 useadd_form/3
with this path.:update_action
- The update action to use when building forms for data. Only necessary if you supply thedata
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.
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. Seefor_create/3
"Nested Form Options" docs for more.:api
- The api module to use for form submission. If not set, calls toForm.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 implementAshPhoenix.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 topost
for creates, andput
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
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.
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
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 isfalse
.: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.
Specs
submit!(t(), Keyword.t()) :: Ash.Resource.record() | :ok | no_return()
Same as submit/2
, but raises an error if the submission fails.
Specs
Specs
Validates the parameters against the form.
Options:
:errors
- Set to false to hide errors after validation The default value istrue
.
Specs
Gets the value for a given field in the form.