This is an alternative site for discovering Elm packages. You may be looking for the official Elm package site instead.
We were not able to find the expected elm-package.json file at this tag.
Tag 2.0.1
Committed At 2018-08-28 16:34:20 UTC

Modules

    README

    elm-forms

    A library for building and validating Forms in Elm

    Build Status

    Motivation

    There is no specific way of handling/validating forms in Elm. This library aims to provide an easy but flexible way of creating forms, validating them, handling the different message updates and building a whole business logic on top of them.

    Here is a list of different features that we need when dealing with forms imo (and that the library actually implements) :

    • Custom error
      We should be able to fail with custom errors but also implement some logic on our errors : a custom error is usually more than a string (but can be just a string if that's enough)

    • Field error
      We should be able to have errors at the field level in order to identify which field caused the failure during the validation process

    • Field identification
      The key associated with a field should be more than a string : a comparable

    • Validation process
      The validation process should be accumulative and gather all the errors. But should also provide a way to stop and fail at the first error encountered.

    • View agnostic
      We should be able to work with forms whether we use Bootstrap, MDL, elm-lang/html ... The library should only provide functions to use in the view layer

    Plus, the library should also be :

    • Easy to use
      And provide helper functions dealing with the complex stuff so we can focus on the business logic

    • Flexible
      Enough to fit most of the common use cases. But also give us the opportunity to do more if we understand what's happening under the hood

    • Pipeline friendly
      Because when you start using elm-decode-pipeline you just really like this syntax :)

    A quick overview

    Here are some parts of the first example : a basic form with three fields (two strings and one int) that creates an OtherModel

    ...
    
    {- Model -}
    
    init : ( Model, Cmd Msg )
    init =
        ( Model (F.form myFormFields myFormValidate)
        , Cmd.none
        )
    
    
    type alias Model =
        { myForm : F.Form String MyFormError OtherModel
        }
    
    ...
    
    {- Form -}
    
    type alias OtherModel =
        { firstName : String
        , lastName : String
        , referenceNumber : Int
        }
    
    
    type MyFormError
        = EmptyString
        | NotInt
    
    
    myFormFields : FF.Fields String
    myFormFields =
        FF.fields
            [ ( "first-name", FF.input )
            , ( "last-name", FF.input )
            , ( "reference-number", FF.input )
            ]
    
    
    myFormValidate : FV.Validate String MyFormError OtherModel
    myFormValidate fields =
        FV.valid OtherModel
            |> FV.required fields "first-name" (FV.stringField <| FV.notEmpty EmptyString FV.success)
            |> FV.required fields "last-name" (FV.stringField <| FV.notEmpty EmptyString FV.success)
            |> FV.required fields "reference-number" (FV.stringField <| FV.int NotInt FV.success)
    
    ...
    
    {- Msg/Update -}
    
    type Msg
        = Form (FU.Msg String)
    
    update : Msg -> Model -> ( Model, Cmd Msg )
    update msg model =
        case msg of
            Form formMsg ->
              { model | myForm = FU.updateForm formMsg model.myForm } ! []
    
    ...
    
    {- View -}
    
    inputText : String -> String -> Html Msg
    inputText placeHolder fieldName =
        input
          [ inputStyle
          , placeholder placeHolder
          , onInput (FU.stringFieldMsg Form fieldName)
          ]
          []
    
    ...
    
    F.validate model.myForm -- validates the form and returns a `FormResult`
    

    A journey with Forms (examples)

    For a better understanding on how to use the library, I would recommend you to go through all the examples, following the order specified. You should have a look at the source code, as there are some comments there, while running the examples and playing with them.

    All the examples are single apps (and have their own elm-package.json), so you can run them like this :

    cd EXAMPLE_DIR
    elm-reactor
    

    If you have downloaded/cloned the all library you can just :

    cd elm-forms/examples
    elm-reactor
    

    and have access to all the examples.

    Troubleshooting

    • If you have a ConfigError when validating your form, have a look at which field is concerned and
      • If the error is a MissingField one : make sure there is no typo error in the field key either in the Fields or in the Validate function
      • If the error is a WrongType one : make sure you're using the stringField helper for an input/select field and the boolField helper for a checkbox field
    • If a field value never changes
      • First make sure you're implementing the form Msg and you're updating the form with the updateForm function
      • Second, in your view, make sure you have an event defined on the field and it's using a form Msg : stringFieldMsg or boolFieldMsg
      • Finally make sure there is no typo error in the field key either in the Fields or in your view event
    • If a field validation never/always fails/succeeds, make sure you're using the success or failure function