Ben Booth

Animating Loading Spinners with CSS

Ben Booth — Tue, 20 Jun 2017 22:49:09 GMT

I recently had the privilege of being invited to give my first ever meetup talk at SydCSS. It was a first time speakers night so short talks (5 mins) and high nerves were the order of the day. On a recent side project I had wasted a bunch of time creating a fancy loading spinner while I was mentally blocked trying to solve a real problem. I had the idea at the time that I could probably give a reasonably interesting talk by making some loading animations with CSS and explaining the interesting parts of the CSS animation API used for each animation. I had a rough plan and a platform, the rest of this article is the transcript of that talk rewritten as a blog post.

You can view the slides for the talk here, take a look and play around with the examples on the slides!

There are two basic building blocks for CSS animations. Firstly the @keyframes at-rule, which you define with the @keyframes keyword, then a name or identifier for the keyframes set, then a list of steps which define CSS properties for each step.

@keyframes my-sweet-animation {
  0% {
    /* ... */
  }
  50% {
    /* ... */
  }
  100% {
    /* ... */
  }
}

Secondly the animation properties which you can use in shorthand form, or by using individual sub-properties.

@keyframes my-sweet-animation {
  /* ... */
}

.thing-to-animate {
  /* shorthand */
  animation: 2s my-sweet-animation;

  /* individual sub-properties */
  animation-name: my-sweet-animation;
  animation-duration: 2s;
  animation-timing-function: ease;
}

There are 8 animation sub-properties and they provide a great deal of flexibility: animation-name, animation-duration, animation-delay, animation-direction, animation-iteration-count, animation-timing-function, animation-fill-mode and animation-play-state.

Fading

See the Pen Fading dot, 3-step @keyframes by Ben (@bkbooth) on CodePen.

Starting with a simple fading dot animation, which is just a block with rounded corners where the opacity is being faded in and out. I’ve defined the @keyframes at-rule with 3 steps going from completely visible, to completely invisible, then back to completely visible. To use these keyframes to animate the dot, I’ve used the animation shorthand property to set the animation-duration to 1 second; the animation-name to ‘fade-in-out’ which matches the @keyframes at-rule; and ‘infinite’ for the animation-iteration-count. animation-iteration-count can be a number or ‘infinite’ and defaults to 1. A single pass through the keyframes isn’t very useful for loading animations, so I’ll be using ‘infinite’ for all of these animations. You can tweak the speed of the animation by modifying the animation-duration property which takes seconds or milliseconds values.

See the Pen Fading dot, 2-step @keyframes by Ben (@bkbooth) on CodePen.

In this case the @keyframes at-rule can be simplified to just the start and end steps by setting the animation-direction property to ‘alternate’, which means the animation goes forward through the keyframes steps, then back through in reverse. Now that a full animation loop goes through the keyframes twice, the animation-duration should be halved. This approach means that you can define more generic and reusable @keyframes at-rules. You may also see ‘from’ and ‘to’ instead of percentages for keyframes steps, these are just aliases for ‘0%’ and ‘100%’ respectively. I personally prefer to stick with percentage steps.

Spinning

See the Pen Rotating star by Ben (@bkbooth) on CodePen.

Spinners are another simple animation that can be defined easily in CSS. I’ve introduced the transform property to handle the rotation, transform provides a great toolset of functions for 2D and 3D translating (as in movement), scaling and rotation. The ‘rotate’ @keyframes at-rule just sets the starting rotation to ‘0deg’ and the ending rotation to ‘360deg’. I’ve introduced the animation-timing-function property and set it to ‘linear’. animation-timing-function defaults to ‘ease’ to ease the animation in and out, this caused the fading dot to “breathe” in and out. If a rotation animation uses ‘ease’ it speeds up and slows down, for rotation you want a nice even ‘linear’ animation.

See the Pen Rotating concentric circles by Ben (@bkbooth) on CodePen.

Using the same rotation @keyframes at-rule you can create more complex animations by just combining things we’ve already looked at. Another value that you can set for the animation-direction property is ‘reverse’ which as you can probably guess, plays the keyframes in reverse.

You can use the same keyframes to rotate pretty much anything you want…

See the Pen Rotating doge by Ben (@bkbooth) on CodePen.

Chasing

See the Pen Chasing dots, CSS by Ben (@bkbooth) on CodePen.

For this animation I’ve arranged a series of small dots around a circle and used a similar @keyframes at-rule as earlier, fading the dots in and out to ‘20%’ opacity. The main animation shorthand property adds nothing new and is being applied to all of the individual dots with an attribute selector. I’ve set an animation-delay for each of the dots to offset each of them starting by an 1/8th of a second. As you can see it’s a little tedious having to manually set the offset for each dot, especially if you wanted to change the speed of the whole animation.

See the Pen Chasing dots, SCSS by Ben (@bkbooth) on CodePen.

If you’re using SASS or something similar, you can improve on this by setting the desired animation speed and the number of dots in variables. Halve the animation speed for the animation property definition. Then loop through the number of dots and calculate the animation-delay for each dot using the desired animation speed, number of dots and current iteration variables.

Bouncing

See the Pen Bouncing dot, single by Ben (@bkbooth) on CodePen.

This bouncing dot animation uses yet another fairly simple @keyframes at-rule, it’s just using the transform property to translate the dot up, and I’m using ‘alternate’ for the animation-direction again. To make it look more “bouncy” I’ve defined a ‘cubic-bezier’ function for the animation-timing-function property. If that looks a little daunting to you, don’t worry, I didn’t actually write this, and you should never need to write one of these by hand because Chrome (and possibly other browsers?) has an awesome bezier curve editor where you can just drag some dots to visually create the cubic-bezier curve and it will write the cubic-bezier function for you.

See the Pen Bouncing dot, triple by Ben (@bkbooth) on CodePen.

Finally, to create this excitedly impatient series of dots, I’ve defined a slightly more complex @keyframes at-rule which performs the translation up and down in just the first 1/3rd of the time. I’ve also set an animation-delay for each of the dots in the series to offset them starting.

Wrapping Up

Most of this is relatively new to the CSS spec but support in modern browsers is actually really good. Depending what browsers you need to target though you’ll get a lot of mileage out of using autoprefixer to process your CSS and automatically add any required vendor prefixes like -webkit, -moz, etc.

MDN is a great learning resources for understanding CSS properties and rules. There’s also a really helpful guide on using CSS animations:

Managing Keybase private key with GPGTools

Ben Booth — Wed, 08 Feb 2017 13:07:00 GMT

This is not a particularly well-written article. I’ve found everything here useful, but so irregularly that I always end up Googling and needing to put together info from multiple blog posts so I’m putting it all together here for my reference, and maybe it’ll help you if you stumbled across it. ~~At some stage I’ll organise this into a proper article.~~ [Update 2017-04-07] I’ll probably never actually update this article.

Import your Keybase key into GPGTools

Export your existing public and private keys from Keybase, save them locally as keybase-public.key and keybase-private.key respectively.

Import both keys into your local GPGTools:

$ gpg --allow-secret-key-import --import keybase-private.key
$ gpg --import keybase-public.key

Delete both the public and private key files.

Optionally, edit ~/.gnupg/gpg.conf to set the default key. Firstly get the ID of the key:

$ gpg --list-secret-keys

Then add it to ~/.gnupg/gpg.conf with this line:

$ default-key [YOUR_KEY_ID]

Update the key with `gpg`

Make any required changes to the key with the gpg command-line tool:

$ gpg --edit-key [YOUR_KEY_ID]

Some useful gpg> commands are:

help    - show help
list    - list key and user IDs
uid N   - select user ID N
adduid  - add a user ID
deluid  - delete selected user IDs
trust   - change the ownertrust
save    - commit your changes and quit

Don’t forget to save after making your changes!

Push the updated key to Keybase

Now that you’ve updated your local copy of the key, push it back to Keybase with:

$ keybase pgp update

Export the updated public key to GitHub

Export your local key to the clipboard with:

$ keybase pgp export | pbcopy

Go to GitHub > Settings > SSH and GPG keys

Add a ‘New GPG key’, or ‘Delete’ your existing one first if you’re updating it.

Signing Git commits with your Keybase key

Add -S [YOUR_KEY_ID] or --gpg-sign=[YOUR_KEY_ID] to your git commit commands to sign the commit using the specified key. You can replace [YOUR_KEY_ID] with any email address added as a uid in the key.

Run these lines to update your global config to sign git commits by default:

$ git config --global user.signingkey [YOUR_KEY_ID]
$ git config --global core.gpgsign true

These can additionally be set or unset on a per-project basis.

Adding --no-gpg-sign to a git commit command will turn off signing for that commit only.

Adding --show-signature to git log commands will show signatures in the git commit log.

Building a basic UI-clone of Instagram using Elm - Part 3

Ben Booth — Wed, 07 Dec 2016 12:34:00 GMT

This article is a part of a series, you should read part 1 and part 2 if you haven’t already. Alternatively you can get the code from the end of the last article here and continue along. You can view the finished app here and all of the source code is available here.

Implement the single post view

Now that we can navigate to a new page/view, let’s start building out the view properly. If you recall where we left off, the SinglePost case in View.viewPage was just rendering the postId that was parsed from the URL. We need to use this postId to find the right Post in model.posts. We’ll define a View.getPost helper function to do this now.

-- View.elm

getPost : String -> List Post -> Maybe Post
getPost postId posts =
    let
        postsById = List.filter (\post -> post.id == postId) posts
    in
        List.head postsById

We need to return a Maybe Post because the postId string parsed from the URL might not be a valid Post.id, or there might just not be a Post in model.posts that matches the postId. We approach the problem by filtering the list to Posts with a Post.id matching postId which should leave 1 or 0 Posts in the postsById list (we’re trusting the data source here that Post.id is unique), then we take the first item from the filtered list, which will return a Maybe Post. Now let’s update the SinglePost case of View.viewPage to use View.getPost and View.viewPost to render a single post.

