Reagent, part 2: Cursors

We continue building a Kanban board with Reagent, adding functionality to edit cards. In the process you’ll learn all about Reagent’s cursors and event handlers.

Transcript

In Episode 9. about Reagent we ended with a mock version of our Kanban board. If you want to follow along from where we left off you can grab the code from Github. Just follow the instructions in the show notes.

All parts of the board are already there, but they don’t do anything yet, it could just as well have been static HTML. To change that we’ll be using Reagent’s cursors. Let’s get started!

Before diving into our app we’ll have to learn how cursors work. Suppose you have a single card stored in a Reagent atom, the card has the :title “Hello Island.”.

(def card-atom (r/atom {:title "Hello Island."}))

Updating it is straightforward, here’s a function that changes the card’s title. We change the atom with swap!, which takes an atom and a function to apply to the value in the atom. Any extra arguments to swap! are passed through as extra arguments to the function, so we can actually simplify this.

Now we can use this function to change the value in the atom, here’s the result.

(defn set-title! [card title]
  (swap! card assoc :title title))

;; same as
(defn set-title! [card title]
  (swap! card (fn [c] (assoc c :title title))))

(set-title! card-atom "Hello Turtles")

card-atom ;;=> #<Atom: {:title "Hello Turtles"}>

Things get a bit more complex when that card data is deep inside a nested structure. Suppose we have this representation of a kanban board: two columns, the second one containing a card with the title “Hello World”.

(def board (r/atom {:columns [{:cards []}
                              {:cards [{:title "Hello Island."}]}]}))

Now to change the title of the card we need to know the “path” to the card. Let me demonstrate what that means using get-in. get-in is like get, but instead of just a key it takes a sequence of keys. This sequence is called a “path”. Each key or numeric index is used to descend another level in the data structure. It works with both maps and vectors because they are both considered associative data structures.

Other functions that work with a path instead of just a key, are assoc-in and update-in.

(get-in @board [])                           ;;=> {:columns [{:cards []} {:cards [{:title "Hello Turtles."}]}]}
(get-in @board [:columns])                   ;;=> [{:cards []} {:cards [{:title "Hello Turtles."}]}]
(get-in @board [:columns 1])                 ;;=> {:cards [{:title "Hello Turtles."}]}
(get-in @board [:columns 1 :cards])          ;;=> [{:title "Hello Turtles."}]
(get-in @board [:columns 1 :cards 0])        ;;=> {:title "Hello Turtles."}
(get-in @board [:columns 1 :cards 0 :title]) ;;=> "Hello Turtles."

So now to update the card’s title we use assoc-in instead of assoc, passing it the path from the root to the title.

(swap! board assoc-in [:columns 1 :cards 0 :title] "Hello Turtles.")

We can update set-title! to work with this board structure, but we need to tell it how to find the column and card in the board, by giving it the right indices.

This isn’t great though, our function which previously just had to know about cards now also has to deal with boards and columns. It has become tightly coupled to the structure of the board.

(defn set-title! [board col-idx card-idx title]
  (swap! board assoc-in [:columns col-idx :cards card-idx :title] title))

(set-title! board 1 0 "Hello Octopi.")'
;;=> {:columns [{:cards []} {:cards [{:title "Hello Octopi."}]}]}

We face the same problem in our Column and card components. To render themselves they only need to know about a single column or card, but to perform updates they need to know where those columns and cards are in the overall application state.

We can do slightly better by passing in a path together with the board atom, that way each component knows where to find the data it needs, without having to worry where in the application state that data lives exactly.

By having both the path and the atom available a component can retrieve its data as well as update it.

Let’s see how that looks for a Column. It’s not a big change, before we got the column data directly, and now we to look it up with get-in.

(defn Column [board col-path]
  (let [{:keys [title cards editing]} (get-in @board col-path)]
    [:div.column
     (if editing
       [:input {:type "text" :value title}]
       [:h2 title])
     (for [c cards]
       [Card c])
     [NewCard]]))

We also need to update our Board code, since that’s rendering these columns. Before we could simply loop over the column values, but now we need to build up the path for each column using numeric indices. I’m doing that by counting the columns first, and then using range to get a sequence from 0 up to the number of columns. Now for each index I can build up the correct path, and pass that together with the board to the Column component.

