This module provides helpers to render a Form
.
If you just want to quickly render a Form
as HTML, take a look at
asHtml
. If you need more control, see custom
and htmlViewConfig
.
Note: If you are implementing your own custom fields using Form.Base
then
you cannot use this module. You should use Form.Base.fill
to write
custom view code. Take a look at the source code of this module for inspiration.
{ values : values
, state : State
, errorTracking : ErrorTracking
}
This type gathers the values of the form, with some exposed state and internal view state that tracks which fields should show validation errors.
Represents the state of the form.
You can change it at will from your update
function. For example, you can set the state to
Loading
if submitting the form fires a remote action, or you can set it to Error
when
such action fails.
update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
case msg of
FormChanged newModel ->
( { newModel | state = FormView.Idle }, Cmd.none )
SignUp email password ->
( { model | state = FormView.Loading }
, User.signUp email password
|> Task.attempt SignupTried
)
SignupTried (Ok user) ->
( { model | state = FormView.Success "You are now registered successfully :)" }, Route.navigate (Route.Profile user.slug) )
SignupTried (Err error) ->
( { model | state = FormView.Error error }, Cmd.none )
idle : values -> Model values
Create a Model
representing an idle form.
You just need to provide the initial values
of the form.
{ onChange : Model values -> msg
, action : String
, loading : String
, validation : Validation
}
This allows you to configure the view output.
onChange
specifies the message that should be produced when the Model
changes.action
is the text of the submit button when the form is not loading.loading
is the text of the submit button when the form is loading.validation
lets you choose the validation strategy.The validation strategy.
ValidateOnSubmit
will show field errors only when the user tries to submit an invalid form.ValidateOnBlur
will show field errors as fields are blurred. It uses field labels to identify fields on the form. This validation strategy will not work as expected if your form has multiple fields with the same label.asHtml : ViewConfig values msg -> Form values msg -> Model values -> Html msg
Render a form as HTML!
You could use it like this:
FormView.asHtml
{ onChange = FormChanged
, action = "Log in"
, loading = "Logging in..."
, validation = FormView.ValidateOnSubmit
}
loginForm
model
And here is an example of the produced HTML:
<form class="elm-form">
<label class="elm-form-field">
<div class="elm-form-label">E-Mail</div>
<input type="email" value="some@value.com" placeholder="Type your e-mail...">
</label>
<label class="elm-form-field elm-form-field-error">
<div class="elm-form-label">Password</div>
<input type="password" value="" placeholder="Type your password...">
<div class="elm-form-error">This field is required</div>
</label>
<button type="submit">Log in</button>
</form>
You can use the different CSS classes to style your forms as you please.
If you need more control over the produced HTML, use custom
to provide
your own view functions. To customize the behavior of individual view functions, see htmlViewConfig
.
htmlViewConfig : CustomConfig msg (Html msg)
Default CustomConfig
implementation for HTML output.
You can update a subset of the CustomConfig
fields to implement a view function that overrides the behavior of asHtml
. For example:
htmlView : ViewConfig values msg -> Form values msg -> Model values -> Html msg
htmlView =
custom
{ htmlViewConfig
| selectField = mySelectField
, radioField = myRadioField
}
In fact, asHtml
is just implemented as:
asHtml : ViewConfig values msg -> Form values msg -> Model values -> Html msg
asHtml =
custom htmlViewConfig
custom : CustomConfig msg element -> ViewConfig values msg -> Form values msg -> Model values -> element
Create a custom view function.
You need to provide a set of functions to render each field, and a function to
put them all together in a form, see CustomConfig
.
This can be used to create view functions that are compatible with style-elements
,
elm-mdl
, elm-css
, etc. You could even use it to transform forms into a String
or Json.Value
!
Take a look at the different view modules in the examples directory
as you might find an implementation that works for you.
Once you provide a CustomConfig
, you get a view function that supports
a ViewConfig
.
{ form : FormConfig msg element -> element
, textField : TextFieldConfig msg -> element
, emailField : TextFieldConfig msg -> element
, passwordField : TextFieldConfig msg -> element
, textareaField : TextFieldConfig msg -> element
, searchField : TextFieldConfig msg -> element
, numberField : NumberFieldConfig msg -> element
, rangeField : RangeFieldConfig msg -> element
, checkboxField : CheckboxFieldConfig msg -> element
, radioField : RadioFieldConfig msg -> element
, selectField : SelectFieldConfig msg -> element
, group : List element -> element
, section : String -> List element -> element
, formList : FormListConfig msg element -> element
, formListItem : FormListItemConfig msg element -> element
}
The configuration needed to create a custom view function.
It needs functions to render each of the supported Form
fields, a function to
render a group
of fields, and a function to wrap the fields together in a form
.
{ onSubmit : Maybe msg
, state : State
, action : String
, loading : String
, fields : List element
}
Describes how a form should be rendered.
onSubmit
contains the output of the form if there are no validation errors.state
is the State
of the form.action
is the main action of the form, you should probably render this in the submit button.loading
is the loading message that should be shown when the form is loading.fields
contains the already rendered fields.{ onChange : String -> msg
, onBlur : Maybe msg
, disabled : Basics.Bool
, value : String
, error : Maybe Form.Error.Error
, showError : Basics.Bool
, attributes : Form.Base.TextField.Attributes
}
Describes how a text field should be rendered.
onChange
takes a new value for the field and returns the msg
that should be produced.onBlur
might contain a msg
that should be produced when the field is blurred.disabled
tells you whether the field should be disabled or not. It is True
when the form is
loading.value
contains the current value of the field.error
might contain a field Error
.showError
tells you if you should show the error
for this particular field. Its value
depends on the validation strategy.attributes
are TextField.Attributes
.{ onChange : String -> msg
, onBlur : Maybe msg
, disabled : Basics.Bool
, value : String
, error : Maybe Form.Error.Error
, showError : Basics.Bool
, attributes : Form.Base.NumberField.Attributes Basics.Float
}
Describes how a number field should be rendered.
onChange
takes a new value for the field and returns the msg
that should be produced.value
contains the current value of the field.attributes
are NumberField.Attributes
.The other record fields are described in TextFieldConfig
.
{ onChange : Maybe Basics.Float -> msg
, onBlur : Maybe msg
, disabled : Basics.Bool
, value : Maybe Basics.Float
, error : Maybe Form.Error.Error
, showError : Basics.Bool
, attributes : Form.Base.RangeField.Attributes Basics.Float
}
Describes how a range field should be rendered.
onChange
accepts a Maybe
so the field value can be cleared.value
will be Nothing
if the field is blank or Just
a Float
.attributes
are RangeField.Attributes
.The other record fields are described in TextFieldConfig
.
{ onChange : Basics.Bool -> msg
, onBlur : Maybe msg
, disabled : Basics.Bool
, value : Basics.Bool
, error : Maybe Form.Error.Error
, showError : Basics.Bool
, attributes : Form.Base.CheckboxField.Attributes
}
Describes how a checkbox field should be rendered.
This is basically a TextFieldConfig
, but its attributes
are
CheckboxField.Attributes
.
{ onChange : String -> msg
, onBlur : Maybe msg
, disabled : Basics.Bool
, value : String
, error : Maybe Form.Error.Error
, showError : Basics.Bool
, attributes : Form.Base.RadioField.Attributes
}
Describes how a radio field should be rendered.
This is basically a TextFieldConfig
, but its attributes
are
RadioField.Attributes
.
{ onChange : String -> msg
, onBlur : Maybe msg
, disabled : Basics.Bool
, value : String
, error : Maybe Form.Error.Error
, showError : Basics.Bool
, attributes : Form.Base.SelectField.Attributes
}
Describes how a select field should be rendered.
This is basically a TextFieldConfig
, but its attributes
are
SelectField.Attributes
.
{ forms : List element
, label : String
, add : Maybe { action : () -> msg
, label : String }
, disabled : Basics.Bool
}
Describes how a form list should be rendered.
forms
is a list containing the elements of the form list.add
describes an optional "add an element" button. It contains a lazy action
that can be called in order to add a new element and a label
for the button.{ fields : List element
, delete : Maybe { action : () -> msg
, label : String }
, disabled : Basics.Bool
}
Describes how an item in a form list should be rendered.
fields
contains the different fields of the item.delete
describes an optional "delete item" button. It contains a lazy action
that can be called in order to delete the item and a label
for the button.