-- View.elm

viewPage : Model -> Html Msg
viewPage model =
    case model.page of
        ListOfPosts ->
            -- ...

        SinglePost postId ->
            case getPost postId model.posts of
                Just post ->
                    div [ class "photo-single" ]
                        [ viewPost model post ]

                Nothing ->
                    div []
                        [ text ("Post " ++ postId ++ " not found.") ]

You should be able to recompile and open the app in the browser now and the SinglePost view will render a single post, which is fun, but no more useful than the ListOfPosts view. We’ll load and display the list of comments (if any) on the SinglePost view next.

Load and display comments

We’ve got a bit of work to do in order to load the comments, but thankfully it’s all derivative of things we’ve already done. Firstly, download all of the *.json files from here and save them to data/*.json. If you inspect one of the files you’ll notice that it’s filename is a {Post.id}.json and the JSON data looks like this:

[
  ...,
  {
    "id": "17856770641073526",
    "username": "tiktoktikkdotcom",
    "time": 1478756236,
    "text": "This is definitely first rated!"
  },
  ...
]

Basically for each Post we have a {Post.id}.json with the list of comments for that post. We only care about the "username" and "text" properties for now, let’s firstly define a type alias in Types.elm and a decoder in Rest.elm.

-- Types.elm

type alias Comment =
    { username : String
    , text : String
    }

-- Rest.elm

import Types exposing (Msg(..), Post, Comment)

decodeComments : Json.Decoder (List Comment)
decodeComments =
    list <|
        map2 Comment
            (field "username" string)
            (field "text" string)

Most of this is pretty similar to what we already did with with the Post type and decoder. Notice that we’ve used Json.Decoder.map2 to extract two properties from each JSON object. While we’re in Rest.elm let’s also add a function that takes a Post.id and loads it’s associated JSON comments file.

-- Rest.elm

getPostComments : String -> Cmd Msg
getPostComments postId =
    Http.send (FetchComments postId) <|
        Http.get ("data/" ++ postId ++ ".json") decodeComments

Again this is pretty similar to Rest.getPosts that we defined previously, except that we’re taking a postId parameter, and we also pass the postId through to the FetchComments action. We should now add FetchComments to the Types.Msg union type and while we’re in Types.elm we should add the lists of Comments to Types.Model and update Types.initialModel to initialise it. We’ll store the lists of Comments in a Dict which is provided by elm-lang/core, but we need to import it before we can use it. The keys in our Dict will be Post.ids and the values will be List Comment. Note that Dict.empty just initialises an empty Dict.

-- Types.elm

import Dict exposing (Dict)

type alias Model =
    { posts : List Post
    , comments : Dict String (List Comment)
    , page : Page
    }

initialModel : Page -> Model
initialModel page =
    Model [] Dict.empty page

type Msg
    = FetchPosts (Result Http.Error (List Post))
    | FetchComments String (Result Http.Error (List Comment))
    | -- ...

Now we should move onto State.elm to handle the FetchComments action in State.update, don’t forget to import Dict here too.

-- State.elm

import Dict exposing (Dict)

update : Msg -> Model -> (Model, Cmd Msg)
update msg model =
    case msg of
        -- ...

        FetchComments postId (Ok comments) ->
            { model
                | comments = Dict.insert postId comments model.comments
                , posts = List.map (setPostComments postId <| List.length comments) model.posts
            } ! []

        FetchComments postId (Err _) ->
            update (FetchComments postId <| Ok []) model

setPostComments : String -> Int -> Post -> Post
setPostComments postId numberOfComments post =
    if post.id == postId then
        { post | comments = numberOfComments }
    else
        post

Just like with FetchPosts, we actually get a Result and need to handle the Err case as well as the Ok case. I decided that for the Err case we’d just call update again but this time passing Ok [], which as we’ll see next will initialise the Dict entry for the given postId to an empty list of Comments. The Ok case needs to do two things, firstly we insert the list of Comments into the Dict with Dict.insert, then we need to update the counter in the Post.comments property of the Post with a Post.id matching postId. Unlike the IncremementLikes case where we defined a helper function inside the case block, we define setPostComments separately because we’ll be reusing this function when we add and remove comments. setPostComments takes a Post.id, an updated number of Comments and a Post, we use it in the FetchComments case to List.map over model.posts.

The final change that we need to make in State.elm is to actually load the Comments by calling Rest.getPostComments. In both State.init and State.update we’ll split the Just page case to have slightly different behaviour for Just ListOfPosts and Just SinglePost. Just ListOfPosts will basically be the same as the current Just page case in both cases, but for Just SinglePost we’ll want to call Rest.getPostComments in both cases.

-- State.elm

init : Navigation.location -> (Model, Cmd Msg)
init location =
    case UrlParser.parseHash pageParser location of
        Just ListOfPosts ->
            initialModel ListOfPosts
                ! [ Rest.getPosts
                  ]

        Just (SinglePost postId) ->
            initialModel (SinglePost postId)
                ! [ Rest.getPosts
                  , Rest.getPostComments postId
                  ]

        Nothing ->
            -- ...

update : Msg -> Model -> (Model, Cmd Msg)
update msg model =
    case msg of
        -- ...

        NavigatedTo maybePage ->
            case maybePage of ->
                Just ListOfPosts ->
                    { model | page = ListOfPosts }
                        ! []

                Just (SinglePost postId) ->
                    { model | page = SinglePost postId }
                        ! [ Rest.getPostComments postId
                          ]

                Nothing ->
                    -- ...

Now we need to actually show the comments. Firstly we’ll define a getPostComments helper function to return a List Comment from model.comments. Because Dict.get returns a Maybe we need to handle the Nothing case, we’ll just return an empty List. Don’t forgot to import Dict here too.

-- View.elm

import Dict exposing (Dict)

getPostComments : String -> Dict String (List Comment) -> List Comment
getPostComments postId comments =
    case (Dict.get postId comments) of
        Just postComments ->
            postComments

        Nothing ->
            []

Next we need to make some changes to the existing View.viewPost function. We’ll determine if we should show the list of Comments by inspecting model.page, we only want to show them for the SinglePost case, so we’ll just show an empty div for the ListOfPosts case. We’ll add the comments directly after p.photo-caption.

-- View.elm

viewPost : Model -> Post -> Html Msg
viewPost model post =
    let
        displayComments =
            case model.page of
                SinglePost postId ->
                    viewComments model post

                ListOfPosts ->
                    div [] []
    in
        -- ...
        , p [ class "photo-caption" ] [ text post.text ]
        , displayComments
        -- ...

Finally we’ll define the viewComments and viewComment functions. viewComment defines the bulk of the DOM structure, but returns a (String, Html Msg) which if you recall is used by Html.Keyed.node. In viewComments we’ll use List.indexedMap to pass an Int index as well as the Comment through to viewComment. viewComments then just returns a Html.Keyed.node using the list of DOM returned by the viewComment calls for each Comment.

-- View.elm

viewComments : Model -> Post -> Html Msg
viewComments model post =
    let
        listOfComments =
            List.indexedMap (viewComment post) <|
                getPostComments post.id model.comments
    in
        Html.Keyed.node "div"
            [ class "comments" ] <|
            listOfComments


viewComment : Post -> Int -> Comment -> (String, Html Msg)
viewComment post index comment =
    ( toString index
    , div [ class "comment" ]
        [ p []
            [ strong [] [ text comment.username ]
            , text comment.text
            ]
        ]
    )

At this stage you should be able to recompile and test the app in the browser again. When you click through to any of the SinglePost views you should see a list of Comments! Let’s remove some of those comments next.

Implement the remove comment button

We’ll add the ability to remove comments by adding a little inline “x” button after each comment. Using our established pattern we’ll firstly add the RemoveComment action to Types.Msg.

-- Types.elm

type Msg
    = -- ...
    | RemoveComment String Int

The String will be a Post.id and the Int will be an index representing the location of the Comment in the List. Let’s add the handler for this action in State.update now. We’re going to use a function from List.Extra which is provided by elm-community/list-extra, so install it now with elm package install elm-community/list-extra and import List.Extra.

-- State.elm

import List.Extra

update : Msg -> Model -> (Model, Cmd Msg)
update msg model =
    case msg of
        -- ...

        RemoveComment postId index ->
            let
                removePostComment : Maybe (List Comment) -> Maybe (List Comment)
                removePostComment comments =
                    case comments of
                        Just comments ->
                            Just <| List.Extra.removeAt index comments

                        Nothing ->
                            Nothing

                numberOfPostComments =
                    getNumberOfPostComments postId model.comments
            in
                { model
                    | comments = Dict.update postId removePostComment model.comments
                    , posts = List.map (setPostComments postId <| numberOfPostComments - 1) model.posts
                } ! []

getNumberOfPostComments : String -> Dict String (List Comment) -> Int
getNumberOfPostComments postId comments =
    case Dict.get postId comments of
        Just postComments ->
            List.length postComments

        Nothing ->
            0

We need the handler to firstly remove the Comment from the right location in model.comments, which is determined by the index in the List Comment where the Dict key matches the passed in postId, then it needs to update the comments counter for the right Post in model.posts. We’ve defined a couple of helper functions for this, firstly getNumberOfPostComments which we’ve defined independently because we’ll use it again soon when we want to add a new Comment, it just gets the List Comment by using Dict.get with the passed in postId, then either returns the length of the list, or 0 if the Dict doesn’t have an entry matching the postId. removePostComment is defined in the RemoveComment handler because it’s only ever used here. We use List.Extra.removeAt to attempt to remove from the provided List of Comments the item at the provided index, it returns the updated List. In the model record update statement we use Dict.update with the removePostComment function, then similar to the FetchComments handler we use List.map with setPostComments to update the number of Comments for the given Post.

Finally let’s add the actual “x” button into the view, just add the following line to View.viewComment immediately after , text comment.text:

-- View.elm

viewComment : Post -> Int -> Comment -> (String, Html Msg)
viewComment post index comment =
    -- ...
    , text comment.text
    , button [ onClick <| RemoveComment post.id index, class "remove-comment" ] [ text "×" ]
    -- ...

Recompile and open the app in your browser, click through to one of the SinglePost views and remove comments to your heart’s content by clicking the little “x” button next to each comment. You might notice that if you remove some comments, navigate back to the ListOfPosts view and then back to the same SinglePost view, the comments that you just removed will all be back! This is because we always load the list of Comments when we navigate to the SinglePost view. To fix it we’ll update the Ok case of FetchComments in State.update to check if there’s an existing entry in Dict for the postId and only update the model if it’s a new entry in the Dict.

-- State.elm

update : Msg -> Model -> (Model, Cmd Msg)
update msg model =
    case msg of
        -- ...

        FetchComments postId (Ok comments) ->
            case Dict.get postId model.comments of
                Just existingComments ->
                    model ! []

                Nothing ->
                    { model
                        | comments = Dict.insert postId updatedComments model.comments
                        , posts = List.map (setPostComments postId <| List.length updatedComments) model.posts
                    } ! []

Recompile and test it in the browser. Removed comments now stay removed! …until you refresh the page, but that’s another story. Let’s move onto the final piece of this puzzle, adding a new comment.

Implement the add comment form

This last step will require updating text in some input fields. Starting in Types.elm, we will add and initialise a newComment property to the Model record and we’ll need 3 new actions in Msg, one for each of the two input fields, and one for actually adding the comment.

--Types.elm

type alias Model =
    { posts : List Post
    , comments : Dict String (List Comment)
    , page : Page
    , newComment : Comment
    }

initialModel : Page -> Model
initialModel page =
    Model [] Dict.empty page (Comment "" "")

type Msg
    = -- ...
    | UpdateCommentUsername String
    | UpdateCommentText String
    | AddComment String Comment

Moving to State.elm, the two UpdateComment... actions are quite simple and basically the same, they just update the corresponding property in model.newComment.

-- State.elm

update : Msg -> Model -> (Model, Cmd Msg)
update msg model =
    case msg of
        -- ...

        UpdateCommentUsername username ->
            let
                comment = model.newComment
            in
                { model
                    | newComment = { comment | username = username }
                } ! []

        UpdateCommentText text ->
            let
                comment = model.newComment
            in
                { model
                    | newComment = { comment | text = text }
                } ! []

The AddComment action is more complex than these, but quite similar to the RemoveComment action. The addPostComment helper function that we’ll define is also used by Dict.update, but either concatenates the new Comment onto the existing List of Comments or returns a new List containing just the new Comment. We also need to reset the two input fields after adding the comment.

-- State.elm

update : Msg -> Model -> (Model, Cmd Msg)
update msg model =
    case msg of
        -- ...

        AddComment postId comment ->
            let
                addPostComment : Maybe (List Comment) -> Maybe (List Comment)
                addPostComment comments =
                    case comments of
                        Just comments ->
                            Just <| comments ++ [ comment ]

                        Nothing ->
                            Just [ comment ]

                numberOfPostComments =
                    getNumberOfPostComments postId model.comments
            in
                { model
                    | comments = Dict.update postId addPostComment model.comments
                    , posts = List.map (setPostComments postId <| numberOfPostComments + 1) model.posts
                    , newComment = Comment "" ""
                } ! []

Finishing up with View.elm we need to define View.viewCommentForm to build the actual form DOM, then use it in View.viewComments. We actually append the comment form to the list of comments, so it also needs to return a (String, Html Msg) tuple for the Html.Keyed.node. Remember to expose onInput and onSubmit from the Html.Events import.

-- View.elm

import Html.Events exposing (onClick, onInput, onSubmit)

viewComments : Model -> Post -> Html Msg
viewComments model post =
    -- ...
        Html.Keyed.node "div"
            [ class "comments" ] <|
            listOfComments
                ++ [ viewCommentForm model post ]

viewCommentForm : Model -> Post -> (String, Html Msg)
viewCommentForm model post =
    ( "comment-form"
    , Html.form [ onSubmit <| AddComment post.id model.newComment, class "comment-form" ]
        [ input
            [ type_ "text"
            , value model.newComment.username
            , onInput UpdateCommentUsername
            , placeholder "author..."
            ]
            []
        , input
            [ type_ "text"
            , value model.newComment.text
            , onInput UpdateCommentText
            , placeholder "comment..."
            ]
            []
        , input
            [ type_ "submit"
            , hidden True
            ]
            []
        ]
    )

By now this should all look pretty straight-forward. We bind the value of each input to properties in model.newComment and we trigger UpdateComment... actions when either of the inputs change. We trigger the AddComment action with the forms onSubmit event.

Recompile and open the app in your browser and you should now be able to leave any nasty comments that you want anonymously without anybody else ever seeing them!

The end!

You can view the code that we’ve built here. We’ve covered quite a lot in building this example:

Bootstrap an Elm application
Define and handle changes to the model state object
Define a DOM structure which responds to changes in the model
Get data with HTTP requests and decode a JSON response
Add navigation with multiple pages/views, run commands after navigating to a new page
Define and handle changes to forms

This doesn’t solve all of the problems that you’ll face trying to build a front-end web application with Elm, but these foundations should give you enough to build most of what you require. Hopefully this has been an interesting exercise for you and encourages you to try and build something interesting with Elm.

If you missed one of the earlier parts, feel free to go back and read them too:

Part 1 - Setup an Elm app and load posts from a JSON file
Part 2 - Build the main list view and add navigation

Building a basic UI-clone of Instagram using Elm - Part 2

Ben Booth — Fri, 02 Dec 2016 12:32:00 GMT

This article is a part of a series, you should read part 1 if you haven’t already. Alternatively you can get the code from the end of the last article here and continue along. You can view the finished app here and all of the source code is available here.

Implement the main list of posts view

Getting a list of posts is all well and good, but not particularly exciting if we’re just going to show a count of the number of posts. We’ll build the UI for the main list of posts now, and as you might have guessed, most of the work for this step will be in View.elm. First we’ll get some house-keeping out of the way. We want more control over index.html so add or replace your index.html with this:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Elmstagram</title>
    <link rel="stylesheet" href="css/styles.css" />
  </head>
  <body>
    <div id="app"></div>

    <script src="js/app.js"></script>
    <script>
      Elm.App.embed(document.getElementById('app'));
    </script>
  </body>
</html>

Download and save the final CSS from here to css/styles.css, then download all of the fonts from here to fonts/*. Next, move posts.json to data/posts.json and update the URL in Rest.getPosts to "data/posts.json".

We’re no longer inlining the compiled JavaScript code, so we need to manually bootstrap it after the script loads. We’ll need to build js/app.js and with elm make:

$ elm make App.elm --output js/app.js

You should be able to start or restart your static HTTP server and see that everything is still working.

OK, onto the view changes. The View.rootView is, as the name suggests, going to be the root view. When we have multiple pages the structure defined here will be common to all pages. Change it to look as follows then download and save this logo to img/logo.svg.

-- View.elm

import Html.Attributes exposing (..)

rootView : Model -> Html Msg
rootView model =
    div [ id "app-root" ]
        [ main_ []
            [ div [ class "photo-list" ] <|
                List.map (viewPost model) model.posts
            ]
        , nav []
            [ div [ class "nav-inner" ]
                [ a [ href "./", class "nav-logo" ]
                    [ img [ src "./img/logo.svg" ] []
                    , text "Elmstagram"
                    ]
                ]
            ]
        , footer []
            [ div [ class "footer-inner" ]
                [ p []
                    [ a [ href "https://github.com/bkbooth/Elmstagram.git" ] [ text "View Source" ]
                    , text "|"
                    , a [ href "./" ] [ text "Elmstagram" ]
                    ]
                ]
            ]
        ]

We’ve added Html.Attributes as another import where we expose everything, this is because similar to Http we will end up using a large number of the functions. This should all be fairly self-explanatory, each DOM node takes a list of attributes followed by a list of child nodes. The only other item of interest is where we List.map with a view function over our list of Posts in model.post. We’ll define View.viewPost now, we want viewPost to be reusable for each post in the main list and for when we click through to a single post. The function will look like this (don’t forget to add Post to the import Types line).

-- View.elm

import Types exposing (Model, Msg(..), Post)

viewPost : Model -> Post -> Html Msg
viewPost model post =
    figure [ class "photo-figure" ]
        [ div [ class "photo-wrap" ]
            [ a [ href "#" ]
                [ img [ src post.media, alt post.text, class "photo" ] []
                ]
            ]
        , figcaption []
            [ div [ class "caption-button" ]
                [ button [ class "like-button" ] [ text "♡" ]
                ]
            , div [ class "caption-content" ]
                [ div [ class "photo-stats" ]
                    [ strong [] [ text <| toString post.likes ]
                    , text " likes, "
                    , strong [] [ text <| toString post.comments ]
                    , text " comments"
                    ]
                , p [ class "photo-caption" ] [ text post.text ]
                ]
            ]
        ]

Again, this is fairly straight-forward building of a DOM tree, note where we access the properties of the Post that is passed into the function (this function is called for every Post in model.posts). At this stage you should be able to rebuild js/app.js with elm make App.elm --output js/app.js, start your static HTTP server if it isn’t still running and reload http://localhost:8080 in your browser to see the layout and list of posts.

An optimisation that we can and should make is to use Html.Keyed to turn each node in our list of Posts into a keyed node to help with Elm’s rendering. This is important for lists where items are getting added, moved, removed, etc. but also when we add navigation between views that are using similar elements. In an early version of this app before adding Html.Keyed, whenever I navigated back to the main list view from a single post view, the first item in the list was always the post that I’d just been looking at momentarily. Using Html.Keyed fixes problems like these, so lets use it now. Because we want to make use of the current View.viewPost implementation on the single post view, we’ll keep it as is and create a wrapper function that returns a keyed node. Add View.viewKeyedPost like this:

-- View.elm

import Html.Keyed

viewKeyedPost : Model -> Post -> (String, Html Msg)
viewKeyedPost model post =
    ( post.id
    , viewPost model post
    )

As you can see, a keyed node is a (String, Html Msg) tuple instead of just a Html Msg node, the string is the unique identifier for that node, in this case the post.id. Change div.photo-list to a keyed node which uses viewKeyedPost like this View.rootView

-- View.elm

Html.Keyed.node "div"
    [ class "photo-list" ]
    <| List.map (viewKeyedPost model) model.posts

Recompile and reload to see that everything should still be working.

Implement the “Like” button

Now let’s implement the functionality for the “like” button which is the heart next to the number of likes and comments on each post. It would be fairly easy to implement double-click to like similar to Instagram, but I’ve decided to reserve clicking on the image for navigating to the single post view. A general procedure which we’ll follow now for adding a new action is to:

add the new action to the Types.Msg union type
handle the action in State.update
use/call the action somewhere in the View

Firstly, update Types.Msg to look like this:

-- Types.elm

type Msg
    = FetchPosts (Result Http.Error (List Post))
    | IncrementLikes String

The String parameter after IncrementLikes will be a Post.id. Next add this to the State.update case statement after the two FetchPosts cases:

-- State.elm

update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case action of
        -- ...

        IncrementLikes postId ->
            let
                incrementPostLikes : String -> Post -> Post
                incrementPostLikes postId post =
                    if post.id == postId then
                        { post | likes = post.likes + 1 }
                    else
                        post
            in
                { model
                    | posts = List.map (incrementPostLikes postId) model.posts
                } ! []

This looks significantly more complex than the previous State.update cases, but most of it is the definition of the incrementPostLikes function. We could move this function out but this is the only place where the function is used, so I find it simpler to just keep it defined here. The function itself just takes a String representing a Post.id and a Post, if the passed in postId matches the passed in post.id we increment the likes property and return the updated post, otherwise we just return the post as is. We use this function in the model update to List.map over the model.posts. Basically all this does is return a new model, with an updated posts property, where any Post with the same Post.id will have it’s likes property incremented.

Finally, we need to update View.viewPost. In View.elm, you should still have import Html.Events exposing (onClick) from the starting example, if not add it back in now. Find button.like-button in View.viewPost and add an onClick handler like this:

-- View.elm

button [ onClick <| IncrementLikes post.id, class "like-button" ] [ text "♡" ]

Now you should be able to recompile and test the app in the browser. Click any of the heart icon “like” buttons and the likes counter for the corresponding post will increment, exciting!

Add a second page and navigation

Just about any reasonably complex web application will contain multiple views and manage the navigation between those views by using the URL. Storing some of the application state in the URL also makes it easier to share a link to a particular page or view. There are two libraries provided by Elm for handling changes in the URL, namely elm-lang/navigation and evancz/url-parser. Go ahead and install both of them now with elm package install elm-lang/navigation and elm package install evancz/url-parser. It’s worth noting that Elm has been deliberate about calling this set of behaviours “navigation” and not “routing” as you would see in most front-end libraries and frameworks.

The first change required to introduce navigation to an Elm app is right at the top in App.elm, elm-lang/navigation provides Navigation.program which we use to create App.main instead of Html.app. Replace import Html with import Navigation, then replace Html.program with Navigation.program and pass State.hashParser is the first parameter before the record definition, we’ll define State.hashParser shortly. App.main should now look like this.

-- App.elm

import Navigation

main : Program Never Model Msg
main =
    Navigation.program State.hashParser
        { init = State.init
        , update = State.update
        , subscriptions = State.subscriptions
        , view = View.rootView
        }

Next we need to update Types.elm, we’ll need Model to keep track of the current page. Firstly define a new union type Page with the pages that you need, in this case ListOfPosts for the main list of posts, and SinglePost String for the single post view where the String will be a Post.id. We then need to add a new page property to the Model record. We’ll also need to update Types.initialModel to set the initial Page, but we’ll take the initial Page as a parameter because we’ll parse the initial URL to work out what the initial Page should be in State.init. We also need to add a new action to the Msg union type to handle navigation changes, we’ll call it NavigatedTo and it will take a single Maybe Page parameter.

-- Types.elm

type alias Model =
    { posts : List Post
    , page : Page
    }

initialModel : Page -> Model
initialModel page =
    Model [] page

type Msg
    = -- ...
    | NavigatedTo (Maybe Page)

type Page
    = ListOfPosts
    | SinglePost String

Next up is State.elm and we’ve got a few changes that we need to make. We need to define some utility functions that map URL’s to a Page and vice-versa:

-- State.elm

import Navigation
import UrlParser exposing (..)

hashParser : Navigation.Location -> Msg
hashParser location =
    NavigatedTo <|
        UrlParser.parseHash pageParser location

pageParser : Parser (Page -> a) a
pageParser =
    oneOf
        [ map ListOfPosts <| s ""
        , map SinglePost <| s "view" </> string
        ]

toUrl : Page -> String
toUrl page =
    case page of
        ListOfPosts ->
            "/"

        SinglePost postId ->
            "/view/" ++ postId

State.hashParser is the function that we passed as the first argument to App.main earlier. It’s role is to translate changes in Navigation.Location to messages that State.update can handle, in this case NavigatedTo which we defined in the last step. To do this it uses UrlParser.parseHash which takes a UrlParser.Parser and a Navigation.Location record. UrlParser exports a number of functions to help with building an UrlParser.Parser which matches the expected URL’s in the app and maps them to Pages. UrlParser.parseHash actually returns a Maybe Page because it might not be able to map the URL to one of the known states of the app, you’ll need to handle this case too. Note that there is also a UrlParser.parsePath function that will run a UrlParser.Parser against the path part of the URL instead of the hash. I’ve actually used UrlParser.parsePath in the repository, but using URL paths with a single-page web application requires some server-side support, UrlParser.parseHash is easier for examples because we can just use a simple HTTP server. Finally State.toUrl just returns a URL String based on a Page. Now we need to replace State.init with this:

-- State.elm

init : Navigation.Location -> (Model, Cmd Msg)
init location =
    case UrlParser.parseHash pageParser location of
        Just page ->
            initialModel page
                ! [ Rest.getPosts
                  ]

        Nothing ->
            initialModel ListOfPosts
                ! [ Rest.getPosts
                  , Navigation.modifyUrl <| toUrl ListOfPosts
                  ]

Because we’re using Navigation.program, our State.init function now gets passed a Navigation.Location which is the URL at the time that the application is initialised. We parse this to a Maybe Page using UrlParser.parseHash and State.pageParser. If it matches a page we pass the page to Types.initialModel, otherwise we explicitly set the page to ListOfPosts and update the URL with Navigation.modifyUrl and State.toUrl. You might want to redirect to a 404 Not Found page instead. In each case we still call Rest.getPosts to load the post data. To finish up the changes in State.elm, we need to add the NavigatedTo case to State.update:

-- State.elm

update msg model =
    case msg of
        -- ...

        NavigatedTo maybePage ->
            case maybePage of
                Just page ->
                    { model | page = page }
                        ! []

                Nothing ->
                    model
                        ! [ Navigation.newUrl <| toUrl ListOfPosts
                          ]

This is pretty similar to what we just did in State.init, except that we don’t need to trigger another action if maybePage is a known Page, just update model.page. If it’s not a known Page, we redirect to the ListOfPosts page using Navigation.newUrl. Navigation.newUrl updates the state and write a new URL into the browser history, whereas Navigation.modifyUrl updates the URL without adding a new state to the browser history.

We’ll add the proper UI for the single post view in the next part, for now we’ll just show the Post.postId. We’ll create a new View.viewPage function to change the view based on the current page. Replace Html.Keyed.node ... in View.rootView with just viewPage model and move the Html.Keyed.node ... block to View.viewPage under the ListOfPosts case. We’ll just put a dummy view in for the SinglePost case for now. Don’t forget to expose Page(..) from the Types import, or you might want to just expose everything from Types now.

-- View.elm

import Types exposing (..)

rootView : Model -> Html Msg
rootView model =
    div [ id "app-root" ]
        [ main_ []
            [ viewPage model
            ]
        -- ...

viewPage : Model -> Html Msg
viewPage model =
    case model.page of
        ListOfPosts ->
            Html.Keyed.node "div"
                [ class "photo-list" ]
                <| List.map (viewKeyedPost model) model.posts

        SinglePost postId ->
            div [ class "photo-single" ]
                [ text ("Post: " ++ postId) ]

Finally we need to update the links in View.elm to use State.toUrl. Import State and then replace both of the href "./"’s in View.rootView with href (State.toUrl ListOfPosts), then replace the href "#" in View.viewPost with href (State.toUrl SinglePost post.id). You should be able to recompile js/app.js now, start your static HTTP server and view the app in the browser.

That’s all (for now)

You can view the code that we’ve built so far here. We’ll continue building the app in Part 3:

Part 1 - Setup an Elm app and load posts from a JSON file
Part 3 - Build the single post view and add the comments form

Building a basic UI-clone of Instagram using Elm - Part 1

Ben Booth — Thu, 01 Dec 2016 02:14:00 GMT

I’ve had a fascination with functional programming for a few years now, but despite taking a quick look at Haskell I’ve not invested much time actually learning a functional language. I’ve generally tried to approach my front-end development from a functional mindset, keeping functions pure, trying not to mutate objects, always using things like map, filter and reduce to manipulate collections. One of my main complaints/observations with functional languages is that they don’t seem to be immediately practical, there seems to be a big step between picking up the fundamentals and basics of the language, and actually building something useful with it. Sometime recently I became aware of Elm and after looking into it quickly, it seemed to address exactly this complaint of mine. There seemed to be a quick turnaround from picking up the basics of the language and being able to actually build something with it, specifically a front-end web application. I read through the An Introduction to Elm book and wanted to build one of my side project ideas with Elm, but I decided that to avoid the possibility of getting overwhelmed and frustrated trying to build something ambitious with a new language, I’d build an example app that covered a lot of what I’d need for a bigger app. So, inspired by Wes Bos’ great Learn Redux course, I decided I’d build a simple UI-clone of Instagram. You can view the finished app here and all of the source code is available here. Also a big shout out to my friend Sam Gates for letting me use data from his @samgatesphotography account for this example app and articles.

Setting up a basic Elm app

Most of the simple examples that you see for Elm seem to have the entire codebase in a single .elm file, this is great to demonstrate how little is required to get up and running with Elm, and the advice seems to be to only break your app into separate files when you need to. I had a look around at some articles and examples and I settled on the following app structure:

project-directory/
├─ elm-package.json ─ project metadata and dependencies
├─ App.elm          ─ bootstrap app using The Elm Architecture
├─ Types.elm        ─ define Model, Msg and any other types
├─ State.elm        ─ handle all changes to state
├─ View.elm         ─ all view rendering and logic
├─ Rest.elm         ─ HTTP requests and JSON parsing
└─ Feature/         ─ a feature sub-directory
   ├─ Types.elm
   ├─ State.elm
   ├─ View.elm
   └─ Rest.elm

This should scale reasonably well, you would mostly re-use the same files as necessary in feature sub-directories. We’ll only use the top-level files for this example, but for anything more complex you would probably need to break the app into smaller features, similar to how you would compose the UI out of separate small components in other frameworks.

The first steps to get started with Elm are to install elm, create a new project directory and initialise an Elm project inside of it. Installing elm-lang/core will include elm-lang/html and initialise an elm-package.json file for the project.

$ npm install -g elm
$ mkdir Elmstagram
$ cd Elmstagram
$ elm package install elm-lang/core

The Elm Architecture is one of Elm’s great contributions to the front-end ecosystem, the concept of a single immutable state object has been used by Redux and many other similar libraries. The following files implement a very basic Elm example, and we’ll use this as a starting point for the app. Note that we won’t need Rest.elm just yet.

-- Types.elm
module Types exposing (..)

type alias Model =
    Int

initialModel : Model
initialModel =
    0

type Msg
    = IncrementLikes

-- State.elm
module State exposing (..)

import Types exposing (..)

init : (Model, Cmd Msg)
init =
    initialModel ! []

update : Msg -> Model -> (Model, Cmd Msg)
update msg model =
    case msg of
        IncrementLikes ->
            (model + 1) ! []

subscriptions : Model -> Sub Msg
subscriptions model =
    Sub.none

-- View.elm
module View exposing (..)

import Html exposing (..)
import Html.Events exposing (onClick)
import Types exposing (Model, Msg(..))

rootView : Model -> Html Msg
rootView model =
    div []
        [ h1 [] [text "Elmstagram"]
        , p [] [text ("Likes: " ++ toString model)]
        , p []
            [ button [onClick IncrementLikes] [text "Like!"]
            ]
        ]

-- App.elm
module App exposing (main)

import Html
import Types exposing (Model, Msg)
import State
import View

main : Program Never Model Msg
main =
    Html.program
        { init = State.init
        , update = State.update
        , subscriptions = State.subscriptions
        , view = View.rootView
        }

I don’t want to go into explaining this too much because this is all pretty thoroughly covered in the Elm introductory tutorials and examples. Basically the App.elm file is the entry point into the application, it must expose a main function which returns a Program as defined by The Elm Architecture. The Program requires:

an init function which provides an initial model and optionally some initial commands to run. We’ll use this next to load the list of posts.
an update function which responds to commands and updates the model.
a subscriptions function which is used to respond to external updates such as messages on a web socket. We won’t require any subscriptions for this example.
a view function which returns the UI based on the current model.

If you’ve only looked at basic Elm examples so far, the model ! [ cmd ] syntax might look a little strange, but all it does is return a (model, cmd) tuple, where it’s easy to provide a list of commands instead of just one. It also means we can just past an empty list as [] instead of explicitly using Cmd.none.

At this point you should be able to run elm make App.elm which will compile everything and produce an index.html which you can open in a browser. Click the “Like!” button to your hearts content, then we’ll move on with making things a little more interesting.

Load posts from a JSON file

Loading data from an external resource is actually fairly straight-forward, though if you’re coming from JavaScript you might find it a little tedious having to define types and decoders. It definitely becomes easier after a little practice and I believe the extra effort trade-off is worth it. You’ll basically need to define type aliases and decoders for all of the types that you’re expecting in your JSON-returning HTTP requests.

Download and save posts.json into your project directory. The JSON data looks like this:

[
  ...,
  {
    "id": "BLvMFSVB8mQ",
    "likes": 91,
    "comments": 4,
    "text": "The description or caption of the post #plusprobablysomehashtags",
    "media": "https://url.to/post.image.jpg"
  },
  ...
]

In Types.elm we need to add a new type alias Post to map the JSON data into. The type properties don’t have to match exactly to the JSON property names, but keeping them the same is the simplest for now. The type should look like this:

-- Types.elm

type alias Post =
    { id : String
    , likes : Int
    , comments : Int
    , text : String
    , media : String
    }

While we’re in Types.elm, we’ll update the Model type and the initialModel function to contain a list of Posts. Note that when we define a type in Elm we get a constructor function of the same name that creates and returns a new value of that type, the function takes the same number of arguments as properties declared in the type definition and in the same order that they’re declared. So far we just have a single posts property which we’ll initialise to an empty list.

-- Types.elm

type alias Model =
    { posts : List Post
    }

initialModel : Model
initialModel =
    Model []

Next we need to define a decoder that instructs Elm how to parse JSON into types that it knows about. We need to use methods defined in Json.Decode from elm-lang/core to create the decoder. The JSON structure is an array of objects, each representing a single post. So we’ll define the decodePosts function as returning a Json.Decode.Decoder (List Post). We’ll need to create the Rest.elm file now and it will look like this:

-- Rest.elm
module Rest exposing (..)

import Json.Decode as Json exposing (..)
import Types exposing (Post)

decodePosts : Json.Decoder (List Post)
decodePosts =
    list <|
        map5 Post
            (field "id" string)
            (field "likes" int)
            (field "comments" int)
            (field "text" string)
            (field "media" string)

Note that we’ve imported Json.Decode as Json exposing(..). This means that in the annotation we can simplify Json.Decode.Decoder to Json.Decoder. We could simplify it further to just Decoder because we’ve exposed everything from Json.Decode, but I prefer to be explicit here. To avoid exposing everything from Json.Decode we’d have to either explicitly refer to each of list, map5, field, string and int as Json.list, Json.map, etc. Or list just the functions that we’re actually using in the import statement: exposing(list, map5, field, string, int). The same goes for exposing functions from Html in View.elm. I generally prefer to be explicit about only importing what I need, but for Rest.elm I’m OK with exposing everything from Json.Decode and for View.elm I’m OK with exposing everything from Html because you generally need a number of functions from both.

Reading the decoder as we’ve defined it, we want to decode the JSON into a list of Posts. We use the map5 function here because we want to take 5 properties from the JSON object. There are a number of Json.Decode.mapx functions to decode different sized JSON objects. map5 takes a function that takes 5 parameters to produce a value (in this case the default Post constructor function), followed by 5 decoders. The 5 field decoders that we’re using each take a property name to extract from the JSON object, followed by a type decoder which needs to match the JSON property type.

To load the JSON file we’ll need to install elm-lang/http (elm package install elm-lang/http) and import Http in Rest.elm. The getPosts function will look like this:

-- Rest.elm

import Http
import Types exposing (Msg(..), Post)

getPosts : Cmd Msg
getPosts =
    Http.send FetchPosts <|
        Http.get "posts.json" decodePosts

Http.get takes a URL as a string and a Json.Decode.Decoder and returns a Http.Request. Http.send takes a Msg and a Http.Request, it performs the HTTP request and sends the success/fail as a Result to the specified Msg. To actually run all of this, we need to call Rest.getPosts from somewhere in the app. We could either do it in response to another Msg (such as clicking a button), or as a part of the initialisation. Because we always want to retrieve the list of posts before the app is able to do anything interesting, we’ll do it as a part of the initialisation. In State.elm modify the init function to look like this:

-- State.elm

import Rest

init : (Model, Cmd Msg)
init =
    initialModel ! [ Rest.getPosts ]

We’ll also need to update the Types.Msg type to include the FetchPosts message and handle the message in the State.update function. Note that we’ve removed the IncrementLikes message.

-- Types.elm

import Http

type Msg
    = FetchPosts (Result Http.Error (List Post))

-- State.elm

update : Msg -> Model -> (Model, Cmd Msg)
update msg model =
    case msg of
        FetchPosts (Ok posts) ->
            { model | posts = posts } ! Cmd.none

        FetchPosts (Err _) ->
            model ! Cmd.none

The { model | posts = posts } syntax is how you update a record in Elm. It returns a new record, starting from the old record specified before the pipe, updated with any property changes after the pipe.

We’ll update the view in the next part to show the actual posts, but for now just change View.rootView to show a count of the number of posts so that we can compile and check that everything still works.

-- View.elm

rootView : Model -> Html Msg
rootView model =
    div []
        [ h1 [] [text "Elmstagram"]
        , p [] [text ("Posts: " ++ (toString <| List.length model.posts))]
        ]

Go ahead and recompile the app with elm make App.elm. Because we’ve introduced a HTTP request you won’t be able to just open the created index.html file in a browser anymore, the browser will show a CORS error when attempting to load posts.json. You’ll need to use a HTTP server to serve the example, but a static server such as http-server will be good enough for now, just install and run it in your project directory, then open http://localhost:8080 in your browser.

$ elm make App.elm
$ npm install -g http-server
$ http-server

That’s all (for now)

You can view the code that we’ve built so far here. We’ll continue building the app in the following articles:

Part 2 - Build the main list view and add navigation
Part 3 - Build the single post view and add the comments form

Running Ghost with PM2 under a different user account on a Linux server

Ben Booth — Mon, 15 Jun 2015 03:17:00 GMT

When I first setup my Ghost blog on my own server (a self-managed Linode which has been great and I highly recommend them), I installed Node.js directly under my main user account. I eventually ran into the problem of needing/wanting to use different versions of Node.js for different applications, so I uninstalled Node.js and installed/used nvm instead. It occurred to me that I might be better off running the Ghost application under a different user account, so that it could manage it’s own nvm/Node.js versions and global npm packages. I did nothing about it at the time, but I recently wanted to be able to run two applications which needed different Node.js versions simultaneously.

My Linode is running CentOS 7, but the process should be pretty similar across Linux distributions, this is an overview of how I’m setup to run Ghost:

Node.js and npm are installed and managed by nvm
The Ghost application is setup under /var/www/benbooth.co
nginx is being used as a reverse proxy to forward requests to the Ghost application
The Ghost application is always running and starts on server start using PM2
Keymetrics monitoring through PM2

Create the new user

Let’s get started, firstly you’ll need to create the new user:

[user]$ sudo useradd [username]

I’m creating a user called ghost to run my blog, so I’d run sudo useradd ghost (tip: to fully delete the user including home directory, use sudo userdel -r ghost). If you want to set a password for the new user type passwd [username]. I don’t want to be able to login directly to this user, so I’m not going to set a password, we can switch to the new user by typing:

[user]$ sudo su ghost

Which switches to the new user, but stays in the same working directory. Pass the -l (or just -) option to login to the new users’ home directory (eg. sudo su - ghost).

Setup Node.js using nvm

Next we need to install nvm and then install Node.js. Download and run the nvm installer script (this is the latest version at the time of writing, check the nvm GitHub repo for the latest version). If you haven’t already, change to the new user first sudo su - ghost.

[ghost]$ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.25.4/install.sh | bash

Then install a Node.js version and tag it as default. (You might need to source ~/.bashrc before you use nvm if you just installed it):

[ghost]$ nvm install 0.10
[ghost]$ nvm alias default 0.10

At the time of writing, Ghost requires Node.js version 0.10.* (0.10.38 is the latest at the time of writing).

Install PM2

Installing PM2 is a straight-forward npm global install:

[ghost]$ npm install -g pm2

Stop the existing Ghost instance

Next, if you haven’t already, stop the existing Ghost instance running under your user account (exit the ghost user shell to take you back to your user shell):

[user]$ pm2 stop ghost
[user]$ pm2 delete ghost
[user]$ pm2 save

This is assuming you were already running the blog using PM2 with the name ghost. pm2 save dumps the list of currently running processes to file so it can be restored later, this is one part of keeping Ghost running even after the server restarts. To cleanup the rest, run these commands too (we’ll set these up again with the new user account):

[user]$ sudo chkconfig --del pm2-init.sh
[user]$ sudo rm /etc/init.d/pm2-init.sh
[user]$ sudo rm /var/lock/subsys/pm2-init.sh

Run the Ghost application under the new user account

Next you’ll need to get Ghost running under the new user account. Firstly, change the ownership of all files (my Ghost instance is installed to /var/www/benbooth.co):

[user]$ cd /var/www/
[user]$ sudo chown -R ghost:ghost benbooth.co/

I don’t think it would be necessary, but just to be sure, I cleared out the node_modules and re-installed the dependencies under the new user account (remember to change to the new user account):

[user]$ sudo su ghost
[ghost]$ cd benbooth.co/
[ghost]$ rm -rf node_modules/*
[ghost]$ npm install --production

Finally, run the Ghost application using PM2 and save the running PM2 processes to file:

[ghost]$ NODE_ENV=production pm2 start index.js --name "ghost"
[ghost]$ pm2 save

Persist Ghost application across server restarts

Keeping PM2 and your Ghost application running across server restarts is a little different depending on your OS/distribution, but PM2 will try to help you as much as possible. Just run:

[ghost]$ pm2 startup [platform]

For me, running CentOS, I run pm2 startup centos. This will not work because it needs to be run using sudo and I don’t want to give my ghost user sudo permission. It will give you a full command that you can run using sudo but linked to the ghost user, copy that command. Now exit from the ghost shell back to your user shell and either run the copied command using sudo, or sudo su to get a root shell, and then run the copied command.

At this stage I found that the startup script wasn’t actually bringing up the PM2 daemon, I had to manually edit the /etc/init.d/pm2-init.sh file to fix an issue (I’m assuming this is a bug, so should be temporary):

[user]$ sudo vim /etc/init.d/pm2-init.sh

Look for the line USER=[username]. In my case, this was set to USER=root and I just had to change it to USER=ghost and save the file.

Extra: Add Keymetrics monitoring

Keymetrics offers good free monitoring for PM2 applications, if you haven’t already, register for an account. You’ll get a private key and a secret key. Linking it to your PM2 instance is super-simple:

[ghost]$ pm2 link [YOUR_SECRET_KEY] [YOUR_PUBLIC_KEY]

If you keep an eye on the Keymetrics dashboard, you should start seeing a heartbeat from your server shortly.

If you already had Keymetrics running under your user account, and aren’t running any other PM2 applications, feel free to delete the Keymetrics link:

[user]$ pm2 link delete [YOUR_PUBLIC_KEY]

Writing a JavaScript Promises Library

Ben Booth — Mon, 04 May 2015 12:16:00 GMT

Updated 29/05/2015

My first exposure to JavaScript Promises was at a JavaScript meetup a couple of years ago and despite being a talk by a very good presenter, it was an early stage in my JavaScript understanding and most of the topic went over my head. Nowadays Promises are quite common and most developers will probably have had some level of exposure, whether they understand them or not. They’re part of the EcmaScript 6 (ES6) specification so if you don’t understand them, now is a great time to learn.

We’re going to write an implementation of a JavaScript Promises library, and hopefully this helps you reading it and me writing it to better understand the workings of Promises. Let’s dive right into the example and a bit of an explanation of how Promises are used. For more information, check out Dr. Axel Rauschmayer’s article on ES6 Promises or Jake Archibald’s article on Javascript Promises.

Using Promises and the demo app

The basic usage of Promises is something like below, so that’s where we’re going to start. doSomething() is going to do something asynchronous and then if it succeeds, we want to be able to use or manipulate the resulting value (if any) from doSomething() in the success function. If something goes wrong in doSomething() we want to be able to handle the error in the failure function.

doSomething().then(
  function(value) {
    // success
  },
  function(error) {
    // failure
  }
);

Take a look at script.js in the demonstration repository at branch step0 for how we’ll use the Promise library for the initial implementation.

button.addEventListener('click', function clickListener() {
  setLoading(true);
  fetch(imgUrl, { responseType: 'blob' }
    .then(function(result) {
      setLoading(false);
      img.src = URL.createObjectURL(result);
    }, function(error) {
      setLoading(false);
      console.error('Got no image!', error);
    });
});

We’re fetching an image, then on success we stop the loading spinner and set the <img>.src to an Object URL containing the loaded image data. On failure we still stop the loading spinner and log the error. We’ll improve on this and remove the duplication as we improve the Promise library.

Inside doSomething() is where we’ll actually setup our Promise, start an asynchronous task and then ‘resolve’ (execute the success handler function) or ‘reject’ (execute the failure handler function) the Promise. A Promise can only be ‘settled’ (either ‘resolved’ or ‘rejected’) once. For the ES6 standard of Promises, we pass a function to the new Promise() constructor. The function has two parameters resolve and reject which are both functions that we use to resolve or reject the Promise after our asynchronous task. In the example below, AsyncTask() is a fictional utility that we can attach success and error handler functions to the onSuccess and onError properties.

function doSomething() {
  return new Promise(function(resolve, reject) {
    var task = new AsyncTask();

    task.onSuccess = function(value) {
      resolve(value);
    };

    task.onError = function(error) {
      reject(error);
    };

    task.start();
  });
}

Looking at fetch.js in the demonstration repository at branch step0 you’ll see how I’ve wrapped an XMLHttpRequest with an asynchronous fetch() function that returns a Promise. I won’t explain this in any detail and it won’t be changing through this article, just take note of where we create the new Promise() and where we resolve and reject the Promise.

The demonstration is just a placeholder image and a ‘Get Random Image!’ button. Clicking the button downloads a random 500x500 image from lorempixel.com and replaces the placeholder image with the downloaded image data.

To run the demonstration you’ll need to clone the git repository, git checkout the correct branch (in this case step0) and then serve the files using a HTTP server. If you have Python 2 or Python 3 installed, the easiest is to just run python -m SimpleHTTPServer or python3 -m http.server respectively from the command line inside the cloned git repository.

Basic success/failure handling

If you try running the demonstration now, you’ll get an error because promise.js is just an empty stub at the moment. To get the demonstration working, we’ll need to flesh out the constructor function and implement the .then() method. The constructor just needs to initialise two internal properties to store the success and failure handler functions that are passed into .then(), and then it needs to call the deferred function that is passed into the constructor. We’ll need to provide the resolve and reject methods that will be called from inside the deferred function that was passed into the constructor. Our initial, very basic implementation looks like this.

// promise.js

function Promise(deferred) {
  this._success = null;
  this._failure = null;

  deferred(
    function resolve(value) {
      if (this._success) {
        this._success(value);
      }
    }.bind(this),
    function reject(error) {
      if (this._failure) {
        this._failure(error);
      }
    }.bind(this)
  );
}

Promise.prototype.then = function(success, failure) {
  if (success) {
    this._success = success;
  }
  if (failure) {
    this._failure = failure;
  }
};

This will get the current demonstration application working. In the demo repository, git checkout step1 to see it working. At the moment, you can only place a single .then() after the returned Promise from fetch(), so we just log the error if you have no network connection or request a bad URL. Change fetch(imgUrl, { responseType: 'blob' }); to fetch(errorUrl, { responseType: 'blob' }); to demonstrate this. Don’t forget to change it back!

Handler chaining

One of the great strengths of the Promise pattern is being able to chain operations to happen after an asynchronous operation, and eventually be able to perform a number of asynchronous operations in a style that looks synchronous, or is at least easier for us to understand and reason with. We want to be able to do something like this.

method()
  .then(/* ... */)
  .then(/* ... */)
  .catch(/* ... */)
  .then(/* ... */);