(defn Board [board]
  [:div.board
   (for [idx (range (count (:columns @board)))]
     (let [col-path [:columns idx]]
       [Column board col-path]))
   [NewColumn]])

Maybe you were thinking it would be nice to somehow bundle an atom and a path together, since we’re always passing them around together. Congratulations, you just invented cursors!

You create a cursor by passing the atom and the path to Reagent’s cursor function.

(r/cursor board [:columns 0])
;;=> #<Cursor: [:columns 0] {:title "Todos", :cards [{:title "Learn about Reagent"} {:title "Tell my friends about Lambda Island"}]}>

A cursor behaves like an atom, you can call, deref, swap!, or reset on it. All operations are scoped to the cursor’s path, but any updates are performed on the original atom. This way you can ignore the rest of the application state, and only focus on the bits you care about.

So here I’m adding a card to the first column through a cursor, and you can see that this change is reflected in the app-state.

(def cards-cursor
  (r/cursor board [:columns 0 :cards]))

@cards-cursor

(swap! cards-cursor conj {:title "New card in column 0"})

@cards-cursor ;;=> [{:title "New card in column 0"}]
@board ;;=> {:columns [{:cards [{:title "New card in column 0"}]} {:cards [{:title "Hello Island!"}]}]}

Let’s see how these cursors can help to hook up our components. First we do the columns. Since we already changed this code to use an atom plus a path, this is a small transformation.

(defn Column [col-cur]
  (let [{:keys [title cards editing]} @col-cur]
    [:div.column
     (if editing
       [:input {:type "text" :value title}]
       [:h2 title])
     (for [c cards]
       [Card c])
     [NewCard]]))

(defn Board [board]
  [:div.board
   (for [i (range (count (:columns @board)))]
     [Column (r/cursor board [:columns i])])
   [NewColumn]])

For cards we use the same pattern, loop over the indices, and build up a cursor for each card. Notice though that I’m creating a cursor based on another cursor, instead of on the original atom. This is another way in which a cursor simply behaves as an atom, but the path of the new cursor is now relative to the path of the old one.

(defn Card [card-cur]
  (let [card @card-cur]
    (if (:editing card)
      [:div.card.editing [:input {:type "text" :value (:title card)}]]
      [:div.card (:title card)])))

(defn Column [col-cur]
  (let [{:keys [title cards editing]} @col-cur]
    [:div.column
     (if editing
       [:input {:type "text" :value title}]
       [:h2 title])
     (for [i (range (count cards))]
       [Card (r/cursor col-cur [:cards i])])
     [NewCard]]))

While we’re add it I’d like to clean this Card component up a bit, I find this outer let is a nice place to destructure the data we need.

(defn Card [card-cur]
  (let [{:keys [editing title]} @card-cur]
    (if editing
      [:div.card.editing [:input {:type "text" :value title}]]
      [:div.card title])))

Now we’re finally ready to start adding functionality. The first thing we do is make a card editable by clicking on it. Now you’ll see how those cursors come in handy!

Just like in plain React event handlers are passed in as properties of the element. The only difference when using Reagent is that you now use kebap-case instead of camelcase for the event name, so “on-click” is written with a dash, instead of with an uppercase “C”.

Click on a card to see it’s working, and indeed we get the text field.

