Getting started with Elm 0.19

Introduction

Since the last article I wrote two years ago, we have been using Elm in production since then with great success.

This article is an update from the original article (Elm 0.18 -> Elm 0.19)

You might as well follow the official Elm guide.

What is Elm and why should I care?

Elm is a Web application development platform, providing a programming language, a compiler, an architecture and tooling. It focuses on making sure your app state and the HTML that reflects it are always in sync.

If you have been doing any frontend development during the last couple of years, you might have seen that the JavaScript ecosystem is a bit wild. Keeping up-to-date with the growing number of competing frameworks can take a lot of energy, not to mention the challenge in making sure your app works on all the available browser versions.

If you want to be able to write front-end applications without having to cope with the JavaScript fatigue, you should definitely try Elm.

Elm brings functional programming to your browser. The language is statically typed, so with Elm you won't see any runtime errors caused by inconsistent typing. Being functional and pure, Elm let you write code that is completely decoupled, which makes your code more reusable and easier to refactor.

How is Elm different?

Most of the time, using Elm, the two lines it takes to load your app from the HTML file is all the JavaScript you need. Your Elm code is compiled to JavaScript by the Elm compiler.

Most mistakes you make will be caught at compilation time, which means that you will barely ever encounter exceptions at runtime in the browser. Also, that means fewer unit tests and defensive programming to write, which is always good.

Because there is a compilation step, Elm forces you to handle every possible case of your model state. It makes sure you covered them on the rendering side.

Also, the Elm compiler is super smart. It always does its best to help you with meaningful messages, provides guidance to fix your types and handle uncovered edge cases. It even finds your typos!

Cannot find variable `nane`

13|     hello ++ ", " ++ nane ++ "!"
                         ^^^^
Maybe you want one of the following?

    name
    tan
    Cmd.none
    Sub.none

Detected errors in 1 module.

The tooling is great. elm-live automatically updates the browser code to reflect your code update in realtime. It comes with a debugger that shows you the list of events and state of your application at a given point in time — you can even go back in time and replay previous events. elm-format also formats your code automatically avoiding arguments over coding styles.

Getting started

sudo npm install -g elm elm-format elm-live

Starting your first project

No need for boilerplate here, you can just start by running elm init to create the minimum elm.json file mandatory to start an app:

~/tutorial$ elm init

Hello! Elm projects always start with an elm.json file. I can create them!

Now you may be wondering, what will be in this file? How do I add Elm files to
my project? How do I see it in the browser? How will my code grow? Do I need
more directories? What about tests? Etc.

Check out <https://elm-lang.org/0.19.0/init> for all the answers!

Knowing all that, would you like me to create an elm.json file now? [Y/n]:
Okay, I created it. Now read that link!

You now have an elm.json file in your project as well as an empty src/ directory where you put your source files.

elm.json is to Elm projects what package.json is to nodejs ones.

~/tutorial$ tree -L2
├── elm.json
└── src

1 directory, 1 file

Creating your first file

To get started you can simply create a new file named src/Main.elm :

import Html
main = Html.text "Hello world"

Elm benefits from a full featured module system, with a broad ecosystem of external packages available. Html is part of the core libs.

module Main exposing (main)

import Html


main =
    Html.text "Hello world!"

~/tutorial$ elm-format --yes Main.elm

~/tutorial$ elm reactor
Go to <http://localhost:8000> to see your project dashboard.

Learning about the Elm virtual DOM

Virtual DOM functions to generate HTML are in the Html module.

The Html module we used above to render some text also exposes many more functions for rendering HTML tags. You can import them all using:

import Html exposing (..)

Note that unlike with some other languages, the Elm compiler will complain if you try to import symbols already defined in the current module, which makes it actually useful and really enjoyable to use.

You can then use text directly for instance:

main = text "Hello world"

The Virtual DOM HTML nodes are functions named after standard HTML tags, and take two parameters:

• A list of attributes
• A list of children

If I want to create a div with a link it would look like this:

module Main exposing (main)

import Html exposing (..)
import Html.Attributes exposing (..)


