axelerator/fancy-forms/1.0.0

NOTE: the latest version is 7.0.1

FancyForms.Form

FancyForms is a library for building forms in Elm. It is designed with the following goals in mind:

  1. Type saftey: Data collected in the forms will be returned directly into a user provided type.
  2. Ease of use: No matter how complex the form is, it will only need one Msg and one field on the model.
  3. Customization: Users can provide their own widgets and custom validations.
  4. CSS Agnostic: Adapts to any CSS framework.
  5. Composable: Smaller forms can be combined into larger forms.
  6. I18n: Internationalization is supported by avoiding hard coded strings.

Definition

type alias Form data customError =
FormInternal
{ view : FormState -> List (Error customError) -> List (Html Msg)
, combine : FormState -> data
}
customError
data

A form that collects a value of type data and potentially produces errors of type customError.

DomId
-> Validator data customError
-> FieldWithErrors customError
-> a
-> FormInternal a customError data

Defines a new form that fields can be added to. Takes four arguments: 1, A unique id for the form to be used as id in the DOM 1. A validator function that takes the form data and returns a list of errors 1. A function that receives the fields and returns the view and combine functions 1. A function that receives the markup of a field and combines it with a list of errors

   myForm : Form Int ()
   myForm =
       Form.form "minimal-example"
           (\data -> [])
           (\errors_ html -> html)
           (\amount ->
               { view = \formState _ -> amount.view formState
               , combine = \formState -> amount.value formState
               }
           )
           |> field (integerInput [])
type alias FieldWithErrors customError =
List (Error customError) -> List (Html Msg) -> List (Html Msg)

A function that recieves the markup of a field and combines with a list of errors.

List (Validator model customError)
-> Widget model msg value customError
-> Widget model msg value customError

Adds a validator to a widget.

Widget widgetModel msg value customError
-> FormInternal (Field value customError -> c) customError data
-> FormInternal c customError data

Adds a new field with the given widget to the form

Wiring

type Msg

The message type for the form.

update : Form a customError -> Msg -> FormState -> FormState

Updates the form state based on the form message.

extract : Form data customError -> FormState -> data

Returns the result of the combine function aka the current state of the form.

init : Form data customError -> FormState

Initializes a form state with the default values

render : (Msg -> msg) -> Form a customError -> FormState -> List (Html msg)

Takes the following three arguments to display a form:

  1. a function to turn the forms messages into a Msg of the application.

  2. the form

  3. the current state of the form

    type Msg = ... | ForForm Form.Msg | ... type alias Model = { ... , formState : FormState, .. } myForm = Form.form ...

    view model = div [] <| Form.render ForForm myForm model.formState

List fields

ListWithAddButton Msg
-> FieldWithRemoveButton Msg
-> Widget model msg value customError
-> { a
| fn : Field (List value) customError -> b
, count : Int
, updates :
Dict
String
(SubfieldId -> FieldOperation -> Value -> ( Value, Effect ))
, fieldWithErrors : FieldWithErrors customError
, validator : e
, defaults : Dict String Value
, blur : c -> FormState
, domId : h
}
-> { fn : b
, count : Int
, updates :
Dict
String
(SubfieldId -> FieldOperation -> Value -> ( Value, Effect ))
, fieldWithErrors : FieldWithErrors customError
, validator : e
, defaults : Dict String Value
, blur : c -> FormState
, domId : h
}

Adds a field to the form where the user can add and remove elements.

The first argument is a ListWithAddButton function that cobines the inout list with a button to add a new element.

The second argument is a FieldWithRemoveButton function that combines one item with a button to remove it.

The third argument is the widget to use for each element in the list.

type alias FieldWithRemoveButton msg =
msg -> List (Html msg) -> List (Html msg)

A function that recieves the markup of a list item and combines it with a butoon to remive it from the List.

type alias ListWithAddButton msg =
msg -> List (Html msg) -> List (Html msg)

A function that recieves the markup of a field and combines it with a button to add a new item.

Fields with Variants

(Variants String -> Widget String msg String customError)
-> ( String, Form value customError )
-> List ( String, Form value customError )
-> FormInternal (Field value customError -> c) customError data
-> FormInternal c customError data

Adds a new field to with different variants to the form. Each variant is represented by a label and a sub form.

The function takes the following arguments:

  1. A widget to select the variant

  2. The default variant

  3. A list of other variants

type alias Variant a =
{ value : a
, id : String
, label : String
}

A variant for widgets with a "select" notion.

type alias Variants a =
ListNonempty (Variant a)

A nonempty list of variants.

Composition

toWidget : Form a customError -> Widget FormState Msg a customError

Converts a form to a widget.

Widget widgetModel msg value customError
-> (DomId -> List (Html msg) -> List (Html msg))
-> Widget widgetModel msg value customError

Creates a new Widget that's decorated with the given function.