Reagent, part 1

One of the more popular wrapper libraries for using React with ClojureScript is Reagent. We’ll build a kanban style board to demonstrate the main features.

Transcript

We already learned the basics of React in Episode 6. If you’re new to React I would suggest you check that out. In this episode we’ll work with a ClojureScript wrapper library called Reagent to build a kanban-style board with cards and columns.

Start with a new Chestnut app, this time with the --reagent option. Chestnut combines a minimal setup with all tooling and setup to work comfortably.

$ lein new chestnut kanban --template-version 0.14.0 -- --reagent

One of the libraries used by this template is no longer compatible with the latest versions of Java. To fix that, add these dependencies in project.clj.

(defproject kanban "0.1.0-SNAPSHOT"
  :dependencies [,,,
                 [org.clojure/core.rrb-vector "0.0.14"]
                 [javax.xml.bind/jaxb-api "2.2.4"]
                 ,,,
                 ]
  ,,,)

Now start Figwheel, either from a terminal with lein figwheel, or if you’re using an nREPL based system like CIDER you can call Chestnut’s (run) from your REPL.

lein figwheel

M-x cider-jack-in
user> (run)

Here’s what the result will look like, you have a number of columns, and columns contain cards. You can click on a column title or on a card to edit it.

Cards and columns are straightforward divs with some styling. I won’t dwell on the CSS, just copy it from the show’s transcript and put it in style.css.

.card {
    background-color:  #fafafa;
    border-radius: 0.2em;
    padding: 0.5em;
    margin: 0.5em;
}

.card.editing {
    padding: 0;
}

.card.editing input {
    width: 100%;
    box-sizing: border-box;
    font-size: 1em;
}

.column, .new-column {
    width: 200px;
    float: left;
    padding: 0.1em 0.5em;
    border-radius: 0.2em;
    background-color:  #cccccc;
    margin: 0.5em;
}

.new-card, .new-column {
    padding: 0.5em;
    background-color:  #aaaaaa;
    border: 1px solid #cccccc;
    border-radius: 0.2em;
    margin: 0.5em;
}

Now open core.cljs, we will be spending most of our time in here. There’s already a bit of example code in here.

The greeting function is a Reagent component. Remember that in React we used createClass to create a component class, which required at a minimum a render method. Reagent boils that down to its minimum: components in Reagent are just functions, they return the virtual DOM in the form of Hiccup, a way of writing HTML tags using Clojure’s syntax.

So a React element is simply represented as a vector. The first element in the vector is the element’s type, which can be either a keyword, or a component. You can see that in the last line, where we pass reagent/render a single element, with as type the greeting component.

(ns kanban.core
  (:require [reagent.core :as reagent :refer [atom]]))

(enable-console-print!)

(defonce app-state (atom {:text "Hello Chestnut!"}))

(defn greeting []
  [:h1 (:text @app-state)])

(reagent/render [greeting] (js/document.getElementById "app"))

We’ll start with three components: a card, a column, and a “board” component which forms the root of our component tree.

I like to first code up the general structure of the UI, this is more a design than a coding task, and as long as you have a good idea of what you’re trying to build this can go fast.

Once the structure is there you can move on to the more error prone parts: hooking up state and behavior.

(defn Card []
  [:div.card])

(defn Column []
  [:div.column])

(defn Board []
  [:div.board])

A card and a column both have a title, just hard code them for now. A board consists of a number of columns. Now render the Board component, and let’s see how that looks.

(defn Card []
  [:div.card
   "a card"])

(defn Column []
  [:div.column
   [:h2 "a column"]])

(defn Board []
  [:div.board
   [Column]
   [Column]])

(reagent/render [Board] (js/document.getElementById "app"))

We also need a placeholder card and column so people can add new ones. Each of these also becomes a component.

(defn Card []
  [:div.card
   "a card"])

(defn NewCard []
  [:div.new-card
   "+ add new card"])

(defn Column []
  [:div.column
   [:h2 "a column"]
   [Card]
   [Card]
   [Card]
   [NewCard]])

(defn NewColumn []
  [:div.new-column
   "+ add new column"])

(defn Board []
  [:div.board
   [Column]
   [Column]
   [NewColumn]])

Let’s have another look at that namespace declaration, it refers to an atom function in the reagent.core namespace. It turns out Reagent has its own atom implementation. It’s very similar to the ClojureScript atom, but it allows Reagent to know when specific components need to be re-rendered, based on changes in the application state.

I like to see immediately when I’m using a React atom, so I’m going to change this namespace declaration a bit, and then update the calls to atom and render.

It’s a common mistake when using Reagent to accidentally use the ClojureScript atom instead, and you will be scratching your head wondering why your UI isn’t updating when it should.

(ns kanban.core
  (:require [reagent.core :as r]))

(defonce app-state (r/atom {:text "Hello Chestnut!"}))

,,,

(r/render [Board] (js/document.getElementById "app"))

Now let’s define some cards so we have something to render. Change the defonce to def for now, so the state is reset on every update. We’ll change it back later but right now this makes things easier.

Our app-state consists of colunms, which have a title, and a number of cards. I’ll just add a couple todo items to this column.

