Reactive HTML with Signaali

Signaali is a library which provides functions to build reactive systems. In this article, I describe how to use it to change the DOM when an event happens or when a data changes.

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.

Making HTML reactive using Signaali

Let’s make an HTML page

Subscribe to my newsletter

Vincent Cantin (green-coder)

Vincent Cantin (green-coder)