Have a quick look at script.js on branch step2 to see how the demo has been changed. We don’t need to duplicate the setLoading(false) calls anymore, we can do that at the end of the chain. We’ve separated some of the processing and notice the new .catch() method. We’ll start by quickly implementing .catch() in the Promise library, it’s just a convenience function for .then(undefined, failure()).

Promise.prototype.catch = function(failure) {
  return this.then(void 0, failure);
};

The Promise() constructor doesn’t need to change at all, we’ll even keep the if (this._success) { ... } and if (this._failure) { ... } checks around the handler calls because at the end of the chain the handler functions won’t be defined. Our .then() method needs to change quite substantially, the first and most important change is that to facilitate chaining .then() and .catch() handlers, we must always return a new Promise(). Next we’ll always need to define this._success() and this._failure() methods. If .then() provides a success handler we’ll call success() with the passed in value, then resolve the new Promise with the result of success(value), otherwise we’ll just resolve the new Promise with the passed in value which just hands the passed in value along to the next handler in the chain. If .then() provides a failure handler the processing is quite similar, we’ll call failure() with the passed in error and then because the error should be handled after the failure handler, we resolve the new Promise with the result of failure(error). If there’s not a failure handler provide, we just pass the error down the chain. The revised .then() method looks like this.

Promise.prototype.then = function(success, failure) {
  return new Promise(
    function(resolve, reject) {
      // Always define this._success() to forward success value if not handled locally
      this._success = function(value) {
        if (success) {
          // Handle success value locally, then pass on new success value
          resolve(success(value));
        } else {
          // No local success handler, pass on success value
          resolve(value);
        }
      };

      // Always define this._failure() to forward error if not handled locally
      this._failure = function(error) {
        if (failure) {
          // Handle error locally, then pass on new success value
          resolve(failure(error));
        } else {
          // No local failure handler, pass on error
          reject(error);
        }
      };
    }.bind(this)
  );
};

