Lambda Island

Reagent is a popular and easy to use option for using React with ClojureScript. re-frame builds on top of Reagent, providing an elegant and opinionated way to structure applications and deal with application state. The documentation for re-frame can easily overwhelm. With this episode you get a practical hands-on introduction, so you can be making your own apps in no time.

Transcript

Reagent is one of the more popular ClojureScript libraries for building React apps. It gives you an easy way to define components, and some basic tools for working with application state.

Using Reagent atoms and cursors directly is fine for simple apps, but as your application gets more complex this can easily get messy. This is where re-frame comes in, it’s designed to be functional, reactive, and fast, and it provides structure to keep your code maintainable.

re-frame is both an architecture, a library implementing that architecture, and an application template to easily get you started. As an example I’m going to implement a level editor for the retro game “breakout”.

To get started I’ll generate an application skeleton using the re-frame leiningen template. I’m passing some options to the generator here, one for CIDER support, so I can launch Figwheel from Emacs, and one for Garden, because I like to write my CSS in Clojure.

lein new re-frame breakout +cider +garden

The directory layout is fairly typical. Notice though that there are already a handful of cljs files, each with a specific purpose.

~/breakout $ tree
.
├── project.clj
├── README.md
├── resources
│   └── public
│       └── index.html
└── src
    ├── clj
    │   └── breakout
    │       ├── core.clj
    │       └── css.clj
    └── cljs
        └── breakout
            ├── config.cljs
            ├── core.cljs
            ├── db.cljs
            ├── events.cljs
            ├── subs.cljs
            └── views.cljs

7 directories, 11 files

Looking at project.clj you can see the dependencies for Reagent and re-frame. The project comes with two ClojureScript builds configured, a development build without optimizations, and a minified production build.

(defproject breakout "0.1.0-SNAPSHOT"
  :dependencies [,,,
                 [reagent "0.6.0"]
                 [re-frame "0.8.0"]]
  ,,,)

Of the six generated ClojureScript files, the one that should look most familiar is views.cljs. This is where you define Reagent components. One component called main-panel is already there.

(ns breakout.views
    (:require [re-frame.core :as re-frame]))

(defn main-panel []
  (let [name (re-frame/subscribe [:name])]
    (fn []
      [:div "Hello from " @name])))

You might be most familiar with Reagent components that immediately return Hiccup, so called “form-1” components.

(defn main-panel []
  [:div "Hello from re-frame"])

In re-frame you’ll mostly use form-2 components. These return an anonymous function which does the actual rendering. When Reagent needs to re-render this component only the inner anonymous function is called again. The outer function is only called once, and so it’s a good place for initialization code.

(defn main-panel []
  ;; initialization code here, only runs once
  (fn []
    ;; called every time component re-renders
    [:div "Hello from re-frame"]))

Be aware that if the component function takes any properties as arguments, then the inner render function should do the same.

(defn main-panel [prop1 prop2]
  ;; initialization code here, only runs once
  (fn [prop1 prop2]
    ;; called every time component re-renders
    [:div "Hello from re-frame"]))

Notice there’s no call to reagent/render here. Let’s have a quick look how the application boots up.

In index.html the compiled JavaScript code is loaded, and then an inline script is used to call the init function in the core namespace.

<script src="js/compiled/app.js"></script>
<script>breakout.core.init();</script>

Here’s the init function in core.cljs, exported so it can be called from JavaScript. It calls mount-root, which takes care of rendering the main-panel component we just saw under views.

You can also see a glimpse of re-frame’s state management here. init triggers an event to initialize the re-frame database, a Reagent atom managed by re-frame. We’ll have a lot more to say about that later on.

(defn mount-root []
  (reagent/render [views/main-panel]
                  (.getElementById js/document "app")))

(defn ^:export init []
  (re-frame/dispatch-sync [:initialize-db])
  (dev-setup)
  (mount-root))

Instead of building up the app from scratch, I’m going to start with some Reagent components already implemented, this way I can focus on the parts that are specific to re-frame. At the moment these components are 100% static, their inputs are hard-coded, and they don’t have any event handlers.

As always the code is on Github if you want to follow along or play around with. You can find instructions in the show notes.

main-panel is the top level component. It renders a heading, and then an SVG containing three things: there’s a gray rectangle which forms the background, there are the blocks in the game, and then there’s a color picker with a number of color swatches. I’m using this translate helper component to move it to the side.

(defn main-panel []
  [:div.game
   [:h1 "BREAKOUT LEVEL EDITOR"]
   [:svg {:style {:width (+ g/width 70) :height g/height}}
    [background-box {:x 0 :y 0 :width g/width :height g/height}]
    [blocks]
    [translate {:x 1009 :y 0}
     [color-picker]]]])

This is the component which renders the collection of blocks. At the moment the list of blocks is hard coded. Each block is represented by a vector containing the column number, the row number, and the color number.

