re-frame Subscriptions Got Even Better

Up until recently, to use re-frame subscriptions in Reagent views, you had to use a form-2 component.

A form-2 component is a function that returns another function, which does the actual rendering of the component to hiccup. In contrast, a form-1 component renders the hiccup directly.

;; form-1
(defn todo-item [todo]
  [:div.view
   [todo-checkbox (:id todo) (:completed todo)]
   [:label {:unselectable "on"} title]
   [:button.destroy {:on-click #(dispatch [:todos/remove (:id todo)])}]])

;; form-2
(defn todo-item [todo]
  (fn [todo]
    [:div.view
     [todo-checkbox (:id todo) (:completed todo)]
     [:label {:unselectable "on"} title]
     [:button.destroy {:on-click #(dispatch [:todos/remove (:id todo)])}]]))

It’s a small difference, but it has interesting uses. With a form-2 component the outer function is only called once. When re-rendering a component, only the inner function is called. This gives you a place to put one-time initialization code. In that sense it’s a bit like React’s componentWillMounthook.

Since the inner function is a closure, you can have it close over variables by using a let block. A common pattern is to close over a Reagent atom to hold component-local state.

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

(defn todo-input []
  (let [title (r/atom "")]
    (fn []
      [:input#new-todo {:type "text"
                        :value @title                           ;; <------------ deref!
                        :placeholder "What needs to be done?"
                        :auto-focus true
                        :on-change #(reset! title (-> % .-target .-value))}])))

By deref’ing the atom inside the render function Reagent will know that the component depends on this ratom, and re-render it when the atom updates.

The same is true for Reagent reactions, such as returned by re-frame’s subscribe function. You only want the reaction to be created once, but it should be dereferenced for its current value whenever the component re-renders.

The re-frame docs about “subscription flow”contain a great introduction to ratoms and reactions. They are also covered in depth in Lambda Island episode 20, re-frame Subscriptions

(require '[re-frame.core :refer [subscribe])

(defn toggle-all-checkbox []
  (let [all-complete? (subscribe [:todos/all-complete?])]
    (fn []
      [:span
       [:input {:type "checkbox"
                :checked @all-complete?}]             ;; <---------------- deref!
       [:label {:for "toggle-all"} "Mark all as complete"]])))

Re-frame 0.8 introduced a subscription cache, meaning that multiple calls to subscribe with the same arguments will return the same identical reaction.

In version 0.9 this became official, and so now you can subscribe and dereference a subscription in one go.

(defn toggle-all-checkbox []
  [:span
   [:input {:type "checkbox"
            :checked @(subscribe [:todos/all-complete?])}]
   [:label {:for "toggle-all"} "Mark all as complete"]])

It’s a neat change, and one that makes re-frame yet again a little bit more user friendly.

You could go one step further by creating a little helper function that subscribes and derefs in one go:

(def deref-subscribe [query-v]
  (deref (subscribe query-v]))

Or if you like it point-free:

(def deref-subscribe (comp deref subscribe))

There was some discussion to add this helper to re-frame itself, but the jury is still out on what to call it. Proposed names include listen, watch, and input-signal.

Personally I started using <sub in my projects, and I’m liking it a lot. It provides a little visual queue as to where the inputs of a component are. I’ve even consider using >evt as an alias for dispatch.

I would perhaps even go one step further and embrace the unicode futureby using ⇐ and ⇒, but it seems ClojureScript doesn’t like Unicode identifiers (´•̥̥̥︵•̥̥̥` )

;; sadly doesn't work
;; (def ⇐ (comp deref re-frame.core/subscribe))
;; (def ⇒ re-frame.core/dispatch)

(def <sub (comp deref re-frame.core/subscribe))
(def >evt re-frame.core/dispatch)

(defn toggle-all-checkbox []
  [:span
   [:input {:type "checkbox"
            :checked (<sub [:todos/all-complete?])
            :on-change #(>evt [:todos/toggle-all])}]
   [:label {:for "toggle-all"} "Mark all as complete"]])

If you’re wondering how you would type those arrows, then it’s about time you set up a Compose Key!