If you git checkout step2 and run the demonstration now, the functionality is unchanged, but the code to achieve it is a bit nicer.

Promises in the handler chain

One of the best things you can do with Promises is return a Promise within a handler, this lets you flatten out a chain of asynchronous operations. Take a look at script.js on branch step3 and you’ll notice that we’ve moved the .catch() handler to the top of the chain and we’re returning a new Promise via another call to fetch(), this time fetching a local fallback image.

fetch(imgUrl, { responseType: 'blob' }).catch(function(error) {
  console.error('Got no image!', error);
  console.info('Getting default image');
  return fetch(defaultImgUrl, { responseType: 'blob' });
});
//...

We only need to make one change to our this._success() handler inside the .this() method. It now needs to check if the passed in value is an instance of Promise, call .then() on it if it is a Promise and resolve/reject the outer Promise based on the result/error of the passed in Promise. Replace the line resolve(success(value)); with the following block to handle Promises as a value.

if (value instanceof Promise) {
  // Resolve/reject this Promise after the passed in Promise is resolved/rejected
  value.then(
    function(result) {
      // Handle resulting value locally, then pass on new success value
      resolve(success(result));
    },
    function(error) {
      // Pass on resulting error
      reject(error);
    }
  );
} else {
  // Handle success value locally, then pass on new success value
  resolve(success(value));
}

