axelerator / fancy-forms / 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 String
    | MustBeLesserThan String
    | CustomError customError

A type for errors that can be generated by a Validator


type FormState
    = FormState ({ parentDomId : DomId, values : Dict FieldId Json.Encode.Value, fieldStatus : Dict FieldId FieldStatus, allBlurred : Basics.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 value customError
, isConsistent : model -> Basics.Bool
, view : DomId -> List (Html.Attribute msg) -> model -> List (Html msg)
, update : msg -> model -> UpdateResult model
, encodeMsg : msg -> Json.Encode.Value
, decoderMsg : Json.Decode.Decoder msg
, encodeModel : model -> Json.Encode.Value
, decoderModel : Json.Decode.Decoder model
, blur : model -> model
, innerAttributes : List (Error customError) -> value -> List (Html.Attribute msg) 
}

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.

blurAll : FormState -> FormState

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 Json.Encode.Value -> DomId -> FormState

Creates a new form state with the given values.

Advanced helpers to cunstruc widgets from scratch

blurChildren : FieldId -> Widget model msg value customError -> FormState -> FormState

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.


type FieldOperation
    = Add
    | Remove
    | Update Json.Encode.Value

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


type FieldStatus
    = NotVisited
    | Focused
    | Changed
    | Blurred

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


type SubfieldId
    = SingleValue
    | ArrayElement Basics.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

encodedUpdate : Widget model msg value customError -> SubfieldId -> FieldOperation -> Json.Encode.Value -> Json.Encode.Value

Encodes the update for the given field.

formStateDecoder : Json.Decode.Decoder FormState

Decodes a form state from a JSON value

formStateEncode : FormState -> Json.Encode.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 -> Json.Encode.Value

Reads the value for the given field.

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

Calculates the dom id for the given field and subfield.

updateFieldStatus : FieldStatus -> Effect -> FieldStatus

Updates the status of a field based on an effect

wasAtLeast : FieldStatus -> FieldId -> FormState -> Basics.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 -> Json.Encode.Value -> FormState

Updates the value for the given field.

withInnerAttributes : (List (Error customError) -> value -> List (Html.Attribute msg)) -> Widget model msg value customError -> Widget model msg value customError

You can provide a function that generates a list of attributes for the inner widget. This function can use the current value and errors to generate the attributes.

noAttributes : List (Error customError) -> value -> List (Html.Attribute msg)

The default for a Widget