(defn card [card-cur]
  ,,,
  [:div.card {:on-click #(swap! card-cur assoc :editing true)} title]
  ,,,)

Now we can turn a card into a text field now, but we still can’t edit it. As I said in episode 9 this has to do with how React works, we use a certain string as the input element’s value property, and the only way to change that value is to pass a different value.

There’s two ways to solve this. The first is to use :defaultValue instead of :value. Now React will take care of managing the input field so you can edit it, but any changes you make won’t be reflected in the app-state, and you would have to read the final value of the text field directly out of the DOM.

(defn Card [card-cur]
  ,,,
  [:div.card.editing [:input {:type "text" :defaultValue title}]]
  ,,,)

The better solution in this case is to use an on-change event handler. This anonymous function will receive a change event. The event’s target is the object that triggered the event, in this case the <input> DOM element. We get the new value from the DOM element, update the application state, and now through React’s render loop that new value is reflected again in the UI.

(defn Card [card-cur]
  ,,,
  [:div.card.editing [:input {:type "text"
                              :value title
                              :on-change #(swap! card-cur assoc :title (.. % -target -value))}]]  ,,,)

Now when you click on a card it becomes editable, but how do we make the edit field go away again? We’ll implement two event handlers for that, first an on-blur handler, so that when another element gets focus the text-field automatically goes away, and then an on-key-press handler so that you can stop editing simply by pressing enter.

The :on-blur handler is straightforward, we just remove the editing flag again with dissoc.

[:div.card.editing [:input {:type "text"
                            :value title
                            :on-change #(swap! card-cur assoc :title (.. % -target -value))
                            :on-blur #(swap! card-cur dissoc :editing)}]]

Before implementing the key-press handler that will detect the Enter key, let’s do some refactoring. We are defining all these event handlers inline, maybe it’s better to pull those out into functions.

on-change updates the title

on-blur stops the editing

and on-click starts the editing

Now we can see straight away what these events do.

(defn- update-title [card-cur title]
  (swap! card-cur assoc :title title))

(defn- stop-editing [card-cur]
  (swap! card-cur dissoc :editing))

(defn- start-editing [card-cur]
  (swap! card-cur assoc :editing true))

(defn- Card [card-cur]
  (let [{:keys [editing title]} @card-cur]
    (if editing
      [:div.card.editing [:input {:type "text"
                                  :value title
                                  :on-change #(update-title card-cur (.. % -target -value))
                                  :on-blur #(stop-editing card-cur)}]]
      [:div.card {:on-click #(start-editing card-cur)} title])))

Finally the key-press handler checks for the “enter” key, which has character code 13, and also stops the editing.

(defn Card [card-cur]
  ,,,
  [:div.card.editing [:input {:type "text"
                              :value title
                              :on-change #(update-title card-cur (.. % -target -value))
                              :on-blur #(stop-editing card-cur)
                              :on-key-press #(if (= (.-charCode %) 13)
                                               (stop-editing card-cur))}]]
  ,,,)

There’s just one more thing that’s a bit annoying, when you click on a card it turns into a text field, but then you need to click on the text field again so it gets focus.

The easy way to solve this is with the autoFocus attribute added in HTML5. Autofocus works in Firefox and Chrome since their very early versions, but it was only added to internet explorer in version 9, and Safari on iOS doesn’t support autofocus at all. We’ll look at a more general solution in the next episode.

That’s it for this episode, you now know everything to build functioning Reagent applications. In the next episode about Reagent we’ll add the finishing touches, talk about performance, and deal with React’s lifecycle methods.

In the meanwhile I would love to hear from you! I’m on Twitter and Clojurians Slack as plexus, or you can simply send an email to arne@lambdaisland.com. Til next time!

(defn Card [card-cur]
  ,,,
  [:div.card.editing [:input {:type "text"
                              :value title
                              :autoFocus true
                              :on-change #(update-title card-cur (.. % -target -value))
                              :on-blur #(stop-editing card-cur)
                              :on-key-press #(if (= (.-charCode %) 13)
                                               (stop-editing card-cur))}]]
  ,,,)

Show Notes

browse source code

The starting point of this episode is the branch ep-9-reagent, the end point is ep-10-reagent-cursors. You can follow along by starting with

git clone https://github.com/lambdaisland/kanban.git -b ep-9-reagent

Cursors

Creating cursors:

(require '[reagent.core :as r])

(r/cursor <atom> <path)

;; example
(def board (r/atom {:columns []}))

(def cols-cursor (r/cursor board [:columns]))

(swap! cols-cursor conj {:title "todos" :cards []})

@board ;;=> {:columns [{:title "todos" :cards []}]}

Reagent cookbook has a cursors recipe

Event handlers

:on-click
Called whenever an element is clicked (mdn)
:on-change
Useful on text fields, you can get the new value of the field with (fn [e] (.. e -target -value)) (mdn)
:on-blur
Called when an element loses focus (mdn)
:on-key-press
Useful to React to single key press events. Find which key was pressed with (fn [e] (.-charCode e)) (mdn)

Autofocus

The HTML attribute is called autofocus, but the DOM property is called autoFocus with a capital F.

Chart with browser support