What’s in a component? That which implemented in any other way would fell as reusable

The complete source code displayed in this article can be found in Vrac’s repository.

In the last post “Making HTML reactive using Signaali“, we hooked up our code to HTML elements already existing in an HTML page. That’s not how modern web development work, nowadays we create them within our program and refer to them from there.

So, let’s represent HTML in our program. But wait .. which format should we choose? Hiccup is using Clojure vectors for both HTML and data, sometimes causing ambiguity for people reading the source code and security issues at runtime. UIx is using a syntax which is not ambiguous, so let’s reuse it!

We go from:

    <main>
      <h1>Developing Vrac from scratch - components</h1>
      <p>This demonstrates how Vrac is implemented.</p>

      <h2>Reactive counter</h2>
      <div>
        Counter value: <span id="counter-element">n/a</span>
        <div>
          <button id="inc-counter-button">Increment</button>
          <button id="reset-counter-button">Reset</button>
        </div>
      </div>

      <h2>Lazy effects</h2>
      <div>
        The effects are lazy, the user decides when to re-run them.
        Click the button to update the DOM.
        <div>
          <button id="run-effects-button">Run effects</button>
        </div>
      </div>
    </main>

and convert it to:

(defn my-html []
  ($ :main
     ($ :h1 "Developing Vrac from scratch - components")
     ($ :p "This demonstrates how Vrac is implemented.")
     ($ :h2 "Reactive counter")
     ($ :div "Counter value:" ($ :span#counter-element "n/a")
        ($ :div
           ($ :button#inc-counter-button "Increment")
           ($ :button#reset-counter-button "Reset")))
     ($ :h2 "Lazy effects")
     ($ :div "The effects are lazy, the user decides when to re-run them. Click the button to update the DOM."
        ($ :div
           ($ :button#run-effects-button "Run effects")))))

There are a few changes to do:

• We want to stop referring to HTML elements by id and instead refer to them contextually or via Clojure symbols.

• The :span element looks a bit useless now that we don’t use the id, let’s remove it and directly refer to a text node instead.

• We want to have a Signaali state for the counter.

• We want to avoid verbosity for the effect which updates a counter text node, so we want it to be implicit.

• We want to add event listeners on the buttons.

With a bit of magic, it could look like:

(defn my-html []
  ($ :main
     ($ :h1 "Developing Vrac from scratch - components")
     ($ :p "This demonstrates how Vrac is implemented.")
     ($ :h2 "Reactive counter")
     (let [counter-state (sr/create-state 0)]
       ($ :div "Counter value:" counter-state
          ($ :div
             ($ :button {:on-click #(swap! counter-state inc)} "Increment")
             ($ :button {:on-click #(reset! counter-state 0)} "Reset"))))
     ($ :h2 "Lazy effects")
     ($ :div "The effects are lazy, the user decides when to re-run them. Click the button to update the DOM."
        ($ :div
           ($ :button {:on-click #(sr/re-run-stale-effectful-nodes)} "Run effects")))))

The function my-html starts to look like a real React component now. But what is a component alone? We should have more! How do we compose them? Our components are functions, so we compose them by calling those functions — naturally.

You can count on me like 1-2-3, I’ll be there …

Let’s say that we want more counters in our small experiment — 3 of them.

(defn my-counter [counter-state]
  ($ :div "Counter value:" counter-state
     ($ :div
        ($ :button {:on-click #(swap! counter-state inc)} "Increment")
        ($ :button {:on-click #(reset! counter-state 0)} "Reset"))))

(defn my-html [nb-counters] ;; nb-counters is 3
  ($ :main
     ($ :h1 "Giving shape to components")
     ($ :p "This demonstrates how Vrac is implemented.")
     ($ :h2 "Reactive counters")
     (for [i (range nb-counters)]
       (let [counter-state (sr/create-state (* i 100))]
         (my-counter counter-state)))
     ($ :h2 "Lazy effects")
     ($ :div "The effects are lazy, the user decides when to re-run them. Click the button to update the DOM."
        ($ :div
           ($ :button {:on-click #(sr/re-run-stale-effectful-nodes)} "Run effects")))))

The $ function

The obvious first question is: what kind value should it return?

Well, we chose this function mainly to remove any ambiguity. But we want it to work similarly to Hiccup to represent an HTML structure which can be transformed later.

Because the ($ :div ,,,) expressions look different from the user’s perspective and because it will contain a few new types of values, let’s give this structure a new name: “Vrac-Hiccup”, shortened as “Vcup”.

“Vcup” is made of either:

• a VcupNode which is a node of children Vcup elements, or

• a Vcup leaf value — text, reactive node, etc …

.. and because we use types and not Clojure data structures, there is always enough space for more types of node or leaf values.

(defrecord VcupNode [tag children])

(defn $ [tag & children]
  (VcupNode. tag children))

Rendering the root component within the HTML page

With the page’s HTML being handled by the app, index.html now looks like a standard SPA’s index.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <title>Making HTML reactive using own HTML library</title>
  </head>
  <body>
    <script src="/js/main.js" defer></script>
    <div id="app"></div>
  </body>
</html>

The entry point and reloading code of the app becomes:

(defn ^:dev/after-load setup! []
  (render (js/document.getElementById "app")
          (my-html 3)))

(defn ^:dev/before-load shutdown! []
  (dispose-render-effects))

(defn start-app []
  (setup!))

Starting from here in this article, all the functions belong to the Vrac library and not the example. Let’s dive in.

The render function:

1. processes the vcup returned by the root component, uses process-vcup to turn it into a DOM elements + some reactive effects,

2. sets the DOM elements as children of the element defined in index.html,

3. then runs the effects for the first time, enabling them to find their dependencies and react to them in the future.

(defn render [^js/Element parent-element vcup]
  (let [{:keys [effects elements]} (process-vcup vcup)]
    ;; Set all the elements as children of parent-element
    (.apply (.-replaceChildren parent-element) parent-element (to-array elements))
    ;; Run all the effects
    (run! sr/run-if-needed effects)))

(defn dispose-render-effects []
  ;; TODO: dispose all the effects used for the rendering and the DOM updates.
  ;; In this article, we will skip this step.
  ,)

Implementing the process-vcup function

We want to walk the vcup structure to transform it into a DOM structure, and while doing that we also want to keep track of the reactive effects which are used for updating the text nodes.

(defn- set-element-attribute [^js/Element element attribute-name attribute-value]
  (cond
    ;; Event listener
    (str/starts-with? attribute-name "on-")
    (.addEventListener element
                       (-> attribute-name (subs (count "on-")))
                       attribute-value)

    :else
    :to-be-defined-in-next-articles))

(defn process-vcup [vcup]
  (let [all-effects (atom [])
        to-dom-elements (fn to-dom-elements [vcup]
                          (cond
                            (string? vcup)
                            [(js/document.createTextNode vcup)]

                            (instance? VcupNode vcup)
                            (let [^js/Element element (js/document.createElement (name (:element-tag vcup)))
                                  [attributes children] (let [children (:children vcup)
                                                              x (first children)]
                                                          (if (and (map? x)
                                                                   (not (record? x))) ; because map? returns true on records
                                                            [x (next children)]
                                                            [nil children]))
                                  ;; Convert the children into elements.
                                  child-elements (into []
                                                       (comp (remove nil?)
                                                             ;; Inline elements when child is a seq.
                                                             (mapcat (fn [child]
                                                                      (if (seq? child)
                                                                          child
                                                                          [child])))
                                                             (mapcat to-dom-elements))
                                                       children)]

                              ;; Set the attributes on the created element.
                              (doseq [[attribute-name attribute-value] attributes]
                               (set-element-attribute element (name attribute-name) attribute-value))
                              ;; Set the element's children
                              (doseq [child-element child-elements]
                                (-> element (.appendChild child-element)))
                              [element])

                            (instance? sr/ReactiveNode vcup)
                            (let [element (js/document.createTextNode "")
                                  effect (sr/create-effect (fn []
                                                             (set! (.-textContent element) @vcup)))]
                              (swap! all-effects conj effect)
                              [element])

                            :else
                            :to-be-defined-in-next-articles))
        elements (to-dom-elements vcup)]
    {:effects @all-effects
     :elements elements}))

And that’s it! We now have the basics of a reactive web framework + a working example with only 111 lines of code in total, all thanks to Signaali’s support.

In the next article I will make the range of the for loop dynamic — a change with a lot of technical implications. Stay tuned!

The complete source code displayed in this article can be found in Vrac’s repository.

Let’s make an HTML page

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <title>Making HTML reactive using Signaali</title>
  </head>
  <body>
    <script src="/js/main.js" defer></script>

    <main>
      <h1>Reactive HTML without a framework</h1>
      <p>This demonstrates how to use Signaali to manipulate the DOM reactively.</p>

      <h2>Reactive counter</h2>
      <div>
        Counter value: <span id="counter-element">n/a</span>
        <div>
          <button id="inc-counter-button">Increment</button>
          <button id="reset-counter-button">Reset</button>
        </div>
      </div>

      <h2>Lazy effects</h2>
      <div>
        The effects are lazy, the user decides when to re-run them.
        Click the button to update the DOM.
        <div>
          <button id="run-effects-button">Run effects</button>
        </div>
      </div>
    </main>
  </body>
</html>

This page has 3 buttons on which we will listen the “click” event. It also has a span element containing a text which we will update from a Signaali effect. Here is the skeleton of the source code. It has no reactivity yet, the callback functions are registered and unregistered, but they do nothing yet.

(ns example.core) ;; TODO: require signaali's namespace

;; Get the references to the DOM elements we want to modify
(def ^js counter-element      (js/document.getElementById "counter-element"))
(def ^js inc-counter-button   (js/document.getElementById "inc-counter-button"))
(def ^js reset-counter-button (js/document.getElementById "reset-counter-button"))
(def ^js run-effects-button   (js/document.getElementById "run-effects-button"))

;; TODO: a state for the counter

;; TODO: an effect that updates the text in the DOM element `counter-element`

(defn on-inc-counter-button-clicked []
  ;; TODO: increase the counter state
  ,)

(defn on-reset-counter-button-clicked []
  ;; TODO: set the counter state to zero
  ,)

(defn on-run-effects-button-clicked []
  ;; TODO: run the effect which will update the DOM
  ,)

(defn setup! []
  (.addEventListener inc-counter-button   "click" on-inc-counter-button-clicked)
  (.addEventListener reset-counter-button "click" on-reset-counter-button-clicked)
  (.addEventListener run-effects-button   "click" on-run-effects-button-clicked)

  ;; TODO: set the counter's state to zero
  ;; TODO: run the effect once, to update the DOM
  ,)

(defn shutdown! []
  (.removeEventListener inc-counter-button   "click" on-inc-counter-button-clicked)
  (.removeEventListener reset-counter-button "click" on-reset-counter-button-clicked)
  (.removeEventListener run-effects-button   "click" on-run-effects-button-clicked)

  ;; TODO: dispose the effect, to avoid memory leaks.
  ,)


;; Shadow-CLJS hooks: start & reload the app

(defn start-app []
  (setup!))

(defn ^:dev/before-load stop-app []
  (shutdown!))

(defn ^:dev/after-load restart-app []
  (setup!))

Let’s start using Signaali by including the namespace:

(ns example.core
  (:require [signaali.reactive :as sr]))

Then we need a state for the counter

(def counter-state
  (sr/create-state nil
                   ;; Optional param, useful for debugging
                   {:metadata {:name "counter state"}}))

Then we need an effect which will update the DOM node with a text version of the counter’s value.

(def counter-text-updater
  (sr/create-effect #(set! (.-textContent counter-element) (str @counter-state))
                    ;; Optional param, useful for debugging
                    {:metadata {:name "counter text updater"}}))

Now let’s make the callbacks interact with Signaali’s state and effect.

(defn on-inc-counter-button-clicked []
  (swap! counter-state inc))

(defn on-reset-counter-button-clicked []
  (reset! counter-state 0))

(defn on-run-effects-button-clicked []
  (sr/re-run-stale-effectful-nodes))

And last, we need to initialize the state and the DOM element’s text on setup, and dispose the effect on shutdown.

(defn setup! []
  (.addEventListener inc-counter-button   "click" on-inc-counter-button-clicked)
  (.addEventListener reset-counter-button "click" on-reset-counter-button-clicked)
  (.addEventListener run-effects-button   "click" on-run-effects-button-clicked)

  (reset! counter-state 0)
  (sr/add-on-dispose-callback counter-text-updater #(set! (.-textContent counter-element) "n/a"))
  @counter-text-updater)

(defn shutdown! []
  (sr/dispose counter-text-updater)

  (.removeEventListener inc-counter-button   "click" on-inc-counter-button-clicked)
  (.removeEventListener reset-counter-button "click" on-reset-counter-button-clicked)
  (.removeEventListener run-effects-button   "click" on-run-effects-button-clicked))

You now know most of what you need to start your own web framework in Clojure(script).

In the next blog post of this series, I will start writing helpers to avoid most of the boilerplate we had to type above. That’s usually how web frameworks are born.