:g stands for “group”, it’s the SVG equivalent of a “div”, just a generic way to group some elements together.

Note that, since we have siblings components of the same type, we give them a unique key, otherwise React will complain and we’ll get degraded performance.

(defn blocks []
  (let [blocks [[3 5 0] [2 8 1] [1 1 4]]]
    [:g
     (for [[x y color] blocks]
       [block {:x x
               :y y
               :color color
               :key (str x "--" y)}])]))

Finally there’s the color picker. It renders another gray background box, then the six color swatches, and finally the white border which indicates which color is selected.

(defn color-picker []
  [:g
   [background-box 0 0 60 310]
   (for [idx (range 6)]
     [color-swatch {:index idx
                    :key (str "color-" idx)}])
   [selection-marker {:index 0
                      :key "marker"}]])

There are two pieces of state that are currently hard coded that we want to be able to change, the blocks, and the selected color.

In a vanilla Reagent app you might store these in a single Reagent atom, and use that atom directly. With re-frame the same will happen under the hood, but the atom is managed by re-frame, you never deal with it directly.

(def app-state (reagent.core/atom
                {:selected-color 3
                 :blocks [[3 5 0] [2 8 1] [1 1 4]]}))

re-frame encourages you to think of this single atom with application state as your application database. The initial value of this database is defined in db.cljs. Later on we will query this database through subscriptions, defined in subs.cljs, and update it through event handlers, defined in events.cljs.q

To give the database it’s initial value, change the default-db var in the db namespace. We need to store the currently selected color index, and the list of blocks. Before we were using a vector of vectors, but now we’ll use a map, using the [column row] coordinates as key, and the color as assoiciated value. This will make it easier later on to update or remove blocks based on their coordinates.

(def default-db
  {:color 0
   :blocks {[3 5] 0
            [2 8] 1
            [1 1] 4}})

Next we need to write some queries to get this data out of the database and into our components. We do this by registering “subscription handlers”. So switch to the subs namespace.

Registration a subscription handler is done with reg-sub, and since that’s the main thing we’ll be doing here, I prefer to refer to it directly.

reg-sub takes the name of the handler, and then the handler function itself. This needs to be a pure function which takes the current value of the database, and returns the result of the query.

For the color we just need to pull the color number out of the database. For the blocks we do a bit more work. It’s easier for the view to deal with the vector format we were using earlier, so map over the blocks in the database, destructuring each MapEntry, and then in turn destructure each key into a column and row.

(reg-sub :color
         (fn [db _]
           (:selected-color db)))

(reg-sub :blocks
         (fn [db _]
           (map (fn [[[x y] color]]
                  [x y color])
                (:blocks db))))

Now we’re ready to update the views, using the subscribe function. Start by referring it from the re-frame.core namespace.

Pass subscribe a vector with the name of the subscription. The result of calling subscribe is a special kind of Reagent atom called a “reaction”. Since it’s a kind of atom we need to dereference it to get to the actual value.

Now there’s one more important change we need to make. Right now subscribe gets called every time this component gets re-rendered. Instead it should only be called once when the component is first created, and not for subsequent renderings.

This is where those form-2 components I talked about earlier come in handy. Just introduce an extra anonymous render function, so the subscription lives outside of the render function, but the dereferencing is done inside.

(defn blocks []
  (let [blocks (subscribe [:blocks])]
    (fn []
      [:g
       (for [[col row color] @blocks]
         [block {:column col
                 :row row
                 :color color
                 :key (str col "--" row)}])])))

Next up we do the same for the selected color. Use an outer let block to subscribe to the current value of :color, put in an anonymous function so the subscription only happens once, and then derefence color-idx inside the inner function to get the latest value.

(defn color-picker []
  (let [color-idx (subscribe [:color])]
    [:g
     [background-box {:x 0 :y 0 :width 60 :height 310}]
     (for [idx (range 6)]
       [color-swatch {:index idx
                      :key (str "color-" idx)}])
     [selection-marker {:index color-idx}]]))

With such a contrived example it may be hard to see why these subscriptions are useful. Why not fetch data from the main database atom directly?

One good reason is performance. If we dereferenced the database atom directly in our components, then whenever the database gets updated, all the components would be re-rendered. This is how Reagent works: it tracks which components dereference a certain atom, and re-renders them when the atom changes.

By using these focused subscriptions, components will only be re-rendered when their inputs change, so changing the selected color won’t cause the blocks to render, and vice versa.

There’s a lot more to subscriptions than what I’m showing you here, but exploring them in-depth is beyond the scope of this episode.

So now we’ve moved our app state into the database, but the app still isn’t doing anything. To make it do something we need to dispatch events.

This is done with dispatch. Start by adding it to the namespace declaration. Dispatch is typically called from an React event-handler like :on-click. It has a similar signature to subscribe, you pass it a vector containing the event type, and any arguments. Make sure to wrap the subscribe call in an anonymous function. I forget that all the time.