It’s just Clojure values all the way down, nothing exotic. The state follows the structure of the components, which makes things easy.

(def app-state
  (r/atom {:columns
           [{:title "Todos"
             :cards [{:title "Learn about Reagent"}
                     {:title "Tell my friends about Lambda Island"}]}]}))

Now we can start rendering based on actual values. First pass the application state atom to the Board component. Now the Board function will receive this state atom as its first argument.

(defn Board [state]
  ,,,)

(r/render [Board app-state] (js/document.getElementById "app"))

It’s worth pausing a moment to see what goes into making that happen. Remember that React components receive a JS properties object, which also contains any child elements passed to the component.

{:render (fn []
           ,,,
           (this-as t
             (.. t -props)))}

Reagent components on the other can receive any number of ClojureScript or JavaScript values, and they are passed as positional arguments.

If we look at the resulting component in the React browser extension, we see only a single property, argv, which is a vector containing the values passed to the component.

Reagent sets up a React component with a render function that “wraps” our own component function, and takes care of calling our function with the values in argv.

Back to our kanban board! The Board component can now dereference the state atom to get its current value, and then render columns based on that.

I find for-loops work really well for rendering collections like this. We just pass the column data as-is to each Column component.

(defn Column [col]
  ,,,)

(defn Board [state]
  [:div.board
   (for [c (:columns @state)]
     [Column c])
   [NewColumn]])

The column component now receives a map representing the column, it contains the title and a vector of cards, so we can destructure that. We now use the same pattern to render the collection of cards.

(defn Card [card]
  ,,,)

(defn Column [{:keys [title cards]}]
  [:div.column
   [:h2 title]
   (for [c cards]
     [Card c])
   [NewCard]])

Finally all the card component needs to do right now is render its title.

(defn Card [card]
  [:div.card
   (:title card)])

So that’s cool, our UI rendering is basically done. You can play around with this by adding some columns and cards to the app-state.

(def app-state ,,,)

There’s still something missing from our rendering code though, we also want to edit cards and column titles. When a user clicks on a card or column title it should temporarily change into a text field.

We’ll keep track of which card or column is being edited with an extra :editing flag in our app-state.

(def app-state
  (r/atom {:columns
           [{:title "Todos"
             :cards [{:title "Learn about Reagent"}
                     {:title "Tell my friends about Lambda Island"
                      :editing true}]}]}))

So now when a card is in the editing state it needs to be rendered differently. I’ll give it an extra class-name so it can be styled, and then wrap the title in an input text field.

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

And do the same for the title of a column.

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

There’s something funny with these text fields, we can’t edit them! Your browser isn’t broken, this is simply because of the way that React works. The DOM in a React app is a pure function of application state. The same application state will always result in the same DOM being rendered. If we could just change the value of these text fields independently, then we would be altering the DOM, breaking this equivalence.

We’ll see how to implement these text fields, as well as how to add new cards and columns, in the following episode.

Show Notes

browse source code

Caution

The Chestnut application template has changed since this episode was written. To follow along you are best to stick to version 0.14.0, which you can do like this.

$ lein new chestnut kanban --template-version 0.14.0 -- --reagent

This unfortunately pulls in a version of rrb-vector which is not compatible with newer versions of Java. To fix that, add this to the :dependencies in project.clj:

[org.clojure/core.rrb-vector "0.0.14"]
[javax.xml.bind/jaxb-api "2.2.4"]

result:

(defproject kanban "0.1.0-SNAPSHOT"
  :dependencies [,,,
                 [org.clojure/core.rrb-vector "0.0.14"]
                 [javax.xml.bind/jaxb-api "2.2.4"]
                 ,,,
                 ]
  ,,,)

Resources

Reagent

Code

styles.css

.card {
    background-color:  #fafafa;
    border-radius: 0.2em;
    padding: 0.5em;
    margin: 0.5em;
}

.card.editing {
    padding: 0;
}

.card.editing input {
    width: 100%;
    box-sizing: border-box;
    font-size: 1em;
}

.column, .new-column {
    width: 200px;
    float: left;
    padding: 0.1em 0.5em;
    border-radius: 0.2em;
    background-color:  #cccccc;
    margin: 0.5em;
}

.new-card, .new-column {
    padding: 0.5em;
    background-color:  #aaaaaa;
    border: 1px solid #cccccc;
    border-radius: 0.2em;
    margin: 0.5em;
}

core.cljs

(ns kanban.core
  (:require [reagent.core :as r]))

(enable-console-print!)

(def app-state
  (r/atom {:columns [{:title "Todos"
                      :cards [{:title "Learn about Reagent"}
                              {:title "Tell my friends about Lambda Island"}]}
                     {:title "Awesomize"
                      :editing true
                      :cards [{:title "Meditate"}
                              {:title "Work out"
                               :editing true}]}]}))

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

(defn NewCard []
  [:div.new-card
   "+ add new card"])

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

(defn NewColumn []
  [:div.new-column
   "+ add new column"])

(defn Board [state]
  [:div.board
   (for [c (:columns @state)]
     [Column c])
   [NewColumn]])

(r/render [Board app-state] (js/document.getElementById "app"))