If you git checkout step3 and run the demonstration now, there’s one major change to the functionality. If the initial request to fetch imgUrl fails, the .catch() handler returns a new fetch request for defaultImgUrl, this is a local fallback image so loading it shouldn’t fail. Try replacing the first fetch(imgUrl, { responseType: 'blob' }); with fetch(errorUrl, { responseType: 'blob' }); to demonstrate loading the fallback image and then continuing down the chain of handlers.

Slightly more advanced

Two very useful utility functions that a Promise library should provide are Promise.race() and Promise.all(). Both of these functions take an array of Promises and return a single Promise. Promise.race() resolves or rejects it’s single returned Promise with the result or error from the first of it’s passed in Promises to resolve or reject. The rest of the passed in Promises are ignored, regardless if they resolve or reject. Promise.all() resolves it’s single returned Promise with an array of results resolved from all of the passed in Promises. The indexes of the results array match the index of the Promise that resolved the result from the passed in array of Promises. If any of the Promises passed into Promise.all() are rejected, the single returned Promise is immediately rejected with the error and all other passed in Promises are ignored, regardless if they are resolved or rejected. Promise.all() looks like this.

Promise.all([
  fetch(imgUrl, { responseType: 'blob' }), // fetch 0
  fetch(imgUrl, { responseType: 'blob' }), // fetch 1
]).then(function(results) {
  // results[0] will contain the result of fetch 0
  // results[1] will contain the result of fetch 1
});

