May 20, 2021

Building a library VIII - Extending rendering with functional zippers

Data is really cool to work with, and with the right tools at hand, you can make magic happen. One such tool, which is absolutely fantastic in the right circumstances, are functional zippers.

In short, a functional zipper is a way to navigate through one or several data structures, all the while making changes to them, and then finally realizing the changes at the end. It allows you to take a data structure, make changes to them as you see fit, and then return a completely new data structure based on the old one.

We’ll take a deep dive into a rendering implementation, which will allows us to expand the rendering functionality for the form as a whole, while leaving the rendering of the fields intact as it’s a boundary we wish to keep.

Expanding our rendering

So, we have our general rendering for table, list and paragraphs from part VI, but would like something a bit more flexible.

The really nice way was if we could feed the form how we wanted it to be rendered, telling it where to place the fields, the errors for the fields, etc. If it can be done declaratively, without us having to go into tedious implementations for supporting injections, all the better.

Since we already use hiccup thanks to reagent, we can use that as a basis. Consider the code below.

[:div :$key
 [:span :$errors]]

It’s easy enough to follow. We have a div with the $key, $field and $errors declared. $errors is inside span, because that is what the insanity of the design from the designers demands and there is nothing you can do about it.

This would work for dictacting the rendering of all the related elements for each individual field. Add in some control over the container of all the fields, and you have something that’s fairly workable.

Expanding to the entire form layout

It falls a bit short if you need even more control of the form layout. Each field will look the same, and sometimes you come across situations where you need different visual implementations for different fields. We can expand the idea to the following.

 [:tr :$account.key
     {:colspan 2}
     [:div :$account.errors]]]
  [:td :$percent.label]
   [:div :$]
   [:div :$percent.errors]]]]

Given two fields, account and percent we put them inside a table, but give them a slightly different layout. We follow the same pattern as established above, but can now go down to the individual level for each field.


By using reagent’s use of hiccup vectors, we have expanded the syntax to include our own fields. Two cases have emerged, one a template, the other a wholesome affair where all of the visual layout is spelled out in the hiccup format.

We put a $ marker in front of our expanded vocabularity for two reasons. One, it makes it easier to implement and two, it makes it easier to visually identify.

Zipper details

Whenever you see a zip namespace in the code below, it’s been imported from

First, we need to setup a zipper, that allows us to navigate a hiccup vector. There are some default implementations of zippers in, but this is the one I have used for quite some time to navigate clojure’s normal data structures as a sort of general purpose zipper.

(defmulti branch? type)
(defmethod branch? :default [_] false)
(defmethod branch? cljs.core/PersistentVector [v] true)
(defmethod branch? cljs.core/PersistentArrayMap [m] true)
(defmethod branch? cljs.core/List [l] true)
(defmethod branch? cljs.core/IndexedSeq [s] true)
(defmethod branch? cljs.core/LazySeq [s] true)
(defmethod branch? cljs.core/Cons [s] true)

(defmulti seq-children type)
(defmethod seq-children cljs.core/PersistentVector [v] v)
(defmethod seq-children cljs.core/PersistentArrayMap [m] (mapv identity m))
(defmethod seq-children cljs.core/List [l] l)
(defmethod seq-children cljs.core/IndexedSeq [s] s)
(defmethod seq-children cljs.core/LazySeq [s] s)
(defmethod seq-children cljs.core/Cons [s] s)

(defmulti make-node (fn [node children] (type node)))
(defmethod make-node cljs.core/PersistentVector [v children] (vec children))
(defmethod make-node cljs.core/PersistentArrayMap [m children] (into {} children))
(defmethod make-node cljs.core/List [_ children] children)
(defmethod make-node cljs.core/IndexedSeq [node children] (apply list children))
(defmethod make-node cljs.core/LazySeq [node children] (apply list children))
(defmethod make-node cljs.core/Cons [node children] (apply list children))

(prefer-method make-node cljs.core/List cljs.core/IndexedSeq)
(prefer-method make-node cljs.core/List cljs.core/LazySeq)
(prefer-method branch? cljs.core/List cljs.core/IndexedSeq)
(prefer-method branch? cljs.core/List cljs.core/LazySeq)
(prefer-method seq-children cljs.core/List cljs.core/IndexedSeq)
(prefer-method seq-children cljs.core/List cljs.core/LazySeq)

(defn zipper [node]
  (zip/zipper branch? seq-children make-node node))

Next we require the code that navigates the zipper.

(defn unwrapper [loc markers]
  (let [rest-of-location (zip/rights loc)]
    (-> loc
        (zip/replace rest-of-location))))