main =
    div
        [ class "container" ]
        [ a
            [ href "http://www.servicedenuages.fr/" ]
            [ text "Blog" ]
        ]

We can also create a list of links in our div:

module Main exposing (main)

import Html exposing (..)
import Html.Attributes exposing (..)


main =
    div
        [ class "container" ]
        [ ul
            [ class "links" ]
            [ li
                []
                [ a
                    [ href "http://www.servicedenuages.fr/" ]
                    [ text "Blog" ]
                ]
            , li
                []
                [ a
                    [ href "http://www.elm-lang.org/" ]
                    [ text "Elm lang" ]
                ]
            ]
        ]

Adding some state

Now that you know how to render your page in HTML, let's see how to write a program that handles events.

type Msg
    = AddUser
    | SetName String
    | SetStatus UserStatus

type UserStatus
    = Active
            | Inactive

The Elm Architecture

The way Elm handles a program is by having:

• a Model that keep the state of the app,
• an update function that handles all the app events and updates the model state accordingly
• a view function that returns the Virtual DOM matching the state of the app every time it's updated.

For those who know Redux, it has been heavily inspired by Elm. Basically update is a reducer.

When with Redux you would write:

const initialState = 0;

const incrementAction = {
  type: "INCREMENT"
};

const decrementAction = {
  type: "DECREMENT"
};

function counterReducer(state = initialState, action) {
  switch (action.type) {
    case "INCREMENT":
      return state + 1;

    case "DECREMENT":
      return state - 1;

    default:
      return state;
  }
}

With Elm you will write:

type alias Model = Int

type Msg
   = Increment
   | Decrement

update : Msg -> Model -> Model
update msg model =
  case msg of
    Increment ->
      model + 1

    Decrement ->
      model - 1

The events and their parameters are defined in a Msg type.

In order to create our application that handle states, we can use the Browser package.

It provides four differents level of Elm programs.

1. sandbox which is the simplest Elm program that you can build, it let you create a HTML element handled by Elm which, however, cannot communicate with the outside world.
2. element create an HTML element managed by Elm.
3. document which let you manage a HTML page (handle the title and the body tag)
4. application which let you manage URL changes as well.

To start with, let's create our first Elm program using Browser.sandbox.

module Main exposing (main)

import Browser
import Html exposing (..)


type Msg
    = NoOp


type alias Model =
    { name : String }


main =
    Browser.sandbox { init = { name = "Rémy" }, view = view, update = update }


update : Msg -> Model -> Model
update msg model =
    model


view : Model -> Html Msg
view model =
    text ("Hello " ++ model.name)

We can now handle an event and change the name when we click on it.

module Main exposing (main)

import Browser
import Html exposing (..)
import Html.Attributes exposing (..)
import Html.Events exposing (..)


type Msg
    = Switch


type alias Model =
    { name : String }


main =
    Browser.sandbox { init = { name = "Rémy" }, view = view, update = update }


update : Msg -> Model -> Model
update msg model =
    case msg of
        Switch ->
            { model | name = "Séverine" }


view : Model -> Html Msg
view model =
    div []
        [ text "Hello "
        , a [ href "#", onClick Switch ] [ text model.name ]
        ]

You can refresh the page and try it.

If we want to switch back to Rémy when we click on Séverine we can add a if:

module Main exposing (main)

import Browser
import Html exposing (..)
import Html.Attributes exposing (..)
import Html.Events exposing (..)


type Msg
    = Switch


type alias Model =
    { name : String }


main =
    Browser.sandbox { init = { name = "Rémy" }, view = view, update = update }


update : Msg -> Model -> Model
update msg model =
    case msg of
        Switch ->
            if model.name == "Rémy" then
                { model | name = "Séverine" }
            else
                { model | name = "Rémy" }


view : Model -> Html Msg
view model =
    div []
        [ text "Hello "
        , a [ href "#", onClick Switch ] [ text model.name ]
        ]

Enabling auto updates with elm-live

elm reactor is good to get started but if you want hot-reloading of your app, you might want to setup elm-live.

Once installed, run:

$ elm-live src/Main.elm

If you have to use the debugger, you can use the --debug option:

$ elm-live src/Main.elm -- --debug

It will automatically generate an index.html file with the compiled JavaScript, and open it in your default Web browser.

You can use the --output option to save the JavaScript in its own file and load it in the HTML yourself.

First update the index.html to make it looks like:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Hello world</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="elm.js"></script>
  </head>

  <body>
    <div id="sandbox"></div>
    <script>
        var app = Elm.Main.init({node: document.getElementById("sandbox")});
    </script>
  </body>
</html>

Then you can run elm-live with the --output option:

$ elm-live src/Main.elm -- --debug --output elm.js

Now each time you will update your Elm code it will refresh the app in the browser.

Handling a second event

Let's add an input to let people choose who to greet.

module Main exposing (main)

import Browser
import Html exposing (..)
import Html.Attributes exposing (..)
import Html.Events exposing (..)


type Msg
    = Switch
    | NewName String


type alias Model =
    { name : String }


main =
    Browser.sandbox { init = { name = "Rémy" }, view = view, update = update }


update : Msg -> Model -> Model
update msg model =
    case msg of
        Switch ->
            if model.name == "Rémy" then
                { model | name = "Séverine" }
            else
                { model | name = "Rémy" }

        NewName newName ->
            { model | name = newName }


view : Model -> Html Msg
view model =
    div []
        [ text "Hello "
        , a [ href "#", onClick Switch ] [ text model.name ]
        , br [] []
        , input
            [ onInput NewName
            , value model.name
            ]
            []
        ]

The NewName event will be emitted with the content of the input each time we type in it.

Conclusion

That's about it. Now that you understand how the event update mechanism works and how you can define functions, you know more than you think about Elm.

When in doubt, the package documentation is really useful: https://package.elm-lang.org/

I hope you give Elm a shot on your next project and enjoy Elm as much as we do @Chefclub.

Wait a minute, That's it? Do I really know everything? But you didn't tell me how I was supposed to handle HTTP requests yet!

Handling HTTP requests

Fair enough, I remember asking exactly this question when I was introduced to Elm.

Let's use the photos collection of JSON Placeholder to get a list of JSON objects.

In order to do so we use the elm/http library.

The README is really enlightning already and I would recommand you to try to use it to create a fetchItems command.

import Json.Decode as Decode

fetchItems : Cmd Msg
fetchItems =
  Http.get
    { url = "https://jsonplaceholder.typicode.com/photos"
    , expect = Http.expectJson GotItems (Decode.list decodePhoto)
    }

import Json.Decode as Decode exposing (Decoder)
import Http


type Msg =
    GotItems (Result Http.Error (List Photo))


type alias Photo =
    { id : Int
    , title : String
    , url : String
    , thumbnailUrl : String
    }


decodePhoto : Decoder Photo
decodePhoto =
   Decode.map4 Photo
     (Decode.field "id" Decode.int)
     (Decode.field "title" Decode.string)
     (Decode.field "url" Decode.string)
     (Decode.field "thumbnailUrl" Decode.string)

import Json.Decode as Decode exposing (Decoder)
import Json.Decode.Pipeline exposing (required, optional, hardcoded)

 decodePhoto : Decoder Photo
 decodePhoto =
    Decode.succeed Photo
      |> required "id" Decode.int
      |> required "title" Decode.string
      |> required "url" Decode.string
      |> required "thumbnailUrl" Decode.string

update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        GotItems result ->
            case result of
                Ok photos ->
                    ( { model | error = Nothing, photos = photos }, Cmd.none )

                Err err ->
                    ( { model | error = Just <| errorToString err, photos = [] }, Cmd.none )

update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        GotItems (Ok photos) ->
            ( { model | error = Nothing, photos = photos }, Cmd.none )

        GotItems (Err err) ->
            ( { model | error = Just <| errorToString err, photos = [] }, Cmd.none )

Showing the list of pictures

Once we are able to fetch our list of photos, we might want to display those pretty pictures.