Try and think about how you might implement Promise.race() and Promise.all(). Take a look at script.js at branches step4 and step5 for the demonstration examples of Promise.race() and Promise.all() respectively. (git checkout step4 and git checkout step5) to run them. Below are my implementations.

Promise.race()

Promise.race = function(promises) {
  var settled = false; // Keep track if any Promises have been settled

  return new Promise(function(resolve, reject) {
    promises.forEach(function(promise) {
      promise.then(
        function(result) {
          if (!settled) {
            // First Promise to resolve/reject, resolve with result and set settled flag
            resolve(result);
            settled = true;
          }
        },
        function(error) {
          if (!settled) {
            // First Promise to resolve/reject, reject with error and set settled flag
            reject(error);
            settled = true;
          }
        }
      );
    });
  });
};

Promise.all()

Promise.all = function(promises) {
  var settled = 0, // Keep track of the number of Promises settled
    results = []; // Keep track of Promise resolutions

  return new Promise(function(resolve, reject) {
    promises.forEach(function(promise, index) {
      promise.then(
        function(result) {
          // Add resolution to the same index as the Promises array
          results[index] = result;
          // Increment number of settled Promises, resolve when all are resolved
          if (++settled === promises.length) {
            resolve(results);
          }
        },
        function(error) {
          // Reject immediately if any Promises reject
          reject(error);
        }
      );
    });
  });
};