(defn marker [node]
  (if (and (keyword? node)
           (str/starts-with? (str node) ":$"))

(defn wire [markers loc]
  (let [node (zip/node loc)
        mk (marker node)]
    (if (contains? markers mk)
      (let [value (get markers mk)]
        (if (fn? value)
          (value loc markers)
          (zip/replace loc value)))

(defn wiring [frame markers]
    (loop [loc (zipper frame)]
      (let [next-loc (zip/next loc)]
        (if (zip/end? next-loc)
          (zip/root loc)
          (recur (wire markers next-loc)))))
    (catch js/Exception e
      (.log js/console e))))

What the code does is really simple. We have a frame and some markers. The frame is our expanded hiccup syntax, while the markers is what we introduced before with our $marker (such as :$field). For each $marker, a corresponding key (e.g. :field) exists in markers and is used to replace our $marker in the frame.

In short, the wiring function goes through the entire data structure in frame by using zip/next. If it’s the end of the zipper, we realize our changes to the zipper (i.e., we return the new data structure) with zip/root. If not we move on to the next location in the frame. For each step forward we use the wire function.

The wire function takes our markers and the pointer to the current location in our frame. We realize the current location into a node with zip/node and then check if it’s a marker by using the marker function. If the $marker is in markers we replace the entire $marker with the value in markers. Unless it’s a function, in which case we run the function with the current location (i.e, we are giving the function the zipped frame with all the changes to it, to do with as the function wishes) and the markers.

There is also a function called unwrapper, which takes the the frame and removes that entire level of hiccup syntax. In short…​ if we had [:div "Hello World!"] and ran unwrapper on that, we would be left with "Hello world!".

Rendering setup

We now need to expand our common rendering functions to include our new advanced capabilities. We grab the :wiring key from our field for the advanced rendering and then run it through the wiring function with the wiring as our frame and the markers generated once in our Form-2 reagent component.

(defn render-wiring [{:keys [wiring] :as field} form]
  (let [rendered (wiring/wiring [:$wrapper
                                {:$wrapper wiring/unwrapper
                                 :$key     {:key (str "ez-wire-form-" (:id field))}
                                 :$label   (render-label field form)
                                 :$field   (render-field field form)
                                 :$errors  (render-error-element field form)})]
    (fn [_ _]
      (into [:<>] rendered))))

(defn assoc-wiring [{:keys [name] :as field} params]
  (let [params-wiring (:wiring params)]
    (assoc field :wiring
           (cond (contains? params-wiring name)
                 (get params-wiring name)

                 (:wiring field)))))

(defn get-body [row-fn params form]
  (let [fields (map (comp #(assoc-wiring % params)
                          #(get-in form [:fields %])) (:field-ks form))]
    (fn [row-fn params form]
       (for [field fields]
         (if (:wiring field)
           ^{:key (:id field)}
           [render-wiring field form]
           ^{:key (:id field)}
           [row-fn field form]))])))

We can now add our form rendering functions. In ez-wire they got named as-template and as-wire.


(defn row [{:keys [wiring]} _]

(defn- adapt-wiring [{:keys [template] :as params} form]
  (assoc params :wiring
         (reduce (fn [out [_ {:keys [name]}]]
                   (assoc out name template))
                 {} (:fields form))))

(defn as-template [{:keys [template/element]
                    :or {element :div}
                    :as params}
                   {:keys [id form-key] :as form} content]
  (let [{:keys [template]} params]
     {:display-name "as-template"

      (fn [this]
        (when (util/select-option :form/automatic-cleanup? form params)
          (rf/dispatch [:ez-wire.form/cleanup id])))

      (fn [params form content]
        (let [{:keys [style
               :or {style {}
                    class ""}} params]
          [element {:key (util/slug "form-template" @form-key)
                    :style style
                    :class class}
           [common/get-body row (adapt-wiring params form) form]
           (if content

This piece of code will allow us to create a form like this, with each field being rendered according to the :template wiring in the definition of the form.

(defform my-form-name
  {:template [:<>
  [{:name :percent
    :element Input ;; from some popular React component library
    :adapter integer-adapter
    :validation [:percent-above-0 :percent-below-100]}])

(defn view []
  (let [form (my-form-name {} {})]
    [as-template {} form]))


(defn- ->kw [name k]
  (keyword (str "$" (subs (str name) 1) "." (clojure.core/name k))))

(defn wrapped-render [f field form]
  [f field form])

(defn- assemble-body [{:keys [wiring]} {:keys [fields] :as form} content]
  (let [default-map (if content
                      {:$content [content]}
    (wiring/wiring wiring (reduce (fn [out [_ {:keys [name] :as field}]]
                                    (merge out
                                           {(->kw name :wrapper) wiring/unwrapper
                                            (->kw name :key)     {:key (str "ui-wire-form-wire" (:id field))}
                                            (->kw name :label)   (common/render-label field form)
                                            (->kw name :field)   [wrapped-render common/render-field field form]
                                            (->kw name :errors)  (common/render-error-element field form)}))
                                  default-map fields))))

(defn as-wire [{:keys [wiring/element]
                :or {element :div}
                :as params}
               {:keys [id form-key] :as form} & [content]]
  (let [body (assemble-body params form content)]
     {:display-name "as-wire"

      (fn [this]
        (when (util/select-option :form/automatic-cleanup? form params)
          (rf/dispatch [:ez-wire.form/cleanup id])))

      (fn [params form & [content]]
        (let [{:keys [style
               :or {style {}
                    class ""}} params]
          [element (merge {:key (util/slug "form-wire" @form-key)}
                          (if (not= element :<>)
                            {:style style
                             :class class}))

as-wire requires a bit more work, as we here have to handle each field individually in the frame to be sent to the wiring function. Once that is done, the code we have setup can still be used as is.

With what we currently have, we can now render our form as such. Notice that we now add the options with the as-wire function, instead of defining it as part of the form as we did above with as-template.

(defn view []
  (let [form (my-form-name {} {})]
    [as-wire {{:wiring/element :span
               :class "foobar"


Functional zippers are one of those things that is a bit of a mind bender. In short, we take a hiccup vector [:div :$field], navigate through it, find which part of the vector is a :$field and replace it with what we have for that field.

So…​ we start at the top of the vector. We navigate next at our current position, which is the entire vector [:div :$field]. That moves us into the vector, and our position is now at :div. We check to see if is our field, and it’s not, so we navigate next. Since :div is not a collection, next will move us right inside the collection. We now end up at :$field. This is our field, and so we replace it with what we have in markers, which also happens to be pure data. Our check to see if we are at the end of the vector hits true and we realize the changes (i.e., we get back our changed hiccup vector). The changed hiccup vector will now look something like [:div [my-field-fn]].

Next up…​

We will finish this series with taking a look at branching logic and wizards.

Tags: programming