defmodule Phoenix.HTML.Form do
@moduledoc ~S"""
Define a `Phoenix.HTML.Form` struct and functions to interact with it.
For building actual forms in your Phoenix application, see
[the `Phoenix.Component.form/1` component](https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html#form/1).
## Access behaviour
The `Phoenix.HTML.Form` struct implements the `Access` behaviour.
When you do `form[field]`, it returns a `Phoenix.HTML.FormField`
struct with the `id`, `name`, `value`, and `errors` prefilled.
The field name can be either an atom or a string. If it is an atom,
it assumes the form keeps both data and errors as atoms. If it is a
string, it considers that data and errors are stored as strings for said
field. Forms backed by an `Ecto.Changeset` only support atom field names.
It is possible to "access" fields which do not exist in the source data
structure. A `Phoenix.HTML.FormField` struct will be dynamically created
with some attributes such as `name` and `id` populated.
## Custom implementations
There is a protocol named `Phoenix.HTML.FormData` which can be implemented
by any data structure that wants to be cast to the `Phoenix.HTML.Form` struct.
"""
alias Phoenix.HTML.Form
import Phoenix.HTML
@doc """
Defines the Phoenix.HTML.Form struct.
Its fields are:
* `:source` - the data structure given to `form_for/4` that
implements the form data protocol
* `:impl` - the module with the form data protocol implementation.
This is used to avoid multiple protocol dispatches.
* `:id` - the id to be used when generating input fields
* `:index` - the index of the struct in the form
* `:name` - the name to be used when generating input fields
* `:data` - the field used to store lookup data
* `:params` - the parameters associated with this form
* `:hidden` - a keyword list of fields that are required to
submit the form behind the scenes as hidden inputs
* `:options` - a copy of the options given when creating the
form via `form_for/4` without any form data specific key
* `:errors` - a keyword list of errors that are associated with
the form
"""
defstruct source: nil,
impl: nil,
id: nil,
name: nil,
data: nil,
action: nil,
hidden: [],
params: %{},
errors: [],
options: [],
index: nil
@type t :: %Form{
source: Phoenix.HTML.FormData.t(),
name: String.t(),
data: %{field => term},
action: atom(),
params: %{binary => term},
hidden: Keyword.t(),
options: Keyword.t(),
errors: [{field, term}],
impl: module,
id: String.t(),
index: nil | non_neg_integer
}
@type field :: atom | String.t()
@doc false
def fetch(%Form{} = form, field) when is_atom(field) do
fetch(form, field, Atom.to_string(field))
end
def fetch(%Form{} = form, field) when is_binary(field) do
fetch(form, field, field)
end
def fetch(%Form{}, field) do
raise ArgumentError,
"accessing a form with form[field] requires the field to be an atom or a string, got: #{inspect(field)}"
end
defp fetch(%{errors: errors} = form, field, field_as_string) do
{:ok,
%Phoenix.HTML.FormField{
errors: field_errors(errors, field),
field: field,
form: form,
id: input_id(form, field_as_string),
name: input_name(form, field_as_string),
value: input_value(form, field)
}}
end
@doc """
Returns a value of a corresponding form field.
The `form` should either be a `Phoenix.HTML.Form` or an atom.
The field is either a string or an atom. If the field is given
as an atom, it will attempt to look data with atom keys. If
a string, it will look data with string keys.
When a form is given, it will look for changes, then
fallback to parameters, and finally fallback to the default
struct/map value.
Since the function looks up parameter values too, there is
no guarantee that the value will have a certain type. For
example, a boolean field will be sent as "false" as a
parameter, and this function will return it as is. If you
need to normalize the result of `input_value`, see
`normalize_value/2`.
"""
@spec input_value(t | atom, field) :: term
def input_value(%{source: source, impl: impl} = form, field)
when is_atom(field) or is_binary(field) do
impl.input_value(source, form, field)
end
def input_value(name, _field) when is_atom(name), do: nil
@doc """
Returns an id of a corresponding form field.
The form should either be a `Phoenix.HTML.Form` emitted
by `form_for` or an atom.
"""
@spec input_id(t | atom, field) :: String.t()
def input_id(%{id: nil}, field), do: "#{field}"
def input_id(%{id: id}, field) when is_atom(field) or is_binary(field) do
"#{id}_#{field}"
end
def input_id(name, field) when (is_atom(name) and is_atom(field)) or is_binary(field) do
"#{name}_#{field}"
end
@doc """
Returns an id of a corresponding form field and value attached to it.
Useful for radio buttons and inputs like multiselect checkboxes.
"""
@spec input_id(t | atom, field, Phoenix.HTML.Safe.t()) :: String.t()
def input_id(name, field, value) do
{:safe, value} = html_escape(value)
value_id = value |> IO.iodata_to_binary() |> String.replace(~r/\W/u, "_")
input_id(name, field) <> "_" <> value_id
end
@doc """
Returns a name of a corresponding form field.
The first argument should either be a `Phoenix.HTML.Form` or an atom.
## Examples
iex> Phoenix.HTML.Form.input_name(:user, :first_name)
"user[first_name]"
"""
@spec input_name(t | atom, field) :: String.t()
def input_name(form_or_name, field)
def input_name(%{name: nil}, field), do: to_string(field)
def input_name(%{name: name}, field) when is_atom(field) or is_binary(field),
do: "#{name}[#{field}]"
def input_name(name, field) when (is_atom(name) and is_atom(field)) or is_binary(field),
do: "#{name}[#{field}]"
@doc """
Receives two forms structs and checks if the given field changed.
The field will have changed if either its associated value, errors,
action, or implementation changed. This is mostly used for optimization
engines as an extension of the `Access` behaviour.
"""
@spec input_changed?(t, t, field()) :: boolean()
def input_changed?(
%Form{
impl: impl1,
id: id1,
name: name1,
errors: errors1,
source: source1,
action: action1
} = form1,
%Form{
impl: impl2,
id: id2,
name: name2,
errors: errors2,
source: source2,
action: action2
} = form2,
field
)
when is_atom(field) or is_binary(field) do
impl1 != impl2 or id1 != id2 or name1 != name2 or action1 != action2 or
field_errors(errors1, field) != field_errors(errors2, field) or
impl1.input_value(source1, form1, field) != impl2.input_value(source2, form2, field)
end
@doc """
Returns the HTML validations that would apply to
the given field.
"""
@spec input_validations(t, field) :: Keyword.t()
def input_validations(%{source: source, impl: impl} = form, field)
when is_atom(field) or is_binary(field) do
impl.input_validations(source, form, field)
end
@doc """
Normalizes an input `value` according to its input `type`.
Certain HTML input values must be cast, or they will have idiosyncracies
when they are rendered. The goal of this function is to encapsulate
this logic. In particular:
* For "datetime-local" types, it converts `DateTime` and
`NaiveDateTime` to strings without the second precision
* For "checkbox" types, it returns a boolean depending on
whether the input is "true" or not
* For "textarea", it prefixes a newline to ensure newlines
won't be ignored on submission. This requires however
that the textarea is rendered with no spaces after its
content
"""
def normalize_value("datetime-local", %struct{} = value)
when struct in [NaiveDateTime, DateTime] do
<<date::10-binary, ?\s, hour_minute::5-binary, _rest::binary>> = struct.to_string(value)
{:safe, [date, ?T, hour_minute]}
end
def normalize_value("textarea", value) do
{:safe, value} = html_escape(value || "")
{:safe, [?\n | value]}
end
def normalize_value("checkbox", value) do
html_escape(value) == {:safe, "true"}
end
def normalize_value(_type, value) do
value
end
@doc """
Returns options to be used inside a select.
This is useful when building the select by hand.
It expects all options and one or more select values.
## Examples
options_for_select(["Admin": "admin", "User": "user"], "admin")
#=> <option value="admin" selected>Admin</option>
#=> <option value="user">User</option>
Multiple selected values:
options_for_select(["Admin": "admin", "User": "user", "Moderator": "moderator"],
["admin", "moderator"])
#=> <option value="admin" selected>Admin</option>
#=> <option value="user">User</option>
#=> <option value="moderator" selected>Moderator</option>
Groups are also supported:
options_for_select(["Europe": ["UK", "Sweden", "France"], ...], nil)
#=> <optgroup label="Europe">
#=> <option>UK</option>
#=> <option>Sweden</option>
#=> <option>France</option>
#=> </optgroup>
"""
def options_for_select(options, selected_values) do
{:safe,
escaped_options_for_select(
options,
selected_values |> List.wrap() |> Enum.map(&html_escape/1)
)}
end
defp escaped_options_for_select(options, selected_values) do
Enum.reduce(options, [], fn
{option_key, option_value}, acc ->
[acc | option(option_key, option_value, [], selected_values)]
options, acc when is_list(options) ->
{option_key, options} = Keyword.pop(options, :key)
option_key ||
raise ArgumentError,
"expected :key key when building <option> from keyword list: #{inspect(options)}"
{option_value, options} = Keyword.pop(options, :value)
option_value ||
raise ArgumentError,
"expected :value key when building <option> from keyword list: #{inspect(options)}"
[acc | option(option_key, option_value, options, selected_values)]
option, acc ->
[acc | option(option, option, [], selected_values)]
end)
end
defp option(group_label, group_values, [], value)
when is_list(group_values) or is_map(group_values) do
section_options = escaped_options_for_select(group_values, value)
option_tag("optgroup", [label: group_label], {:safe, section_options})
end
defp option(option_key, option_value, extra, value) do
option_key = html_escape(option_key)
option_value = html_escape(option_value)
attrs = extra ++ [selected: option_value in value, value: option_value]
option_tag("option", attrs, option_key)
end
defp option_tag(name, attrs, {:safe, body}) when is_binary(name) and is_list(attrs) do
{:safe, attrs} = Phoenix.HTML.attributes_escape(attrs)
[?<, name, attrs, ?>, body, ?<, ?/, name, ?>]
end
# Helper for getting field errors, handling string fields
defp field_errors(errors, field)
when is_list(errors) and (is_atom(field) or is_binary(field)) do
for {^field, error} <- errors, do: error
end
end
