re-frame, part 3: Events and Effects

Side effects in re-frame are handled through events. You’ll implement several event handlers of a TodoMVC app so it becomes functional. You’ll also implement custom effect and co-effect handlers for storing the application state in localStorage. To debug event handlers you’ll learn about the “debug” interceptor, and about re-frisk, a handy tool for inspecting your re-frame database.

Transcript

In this episode you’ll learn all about re-frame event handlers, as well as effects and co-effects. You’ll continue building the “redolist” app from previous episodes, a TodoMVC implementation based on re-frame. All code is on Github, you can find a link in the show notes. The starting point for this episode is the ep25-start branch.

So grab the repo, switch to the right branch, and poke around in it a bit before continuing this episode. All the views are already there, since they were covered in previous episodes, and they receive data from the database through subscriptions.

The file with event handlers is still mostly empty, you’ll be adding more of them soon.

Before continuing, I recommend adding re-frisk, a helpful tool for inspecting the state of your re-frame app. First add it to project.clj. It’s currently at version 0.3.2.

;; project.clj
:dependencies [,,,
               [re-frisk "0.3.2"]]

In core.cljs, after requiring it, call enable-re-frisk! in the dev-setup function. That’s all the setup you need.

(ns redolist.core
  (:require ,,,
            [re-frisk.core :refer [enable-re-frisk!]]))

(defn dev-setup []
  (when config/debug?
    (enable-re-frisk!)
    ,,,))

What you get in return is this little button at the bottom right corner of your browser window. Click on it and you can inspect re-frame’s state. The main thing to care about for now is :app-db.

You can “pop-out” re-frisk for a more comfortable view, plus some extra functionality. This column on the left shows all past events, and if you select one you can see the full event vector.

Up here is all of re-frame’s state, including registered events and subscriptions, effects and co-effects.

Let’s quickly recap re-frame’s data flow model. On the one hand there’s the application state, held in the re-frame database, an ratom managed behind the scenes by re-frame.

On the other hand there are the views, which turn app state into HTML and show it to the user.

Data flows from the database to the views through subscriptions, you can learn all about them in episode 20.

Subscriptions are reactive: they respond to changes in application state, and propagate those changes to the views.

Views receive browser events, which they use to dispatch re-frame events, which result in a number of side effects (or simply “effects”).

The effects may cause the application state to change, and this change propagates back to the view, thus completing a full cycle.

Let’s have a look at the app. If you open events.cljs you’ll see two events registered there. The first one, :initialize-db, is fired when the application boots to give the database a default value.

(ns redolist.events
  (:require [re-frame.core :refer [reg-event-db]]
            [redolist.db :as db]))

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

This default is set in db.cljs, and I went ahead and added two todo items there so you have something to look at, one completed and one still in progress.

(ns redolist.db)

(def default-db
  {:todos {1 {:id 1
              :title "Put a lying demagogue in power"
              :completed true
              :editing false}
           2 {:id 2
              :title "Fight for freedom #resist"
              :completed false
              :editing false}}
   :display-type :all})

Boot up Figwheel and open the app. This is what we have so far, all the components are there, it all renders, but none of it works, since it doesn’t yet trigger any events.

The only thing that does work is this filtering by active or completed todos. These are actually just plain links, simple a elements. Instead of firing React events, they make the browser navigate to a new URL. This is picked up by Secretary, a routing library for ClojureScript.

I won’t cover Secretary in depth now, but if you look at routes.cljs you can see that it fires a :set-display-type. This is done with re-frame’s dispatch function. You pass it a “event vector”, containing the name of the event, and any extra arguments. You’ll be using dispatch a lot in your views.

:set-display-type expects one argument, a keyword indicating which todos should be visible.

(defn app-routes []
  (secretary/set-config! :prefix "#")
  ;; --------------------
  ;; define routes here
  (defroute "/" []
    (re-frame/dispatch [:set-display-type :all]))

  (defroute "/active" []
    (re-frame/dispatch [:set-display-type :active]))

  (defroute "/completed" []
    (re-frame/dispatch [:set-display-type :completed]))
  ;; --------------------
  (hook-browser-navigation!))

Handling this event is done by an event handler, which is the second event you see registered in events.cljs.

Let’s pick that apart. This event handler only needs to change the database, it does not cause other side effects. This makes it comparatively simple and straightforward. You pass reg-event-db the event name, and then a pure function which takes the old database value and the event vector, and returns the updated database. re-frame will take care of swapping the database ratom behind the scenes.