Update 29/05/2015 Kyle Simpson (@getify) took some time to review this article and gave some awesome feedback. I’ve been slowly rewriting my Promises implementation, but I haven’t had as much time to work on it as I’d like so I thought I should post an update in the meantime. Firstly, this implementation isn’t currently Promises/A+ compliant, that was never an original goal, but it is something I’m working towards now. Kyle has a lightweight Promises/A+ compliant implementation called Native Promises Only (NPO). Two very important things to note about my current implementation:

My handlers aren’t async! This is a big no-no, but relatively easily fixed by wrapping their execution in setTimeout(..., 0)

Promises should recursively resolve to eventually return a non-Promise value

Beware the DOM Reflow

Ben Booth — Fri, 14 Mar 2014 06:17:00 GMT

TL;DR

Don’t ever use a CSS transition with any CSS property that causes a DOM reflow, you will never get smooth transitions, even if you attempt to use a common hack to force GPU rendering of the transitioning DOM element. Try to use the CSS transform property instead of something like left or width for transitions.

A little background

I’ve been working on a mobile app using Cordova (PhoneGap) and AngularJS which has been quite fun to work with so far. I haven’t done any proper performance optimising yet, I’ve just been trying to stay on top of things as I notice them. One particular issue had been bothering me enough that I ended up looking into (and solving) it outside of work.

A little while ago I added a simple CSS slide animation between the app states/views but the animation was terribly choppy when testing in a browser and when testing on my phone (Xperia Z1 which isn’t exactly a slow device). It was so bad that there’s no way it could be put into a finished app, but I left it in there planning to look into eventually. My suspicion was that it was due to a DOM reflow but I had thought that the problem was refreshed data coming back from the server mid-animation causing a DOM update, reflow and the choppiness.

Recently I added a slide out menu similar to many modern mobile apps which included another CSS transition, again terribly choppy but this time it was happening on an element that was already in the DOM and was not getting refreshed data from the server each time it appeared. The slide out menu looked great and was behaving just like I’d planned but the animation choppiness was killing it so I had to investigate further.

A false solution

The first solution I ran into and seemed to be recommended (even if sparingly) by a number of sources was to use a CSS 3D transform that would have no visual effect but would theoretically offload the rendering of that element to the GPU in modern browsers.

transform: translate3D(0, 0, 0);

I wasn’t really happy with the idea of using a hack solution but I gave it a try and it didn’t even seem to be having any effect in my situation.

The solution

Finally I came across another explanation that made much more sense, I was transitioning using the left CSS property which was triggering a DOM reflow each time it changed. The solution was to use a CSS transform properly instead of as a hack, so in my case where I was basically wanting to transition the element along the x-axis I changed my start and end states from:

left: 100%; /* start */
left: 0; /* end */

To:

transform: translateX(100%); /* start */
transform: translateX(0); /* end */

Notes:

You may need to include browser targeted CSS properties such as -webkit-transform depending on your application.
This also produced the added benefit that I no longer needed to absolutely position the element that I was transitioning.

This produced silky smooth animations in both of my testing environments (browser and phone). Using a combination of the various CSS transforms (read up on them for more information) and standard CSS properties that do not cause a DOM reflow (such as opacity) I’ve been able to produce a several subtle animations in my app that are also perfectly smooth.

Pregnancy Risk Factors

Ben Booth — Tue, 11 Mar 2014 21:56:00 GMT