When the event is dispatched it will go into re-frame’s event queue and will be handled asynchronously.

[color-swatch {:index idx
               :key (str "color-" idx)
               :on-click #(dispatch [:select-color idx])}]

To respond to this event we need an event “handler”. These are defined in events.cljs. If you used an older version of the re-frame template then this file may also be called handlers.cljs.

There’s already one event handler there, which sets the database to its initial value. You may remember seeing this event get triggered in the core namespace.

(reg-event-db :initialize-db
              (fn  [_ _]
                db/default-db))

Events will typically cause some kind of side effect, but the most common side effect by far is updating the database, so there’s a dedicated function to create these, called reg-event-db. I’ll refer to it directly again for convenience.

reg-event-db takes the name of the handler, and the handler function itself. This has to be a pure function which returns the updated database.

The second argument to the handler is the event vector, containing the event type followed by any arguments, so you can destructure that to get the color index we passed in earlier.

Note how this is just a pure function, there’s no swap!, we’re not manipulating state, all of that is handled behind the scenes by re-frame.

(reg-event-db :select-color
              (fn [db [_ idx]]
                (assoc db :color idx)))

Finally we need event handlers to create, change, or delete blocks.

When a person clicks on the background, we want to add a block where they clicked, so we’ll dispatch a “create-block” event. I’m using a little helper function which takes the incoming click event, and returns the x and y coordinates where the click happened.

[background-box {:x 0
                 :y 0
                 :width g/width
                 :height g/height
                 :on-click #(dispatch [:create-block (helpers/click-pos %)])}]

The handler for this event uses update to add a new coordinate pair with associated color into the blocks map. In the process we convert from pixel coordinates to row and column numbers.

(reg-event-db :create-block
              (fn [db [_ [x y]]]
                (update db :blocks
                        assoc [(g/px->col x)
                               (g/px->row y)]
                        (:selected-color db))))

Take a moment to try that out, this is actually fun. There’s only one thing left to do. When clicking an existing block we need to either update its color, or remove the block, depending on what’s selected in the color picker.

So in the block component, dispatch a :block-clicked event with the block coordinates.

(defn block [{:keys [column row color]}]
  [:rect {,,,
          :on-click #(dispatch [:block-clicked column row])}])

This time the effect handler needs to decide wether to update or remove a block. It could do that in one go, but to make it more interesting we’ll have it dispatch either a :remove-block or an :update-block event, and handle those separately.

When you want an event handler to trigger another event, your first instinct may be to just use the dispatch function the way we did in the views, but event handlers have to be pure, and dispatching an event is a side effect, so we can’t do that.

The solution is to use an age old functional programming trick: instead of actually performing the side effect, represent what needs to happen in data, and deal with it elsewhere. To do that we use reg-event-fx instead of reg-event-db.

The first argument of the handler function is now no longer the database, but instead its a map which can contain any number of available inputs. These are known as “co-effects”. One of these is the current value of the database.

The result of the handler function is an “effects map”. If we wanted to update the database we would return an effects map with a :db key, and associate it with the new database value. In this case we want to dispatch an event, for that there’s the :dispatch effect, which takes an event vector.

re-frame comes with :db and :dispatch effects built-in, other are provided by extensions, for instance to deal with localStorage, or to perform AJAX requests.

(reg-event-fx :block-clicked
              (fn [cofx [_ x y]]
                (if (= (-> cofx :db :selected-color) 5)
                  {:dispatch [:remove-block [x y]]}
                  {:dispatch [:update-block [x y]]})))

All that’s left is implement the :remove-block and :update-block events. And because of the way we structured our database that’s just a matter of doing an assoc or a dissoc respectively.

(reg-event-db :update-block
              (fn [db [_ coords]]
                (update db :blocks assoc coords (:selected-color db))))

(reg-event-db :remove-block
              (fn [db [_ coords]]
                (update db :blocks dissoc coords)))

Show Notes

browse source code

In this episode you’ll build a level editor for the retro game Breakout. You can try it out on-line.

If you want to follow along, then check out the re-frame-start branch, and start from there. The final result is in the re-frame-episode-1 branch.

git clone https://github.com/lambdaisland/breakout.git
cd breakout
git checkout re-frame-start

Prerequisites

This episode assumes you are somewhet familiar with Reagent, and hence, React. These episode will get you up to speed

If you weren’t familiar with the distinction of form-1, form-2, and form-3 components, then the re-frame wiki page “Creating Reagent Components” will be helpful.

UPDATE: it is no longer necessary to use form-2 components when using re-frame subscriptions, see this blog post on the topic

Notes

The re-frame template supports these optional flags

cider (+cider)
garden (+garden)
cljs.test and doo (+test)
compojure (+handler)
less (+less)
RE-COM (+RE-COM)
SECRETARY (+ROUTES)

re-frame, part 1