It’s common to destructure the event vector like this, ignoring the first element, the event name, since in this case it will always be the same.

(reg-event-db :set-display-type
              (fn [db [_ type]]
                (assoc db :display-type type)))

Let’s add a few more to get a feel for them. For starters it would be nice to be able to mark a todo as done. For that add an on-change handler to the checkbox.

The on-change takes a function, so don’t forget the hash symbol. Otherwise it’s just a function call and the event will be dispatched immediately when the component renders. It’s a surprisingly common mistake.

Just like with subscriptions, it’s a good idea to namespace these event. You’ll be grateful you did when your app starts getting bigger.

This is the first usage of dispatch in the views, so make sure it’s added to the namespace declaration.

(ns redolist.views
  (:require [re-frame.core :as re-frame :refer [subscribe dispatch]]
            ,,,))


(defn todo-checkbox [id completed]
  [:input.toggle {:type "checkbox"
                  :checked completed
                  :on-change #(dispatch [:todos/toggle id])}])

Now register a handler for this event. The event vector contains the todo item’s id, which is easy to get to with destructuring.

The database value is a map containing :todos, which is in turn a map with the id’s of the todo items as keys. Each todo item is again a map, which can be :completed or not. With update-in you can reach into this nested structure, and flip the :completed flag by negating it.

(reg-event-db :todos/toggle
              (fn [db [_ id]]
                (update-in db [:todos id :completed] not)))

Sweet! Check that out and you should be able to mark todos as completed. Now maybe it doesn’t work the first time. In that case a good starting point for debugging is figuring out if the event actually gets fired.

So far you’ve only seen reg-event-db taking two arguments: the event name and handler, but in between those two you can insert a third argument: a vector of “interceptors”. Explaining interceptors in detail will take some time, but just try adding [debug] after the event name.

(reg-event-db :todos/toggle [debug]
              (fn [db [_ id]]
                (update-in db [:todos id :completed] not)))

debug is again defined in re-frame.core.

(ns redolist.events
  (:require [re-frame.core :refer [,,, debug]]
            ,,,))

Now when you look at the browser console, you’ll see a notification that this event was handled, including a diff of how the database changed.

This is what it looks like in Firefox. That’s not how it’s supposed to look like though. The browser is displaying ClojureScript datastructures as plain JavaScript objects, which is not helpful at all.

Handling re-frame event: Object { meta: null, cnt: 2 ...}
 db clojure.data/diff for: [:todos/toggle 2]
 only before: Object { meta: null, cnt: 1, arr: [2], ...}
 only after : Object { meta: null, cnt: 1, arr: [2], ...}

This is what you get in Chrome. It’s not that Chrome itself has support for ClojureScript datastructures, but rather that it has support for custom object formatters. The re-frame template contains cljs-devtools which makes use of this feature to add this custom rendering.

Currently Chrome or Chromium is the only browser supporting this. There’s an open ticket for Firefox, but not much has moved yet.

Handling re-frame event: [:todos/toggle 2]
 db clojure.data/diff for: [:todos/toggle 2]
 only before: {:todos {2 {…}}}
 only after : {:todos {2 {…}}}

If you are using Chrome but ClojureScript collections still aren’t rendering properly, then make sure custom formatters are enabled in the devtools settings dialog.

Let’s add one more event to drive the pattern home. The :todos/add event takes the title for a new todo item, and inserts it into the database.

You can use random uuids to identify each todo item. The item itself is just a map with an id, a title, and a :completed flag. The collection of todos in the database is again a map, with ids as keys. This makes it easy to look up a todo later on.

(reg-event-db :todos/add
              (fn [db [_ title]]
                (let [id (random-uuid)
                      todo {:id id
                            :title title
                            :completed false}]
                  (update db :todos assoc id todo))))

The todo-input component uses an ratom to keep some component local state, namely the text in the input field. That’s why there’s already an on-change handler, it keeps the ratom in sync with whatever is entered in the text field.

When a user presses “enter” a todo item should get added, so for that you need an :on-key-down handler. You don’t want to respond to every key, so you need an extra check before dispatching the event.

The keydown event will have a which property which is the number of the key, with 13 meaning “enter”. If it is enter, then dispatch the event, which adds the todo item, and also reset the title atom so the text field is empty again.

Having that magic number there makes the code a bit cryptic, so let’s pull that out into an enter? predicate.

(defn enter? [evt]
  (= (.-which evt) 13))

(defn todo-input []
  (let [title (r/atom "")]
    (fn []
      [:input#new-todo {,,,
                        :on-key-down #(when (enter? %)
                                        (dispatch [:todos/add @title])
                                        (reset! title ""))}])))

So far these event handlers only deal with the database, they take the current database value as input, and return the updated database. Event handlers can also have other inputs, and they can cause other side-effects.

re-frame refers to the inputs of an event handler as its co-effects, and the side-effects it causes are simply known as “effects”.

To use other effects or co-effects besides reading and updating the database, you use a different registration function, reg-event-fx.

reg-event-fx is strictly more powerful than reg-event-db, and in fact you can easily transform the -db form into a more general -fx form.

The first difference is that, instead of receiving the database as its first argument, the event handler now receives a map of inputs, or “co-effects”. One of these (and currently the only one), is the database.

The return value of the event handler should also be a map, these are the “effects”, each entry in the map describes some side-effect that needs to happen. In this case :db means that the database needs to be updated to this new value.

(reg-event-fx :set-display-type
              (fn [cofx [_ type]]
                {:db (assoc (:db cofx) :display-type type)}))

:db is the only co-effect that is included with re-frame, although others can be added, either by you, or by a third party library.

There are also a couple different effects available: :db for updating the database, :dispatch for triggering another event, :dispatch-n for triggerring several, and :dispatch-later for scheduling an event in the future.

(reg-event-fx :foo
              (fn [cofx [_ type]]
                {:db ,,,
                 :dispatch [:some/event]
                 :dispatch-n [[:all] [:of] [:these]]
                 :dispatch-later [{:ms 200 :dispatch [:this-in-200-ms]}]
                 }))

You can easily register new effects and co-effects, and several are provided by third party libraries. To show you how that works let’s add support for localStorage. This HTML5 API provides a simple key-value store that persists across page loads, so that a users todo list isn’t lost when they close the browser.

Start by adding a new redolist.local-storage namespace, and include these helper functions that wrap the browser’s localStorage API. Check the transcript if you don’t want to type this all out. The only really notable thing about this code is that it encodes stored values using Transit, a fast and compact serialization format based on JSON. LocalStorage only supports storing strings. By using Transit it’s possible to store arbitrary ClojureScript values, such as the current state of the database.

(ns redolist.local-storage
  (:require [re-frame.core :refer [reg-cofx reg-fx]]
            [cognitect.transit :as t]))

(defonce t-writer (t/writer :json))
(defonce t-reader (t/reader :json))

(defn set-item!
  "Set `key' in browser's localStorage to `val`."
  [key val]
  (.setItem (.-localStorage js/window) key (t/write t-writer val)))

(defn get-item
  "Returns value of `key' from browser's localStorage."
  [key]
  (t/read t-reader (.getItem (.-localStorage js/window) key)))

(defn remove-item!
  "Remove the browser's localStorage value for the given `key`"
  [key]
  (.removeItem (.-localStorage js/window) key))

If you have a Figwheel REPL open then go ahead and try these out. First require the local-storage namespace from core.cljs, or Figwheel won’t load it.

(ns redolist.core
  (:require ,,,
            [redolist.local-storage]))

In the REPL, use in-ns to switch to the right namespace. Now you can store a value with set-item!, such as a set of numbers. With get-item you can retrieve it again.

redolist.local-storage> (in-ns 'redolist.local-storage)
nil
redolist.local-storage> (set-item! "test" #{1 2 3})
nil
redolist.local-storage> (get-item "test")
#{1 3 2}
redolist.local-storage> (apply max (get-item "test"))
3

Now comes the interesting bit, adding the effects and co-effects handlers.

reg-fx takes the name of the new effect you want to register, and a handler function that performs the actual side-effects. When an event handler has :storage as a key in its effect map, then this this effect handler will run. The value associated with :storage is passed to the effect handler function as an argument, so it knows which side effects to perform.

I’ll keep it simple and only allow storing a single value under the “redolist” key.

(reg-fx :storage (fn [value]
                   (set-item! "redolist" value)))

Now you can add a “save” event that stores the current state of the database. All it does it take the current value of the database from the co-effect map, and pass it on in the effect map to be put in localStorage. This will trigger the effect handler you just implemented.

(reg-event-fx :storage/save
              (fn [cofx _]
                {:storage (:db cofx)}))

To save the database after every change, dispatch a :storage/save event from the other event handlers. So change :todos/toggle and :todos/add to use reg-event-fx. You can destructure the co-effects map to get to the database. Then return a map with the new :db, and an event vector to dispatch, so that it triggers the :save.

(reg-event-fx :todos/toggle
              (fn [{:keys [db]} [_ id]]
                {:db (update-in db [:todos id :completed] not)
                 :dispatch [:storage/save]}))

(reg-event-fx :todos/add
              (fn [{:keys [db]} [_ title]]
                {:db (let [id (random-uuid)
                           todo {:id id
                                 :title title
                                 :completed false}]
                       (update db :todos assoc id todo))
                 :dispatch [:storage/save]}))

The next step is to now restore the database from localStorage when the page loads. There’s already an :initialize-db event, so you can change that to either load from storage if it finds anything there, or else use the default db.

First register the new co-effect. reg-cofx is very similar to reg-fx, you give it a name, and then a handler function. This time the handler receives a map of co-effects which it can add things to, and possibly extra arguments.

Now grab the saved state from localStorage, and assoc it onto the cofx, so event handlers can access it.

(reg-cofx :storage (fn [cofx _]
                     (->> (get-item "redolist")
                          (assoc cofx :storage ))))

Now you can update :initialize-db to first check for a stored state. If nothing is stored yet then this will be nil, and it’ll use the default database instead.

(reg-event-fx :initialize-db
              (fn [{:keys [storage]} _]
                {:db (or storage db/default-db)}))

There’s one more thing to add. Even though you’ve registered the co-effect, it’s not actually used yet. This makes sense, you might have many data sources, and you don’t want to query them all for every event, instead you need to tell re-frame which co-effects a given event needs, so it can make sure to get those for you.

You do this with inject-cofx, which returns another “interceptor”, just like the debug interceptor I showed you at the beginning. I’m not going to explain the ins and outs of interceptors in this episode, but you should be able to use the ones I’ve shown by following the examples. Add a vector form between the event name and the handler, and in there add the interceptor. Note that you could pass extra arguments to inject-cofx, these would be passed on to the co-effect handler.

(reg-event-fx :initialize-db [(inject-cofx :storage)]
              (fn [cofx _]
                {:db
                 (or (:storage cofx)
                     db/default-db)}))

Apart from interceptors, you now know all the core concepts of re-frame. I’m looking forward to hearing about what you build with it!

Show Notes

browse source code

The starting point for this episode is the ep25-start branch. To code along at home do

git clone -b ep25-start https://github.com/lambdaisland/redolist.git

For the usage of <sub, see the blog post about the revamped re-frame subscriptions.

Cheat sheet

;; Events that purely update the database
(reg-event-db :set-user-name
  (fn [db [_ user-name]]                          ;; [old-db-value event-vector] -> new-db-value
    (assoc db :user-name user-name)))

;; Same event handler, but rewritten to use co-effects -> effects
(reg-event-fx :set-user-name
  (fn [cofx [_ user-name]]                        ;; [cofx-map event-vector] -> fx-map
    {:db
     (assoc (:db cofx) :user-name user-name)}))

Built-in co-effects

`:db`

The current value of the database.

Built-in effects

`:db`

Supply a new value for the app db. Typically used with the :db coeffect to update the database.

{:db (assoc db :foo "bar")}

`:dispatch`

Dispatch another event

{:dispatch [:event-id "param"] }

`:dispatch-later`

Dispatch one or more events in the future.

{:dispatch-later [{:ms 200 :dispatch [:event-id "param"]}        ;;  in 200ms do this: (dispatch [:event-id "param"])
                  {:ms 100 :dispatch [:also :this :in :100ms]}]}

`:dispatch-n`

Dispatch multiple events. Expects a seqable? of event vectors.

{:dispatch-n [ [:do :all] [:three :of] [:these] ])}

`:deregister-event-handler`

Get rid of a previously registered event handler. Either pass it a single id, or a vector of ids.

{:deregister-event-handler :my-id)}
{:deregister-event-handler [:one-id :another-id]}

Registering cofx/fx

(require '[re.frame.core :refer [reg-fx reg-event-fx reg-cofx inject-cofx]])

;; Registering a new effect
(reg-fx :fx-name (fn [fx-input] ,,, ;; perform side-effects
                   ))

;; using it from an event handler
(reg-event-fx :some/event
              (fn [cofx event-v]
                {:fx-name fx-input}))

;; Registering a new co-effect
(reg-cofx :cofx-name (fn [cofx args]
                     (assoc cofx :new-cofx "cofx-value")))

;; using it from an event handler
(reg-event-fx :some/event [(inject-cofx :cofx-name arg1 arg2)]
              (fn [{:keys [new-cofx]} event-v]
                ))