So I’m a guy, not a medical professional and I’m going to talk about pregnancy, this is probably one of the few seasons in life where a guy can get away with it so let me just get up on my soap box.

One of the things that has surprised me most talking to various people throughout my wife’s pregnancy is how there’s almost a negative reaction from older generations (and to a lesser extent others in the same generation) when my wife tells them that she’s following the various eating and lifestyle guidelines that are given to pregnant women. “Back in my days we never had all of these guidelines and we still managed to have children fine,” is along the lines of the average reaction.

So just in case you’re not fully aware, as a pregnant mother there are certain risk factors which you are advised to steer clear of during your pregnancy. These include obvious things like drinking alcohol, smoking and less obvious things like eating soft cheeses, eating food that’s been sitting out in a buffet or eating under-cooked meat. I’d like to acknowledge that yes, pregnant mothers have done many of these things for centuries and have still managed to have healthy babies. It is for this reason that I emphasised the phrase “risk factors” because I think it’s important that this is the reason why my wife and many other’s choose to follow the guidelines.

Pregnancy just like everything else health-related is the subject of regular and ongoing scientific study. Only with pregnancy you’re dealing with the life of a tiny, developing human. Most of us wouldn’t question when medical professionals give us a list of risk factors for something like the days leading up to a surgical procedure so why is it that many immediately question and then downplay the risk factors when dealing with pregnancy and new life?

I have a few theories, so make what you will of them…

There almost seems to be a kind of one upmanship associated with pregnancy, as if somehow mother’s want to do pregnancy better than others. This is a season of life where I’m seeing and hearing about a lot of pregnancies and I think the only thing you can be guaranteed no matter how many precautions you ignore or adhere to is that there are no guarantees how your pregnancy will go.
I think there is a generational factor to this problem where older generations talk of how they did pregnancy without all of the modern guidelines and I think in some cases this puts pressure on the younger generation of mother’s to ignore the guidelines to live up to the expectations of the older generation. I definitely don’t want to disrespect the older generations, giving birth to and raising children is a great privilege and blessing and I know that every mother seeks to do the best by their children. I’ve visited third world villages and have seen that children are both born and raised in the most desperate conditions so I think the point is that if you have access to the latest medical attention and advice you’d be unwise to ignore it.
Finally I think there is a lifestyle problem here, mother’s don’t want to give up doing, eating or drinking things that they love for the better part of a year. I think our society has a little to blame for this, we probably should honour and revere pregnancy more so that giving up luxuries for a few months doesn’t seem like such a big sacrifice.

I had very little to do with my wife making the decision that she would try to adhere to the guidelines and if I’m honest I was probably a little negative about all of the guidelines being a little over the top myself. I was incredibly proud of her making that decision though and while she hasn’t stuck to them 100% she has tried to be sensible about it. A point that she made to me at the time and I think really brings this home is that in most cases you could probably get away with not following the guidelines but imagine the devastation you would feel as a mother if you had a pregnancy where there were complications that arose that could have been avoided just by following the guidelines?

So here’s to pregnant mother’s, you’re doing something truly amazing. Try to find some time to appreciate that with everything that’s going on. No matter how you’re feeling know that you look amazing too.

Simple JavaScript template engine

Ben Booth — Sun, 29 Dec 2013 13:11:00 GMT

Around 6 months ago while learning JavaScript properly and looking for work as a JavaScript developer I started working on a pure HTML/CSS/JS version of Tetris (BlockDrop - github) to experiment and play with my new skills. It’s been a while since I’ve touched it but I just started looking at it again recently and there’s quite a lot that I’d do differently now so I started rewriting it from the ground up. I haven’t got that far with the actual rewrite but one of the things I really wanted to do differently and therefore implemented it first was a simple templating engine so that I could get all the HTML out of my JavaScript.

Setting up a module

First things first, another issue I wanted to resolve from my original BlockDrop implementation was to make the code a little more modular so here’s a little boilerplate I’ve been using to setup my modules.

var TemplateEngine = (function() {
  // private stuff here
  var private;

  return {
    // public stuff in here
    public: function() {
      /* ... */
    },
  };
})();

All we’re doing here is putting the module into an IIFE (immediately-invoked function expression) and assigning it to the global TemplateEngine variable.

Loading local files

The first thing the template engine needs to be able to do is load the HTML templates/partials. The way I chose to do this was using an XMLHttpRequest, to get this to work you’ll need your templates to be served by some kind of web server.

var TemplateEngine = (function() {
  var xhr = new XMLHttpRequest();

  return {
    load: function(fileName) {
      var contents = '';
      xhr.onreadystatechange = function() {
        if (xhr.readyState === 4 && xhr.status === 200) {
          contents = xhr.responseText;
        }
      };
      xhr.open('GET', fileName, false);
      xhr.send();

      return contents;
    },
  };
})();

This is all pretty straight-forward if you’ve done any work with AJAX in native JS, we’re basically just setting up an XHR object and returning the contents of the requested file as a string. One thing to note here is the third false parameter to the xhr.open() call, this means we’re not actually doing an asynchronous request. Since we’re just requesting local files this shouldn’t cause much delay, also for my particular application all of the templates will be loaded once during the first initialisation. For a more robust solution you might want to keep the request asynchronous and return a promise instead of the actual file contents.

Caching loaded templates

For my application the most common template I’ll be using are the actual pieces (shapes of 4 blocks). We wouldn’t want to make a new XHR every time we need a new piece, especially since my current implementation doesn’t make the requests asynchronously. A simple solution is to store loaded templates into a cache object the first time they’re loaded and then simply retrieve them from the cache for subsequent requests. We can even take advantage of localStorage to cache the templates in the user’s browser for future usage. Here’s my modifications to include caching.

var TemplateEngine = (function() {
  var xhr = new XMLHttpRequest(),
    cache = JSON.parse(localStorage.getItem('yourapp.cache.template')) || {};

  return {
    load: function(fileName) {
      var contents = cache[Utils.hashCode(fileName)];
      if (!contents) {
        contents = '';
        // XHR unchanged from previous step

        cache[Utils.hashCode(fileName)] = contents;
        localStorage.setItem('yourapp.cache.template', JSON.stringify(cache));
      }
      return contents;
    },
  };
})();

We try to initialise our cache object from localStorage but if it doesn’t exist yet we intialise it to an empty object. You can use whatever key you want when getting the cache object, just make sure you use the same key when setting the cache later. Utils.hashCode() is just a simple hashing function that I borrowed. I chose to use a hash because the template key in the cache object needs to be unique and needs to be based on the template filename so we can retrieve it when requesting the same filename later.

Simple tag replacements

The most basic thing we’ll need to do with a template engine is find and replace data from the template file with our actual application data. I opted for double-curlies (eg. {{ dataItem }}) in the templates to define areas that should be replaced with application data. In JavaScript the simplest way to represent this is an object where the key matches the double-curly bracket fields in the template and the value is the actual data you want inserted (eg. { dataItem: "dataValue" }).

var replaceTags = function(templateString, replaceMap) {
  return templateString.replace(/\{\{\s*([a-zA-Z0-9\.\$_]+)\s*\}\}/g, function(match, p1) {
    return replaceMap[p1] !== void 0 ? replaceMap[p1] : '';
  });
};

The heavy-lifting here is all done with a RegExp String replace. I won’t go into the details of regular expressions here but it’s worth noting that my allowed character set [a-zA-Z0-9\.\$_] might be too restrictive or too liberal for your application, I’ve been modifying this set as needed. We’re capturing the set and can access it as the 2nd parameter in the replace function.

Parsing the transformed string

Now that we’ve got a string representing some HTML which has all of the template tags replaced with actual application data we’ll want to parse it into a DOM object so that we can add it into an application’s DOM. There’s some existing functionality to handle that.

var TemplateEngine = (function() {
  // ...
  var parser = DOMParser();
  // ...
  var parse = function(templateString) {
    return parser.parseFromString(templateString, 'text/xml').childNodes[0];
  };
})();

The parseFromString() function provided by DOMParser() returns a root DOM node so we’ll need to get the first child node of the returned object so that we can attach that node into an application’s DOM.

Moving forward

What I’ve detailed here was my starting point but I’ve since found the need for my template engine to be able to handle loops which adds some more complexity which I won’t cover here. I also refactored a little so that load(), transform() (which calls replaceTags() as well as handling repeating sections in the templates) and parse() are all private functions of the TemplateEngine object. The only public functions are get() and getString() which both load and transform the templates, get() additionally parses the strings while getString() does not, this was required so that I could use templates within templates.

Ben Booth

Animating Loading Spinners with CSS

Fading

Spinning

Chasing

Bouncing

Wrapping Up

Managing Keybase private key with GPGTools

Import your Keybase key into GPGTools

Update the key with gpg

Push the updated key to Keybase

Export the updated public key to GitHub

Signing Git commits with your Keybase key

Building a basic UI-clone of Instagram using Elm - Part 3

Implement the single post view

Load and display comments

Implement the remove comment button

Implement the add comment form

The end!

Building a basic UI-clone of Instagram using Elm - Part 2

Implement the main list of posts view

Implement the “Like” button

Add a second page and navigation

That’s all (for now)

Building a basic UI-clone of Instagram using Elm - Part 1

Setting up a basic Elm app

Load posts from a JSON file

That’s all (for now)

Running Ghost with PM2 under a different user account on a Linux server

Create the new user

Setup Node.js using nvm

Install PM2

Stop the existing Ghost instance

Run the Ghost application under the new user account

Persist Ghost application across server restarts

Extra: Add Keymetrics monitoring

Writing a JavaScript Promises Library

Using Promises and the demo app

Basic success/failure handling

Handler chaining

Promises in the handler chain

Slightly more advanced

Beware the DOM Reflow

TL;DR

A little background

A false solution

The solution

Pregnancy Risk Factors

Simple JavaScript template engine

Setting up a module

Loading local files

Caching loaded templates

Simple tag replacements

Parsing the transformed string

Moving forward

Update the key with `gpg`