axelerator/fancy-forms/2.0.0

NOTE: the latest version is 7.0.1

FancyForms.FormState

Exposes various types used to track state of the form.

Types used in the declaration of forms

type alias DomId =
String

A unique identifier for a field in a form.

type Error customError
= NotValid
| MustNotBeBlank
| MustBeGreaterThan Int
| MustBeLesserThan Int
| CustomError customError

A type for errors that can be generated by a Validator

= FormState
{ parentDomId : DomId
, values : Dict FieldId Value
, fieldStatus : Dict FieldId FieldStatus
, allBlurred : Bool
}

The state of the form. Stores all the values and the status of each field.

type alias Validator a e =
a -> List (Error e)

A validator is a function that can be used to validate the value of a form or a widget.

type alias Widget model msg value customError =
{ init : value -> model
, default : value
, value : model -> value
, validate : Validator model customError
, isConsistent : model -> Bool
, view : DomId -> model -> List (Html msg)
, update : msg -> model -> UpdateResult model
, encodeMsg : msg -> Value
, decoderMsg : Decoder msg
, encodeModel : model -> Value
, decoderModel : Decoder model
, blur : model -> model
}

A widget that can be used to create a form field.

Helper to construct forms or modify state

alwaysValid : a -> List (Error e)

Creates a validator that always succeeds.

Useful for forms that fully rely on per-field validations.

Marks all fields as blurred. This is needed to show all errors when trying to submit a form without the user having visited all fields.

init : Dict FieldId Value -> DomId -> FormState

Creates a new form state with the given values.

Advanced helpers to cunstruc widgets from scratch

FieldId
-> Widget model msg value customError

Internal: Used to recursively blur child fields.

type Effect
= NoEffect
| WasFocused
| WasChanged
| WasBlurred

Specifies the effect of a field with relation to the focus state.

type alias FieldId =
String

A unique identifier for a field in a form.

= Add
| Remove
| Update Value

Specifies the operation to perform on a field. Add and Remove are used for list fields.

= NotVisited
| Focused
| Changed
| Blurred

The status of a field. We'll only expose the result of a field validation after it has been blurred.

= SingleValue
| ArrayElement Int

List fields need an index additional to the FieldId to know which list item to update.

type alias UpdateResult model =
{ model : model
, effect : Effect
}

Is returned from the update function of a Widget

Widget model msg value customError
-> Value
-> Value

Encodes the update for the given field.

Decodes a form state from a JSON value

Encodes a form state into a JSON value

justChanged : model -> UpdateResult model

Wraps the given model with the indication that the field was changed in a way that it must also have been focused.

justChangedInternally : model -> UpdateResult model

Wraps the given model with the indication that the field was changed but didn't change the focus.

read : FieldId -> FormState -> Value

Reads the value for the given field.

subId : DomId -> FieldId -> SubfieldId -> DomId

Calculates the dom id for the given field and subfield.

Updates the status of a field based on an effect

wasAtLeast : FieldStatus -> FieldId -> FormState -> Bool

Helper to check if a field was visited

withBlur : model -> UpdateResult model

Wraps the given model with the indication that the field was blurred.

withFocus : model -> UpdateResult model

Wraps the given model with the indication that the field was focused.

write : FieldId -> SubfieldId -> FormState -> Value -> FormState

Updates the value for the given field.