I invite you to have a look at the Ellie with the fully functionnal version of the app: https://ellie-app.com/55LtWwHbhkPa1

The interesting part is the following:

displayPhotos : List Photo -> Html Msg
displayPhotos photos =
    List.take 100 photos
        |> List.map showPhoto
        |> div []

showPhoto : Photo -> Html Msg
showPhoto photo =
    a [ href photo.url, title photo.title ] [ img [ src photo.thumbnailUrl ] [] ]

List.map will take each photo of model.photos and create a list of the results of the showPhoto function.

Because showPhoto returns a Html Msg, List.map will return a list of Html Msg. We can then use this result as a list of children to a div [] element.

Conclusion

What's next? Starting from here, you can grow your widget. At some point you might want to create a Single Page App (SPA) and handle URL with multiple pages.

That's where the Elm Architecture really starts to shine. I would recommend you to have a look at elm-kitchen which will help you to get started with the scaffolding.

A word about Elm types and Elm records

type Status = Active | Inactive

displayUser : User -> Html Msg
displayUser user =
    div [] [ text <| user.username ++ " - " ++ statusToString user.status ]


statusToString : Status -> String
statusToString status =
    case status of
        Active ->
            "This user is active"

        Inactive ->
            "This user is inactive"

type Msg
    = AddTodo
    | UpdateTodoDescription String

update : Msg -> Model -> Model
update msg model =
    case msg of
        AddTodo ->
            { model
                | todos = Todo model.currentInputValue :: model.todos
                , currentInputValue = ""
            }

        UpdateTodoDescription value ->
            { model | currentInputValue = value }

{ username = "Natim", status = Active }

{ username : String, status : Status }

getUserName :  { username : String, status : Status } -> String
getUserName user =
    user.username

type alias User =
     { username : String, status : Status }

getUserName :  User -> String
getUserName user =
    user.username

getUserName :  User -> String
getUserName =
    .username

type Maybe a = Just a | Nothing

type Result a b = Err a | Ok b

type Username = Username String

usernameToString = Username -> String
usernameToString (Username value) =
    value

type alias Username =
    String

type alias Username =
    String


type alias FirstName =
    String


type alias LastName =
    String


type Status
    = Active
    | Inactive


type alias User =
    { firstName : FirstName
    , lastName : LastName
    , username : Username
    , status : Status
    }


createUser : Username -> FirstName -> LastName -> User
createUser username firstname lastname =
    User username firstname lastname Inactive

Success! Compiled 1 module.

{ firstName = username, lastName = firstname, username = lastname, status = Inactive }

type Username =
    Username String


type FirstName =
    FirstName String


type LastName =
    LastName String


type Status
    = Active
    | Inactive


type alias User =
    { firstName : FirstName
    , lastName : LastName
    , username : Username
    , status : Status
    }


createUser : Username -> FirstName -> LastName -> User
createUser username firstname lastname =
    User username firstname lastname Inactive

Detected errors in 1 module.
-- TYPE MISMATCH ------------------------------------------------------ Test.elm

The 3rd argument to `User` is not what I expect:

31|     User username firstname lastname Inactive
                                ^^^^^^^^
This `lastname` value is a:

    LastName

But `User` needs the 3rd argument to be:

    Username

Hint: I always figure out the argument types from left to right. If an argument
is acceptable, I assume it is “correct” and move on. So the problem may actually
be in one of the previous arguments!

-- TYPE MISMATCH ------------------------------------------------------ Test.elm

The 2nd argument to `User` is not what I expect:

31|     User username firstname lastname Inactive
                      ^^^^^^^^^
This `firstname` value is a:

    FirstName

But `User` needs the 2nd argument to be:

    LastName

Hint: I always figure out the argument types from left to right. If an argument
is acceptable, I assume it is “correct” and move on. So the problem may actually
be in one of the previous arguments!

-- TYPE MISMATCH ------------------------------------------------------ Test.elm

The 1st argument to `User` is not what I expect:

31|     User username firstname lastname Inactive
             ^^^^^^^^
This `username` value is a:

    Username

But `User` needs the 1st argument to be:

    FirstName