What is Hoplon?

hoplon/hoplon

Hoplon is a simple and powerful tool for building web apps out of highly composable elements in ClojureScript.

You don’t necessarily need to understand CLJS to read this post, I wrote it to (hopefully) be accessible to JavaScript people too!

Hoplon does not rely on interop with any underlying JavaScript framework (e.g. React) — its core is pure CLJS with optional extensions for jQuery, Google Closure, etc. The core functionality weighs in at under 1000 LOC so reading and understanding the internal code is encouraged and a great way to learn some CLJS if you’re just starting out!

Hoplon is an abstraction of the DOM

Hoplon is an abstraction and extension of the native JavaScript DOM API.

The DOM API is native to browsers, object oriented and stateful/mutable.

HTML documents are portable, for sharing over a network between servers/clients and so are stateless/immutable.

Every framework that presents something HTML-esque (e.g. JSX templates) to the developer internally bridges the gap between immutable HTML data and mutable JS objects. These bridges can be simple, lightweight templating utils or incredibly monolithic and vendor-lock-in-ey.

Hoplon has no HTML to DOM bridging logic. Every Hoplon function has a direct and simple JavaScript equivalent, keep reading for examples!

No virtual DOM

Write a paper promising salvation, make it a ‘structured’ something or a ‘virtual’ something…and you can almost be certain of having started a new cult.

Dijkstra

Modern HTML to DOM bridges introduce a “Virtual DOM” which is essentially a diff tool for two HTML documents that can derive a minimal set of DOM updates to get from A to B. We need this because the DOM cannot be diffed and has terrible performance in the face of redundant updates.

This gets complex real fast…

Unlike contemporaries such as Hiccup/Reagent/etc. that primarily model HTML and then bridge to the DOM through a rendering layer, Hoplon targets the DOM directly to provide:

• A thin functional wrapper for the DOM’s OO methods
• A sane state management model (when combined with Javelin)

With no rendering process there is no Virtual DOM.

Direct element creation

Hoplon provides a suite of functions to create DOM elements, like div. Every tag is supported, if you find any tag is missing please file a bug report 😉.

(div)

Is equivalent to:

document.createElement('div');

So we get nothing but a new, detached div element in memory.

Clean and simple. 😀

Composing elements

Hoplon extends the js/Element type to implement Ifn.

An elements or sequence of elements passed as an argument to an element will append the arguments as children.

(div (span))

Is equivalent to:

var div = document.createElement('div');
div.appendChild(document.createElement('span'));
return div;

Note that this is not the same as:

document.createElement('div').appendChild('span')

Because appendChild() returns the appended child, where Hoplon returns the parent. For brevity, imagine that all further JS examples return the parent instead of the actual result of the chained method calls.

As the return value is the parent, which can be arguments themselves, nested function calls look eerily similar to HTML, which is entirely by design.

(div (span) (div (span)))

Produces the same thing the following HTML would bootstrap into a browser:

"<div><span></span><div><span></span></div></div>"

So we already start to see how Hoplon, even while technically ignoring HTML, effectively bridges the gap between DOM methods and HTML syntax.

We don’t need a templating layer over Hoplon, because the emergent code structures Hoplon encourages already mirror HTML code structures.

Adding text

Any string or number arguments are converted to text nodes and appended.

(div "Hi!")

Is equivalent to:

document.createElement('div').appendChild(
  document.createTextNode('Hi!')
);

Getting/setting attributes

Key/value pairs as arguments to an element are treated as element attributes.

(div :data-foo "bar")

Is equivalent to:

document.createElement('div').setAttribute('data-foo', 'bar');

While:

(div :data-foo nil)

Is equivalent to:

document.createElement('div').removeAttribute('data-foo');

Elements also implement ILookup so keywords can be used to fetch attributes as though the element were a hash map of its attributes.

(:data-foo (div :data-foo "bar")

Returns "bar" and is equivalent to:

var el = document.createElement('div');
el.setAttribute('data-foo', 'bar');
return el.getAttribute('data-foo');

Adding event handlers

If the key is the name of an event then the value will:

• Trigger that event if truthy
• Bind an event handler if a function

At this point it is worth mentioning that Hoplon has alternative implementations in core, such as jQuery and Google Closure.

The jQuery implementation is especially useful when discussing events as it normalises the logic to something easier to explain than native event handling:

(div :click true)

Is equivalent to (after requiring hoplon.jquery):

jQuery(document.createElement('div')).trigger('click');

While

(div :click (fn [e] (.log js/console @e)))

Is equivalent to:

jQuery(document.createElement('div'))
  .on('click', function(e) {
    console.log(e.val());
  })
);

Note that for convenience Hoplon implements IDeref for jQuery events so that @e in the click handler becomes e.val(). This is especially handy when working with forms and other user input. The raw event object is still available as e.

Mutating elements

Because all js/Element objects implement IFn we can call existing DOM elements as functions in the same way that we create new elements.

(let [el (div)]
  (el (span))
  (el :data-foo "bar"))

Is equivalent to:

let el = document.createElement('div');
el.appendChild(document.createElement('span'));
el.setAttribute('data-foo', 'bar');
return el;

And (div :data-foo "bar") is the same as ((div) :data-foo "bar").

Note that we can mutate any element at any point in time using the same syntax as Hoplon element creation. This is great for interoperability with other JS libs, as Hoplon will accept any DOM element.

For example, ((.getElementById js/document "#my-el") :data-foo "bar") totally does what you’d expect 😀.

Singletons

Everything so far has been working against a detached DOM, or modifying existing DOM elements.

To actually get detached elements into the page Hoplon implements three “singletons” — html, head and body. Calling these functions doesn’t create a new element, instead it updates js/document properties in place.

(body (div))

Is equivalent to:

document.body.appendChild(document.createElement('div'));

Some of the boot (build tool) tasks that ship with Hoplon can also compile the cljs files containing singletons up into a HTML page that bootstraps Hoplon, but this is optional. Hoplon elements interop with existing systems by simply not using singletons and loading the compiled JS file normally.

Managing state

In 2018 many of us (I hope) have traded time dependency management (e.g. async callbacks) in for of data dependency management (e.g. react props). If so, we won’t be satisfied passing our elements through nested callback hell just to update some aesthetic attribute at the end.

hoplon/javelin

To avoid this, Hoplon has a deep, native integration with Javelin, another library from the creators of Hoplon.

I won’t get too deep into Javelin here, that’s a whole other post.

Javelin introduces the concept of “cells”, which are a lot like native cljs atoms and support the same functions, reset!, swap!, etc.

When a js/Element is passed a cell argument, it reruns its internal logic whenever that cell’s value changes.

(let [c (cell "bar")]
 (div :data-foo c) ; <div data-foo="bar"></div> <-- create a div
 (reset! c "baz")) ; <div data-foo="baz"></div> <-- attribute update

This means we can write all our application logic against the values in our cells, trusting the values to propagate to the correct DOM elements.

Cells themselves can be passed between elements. This is a simple button that toggles visibility of another element:

(defn my-button [c] (button :click #(swap! c not)))
(defn my-el [c] (div :toggle c))
(div
 (let [c (j/cell true)] <-- same cell for both els...
  (div 
   (my-button c) ; <-- click this...
   (my-el c)))) ; <-- toggle this!

Cells implement a reactive programming model where cells can depend on the value of other cells, using cell= for a read only “formula cell”.

(let [a (cell "Hello")
      b (cell "world")
      c (cell= (str a " " b "!"))]
 (div c) ; <div>Hello world!</div>
 (reset! b "Dave")) ; <div>Hello Dave</div>

Every formula cell has an internal cache so that only new values are caculated and propagate. There’s no risk of us thrashing the DOM with redundant updates when we change an unrelated cell somewhere. This allows us to efficiently avoid the need for a Virtual DOM.

Unit tests

Cell values propagate to DOM elements even if they are detached, making unit tests for the UI trivial to write with native cljs tools.

(deftest ??foo
 (let [c (cell "bar")
       el(div :data-foo c)]
  (is (= "bar" (:data-foo el))) ; passes!
  (reset! c "baz")
  (is (= "baz" (:data-foo el)))) ; passes!

Higher order elements

Because DOM elements are functions, we can use all native CLJS function manipulation tools.

For example, we can comp elements together:

(def my-el (comp div span)) ; creates a fn that composes div/span
(my-el) ; <div><span></span></div>

We can partial some classes onto something we re-use a lot:

(def big-button (partial button :class "big"))
(big-button "Click me!") ; <button class="big">Click me!</button>

We can map over a list of items:

(map span ["Cat" "Dog"]) ; <span>Cat</span><span>Dog</span>

Extensibility

As I mentioned above, Hoplon implements core logic with native JS, jQuery and Google Closure, as well as providing SVG support.

These reimplementations are all achieved through native CLJS multimethods.

This is how, for example, Hoplon knows to treat :click as an event rather than an attribute.

This extensibility can be really powerful, the other day I integrated Auth0 to allow JWT backed social logins with a single :login! attribute.

(button :login! {:connection "google-oauth2"} "Login with Google")
(button :login! {:connection "facebook"} "Login with Facebook")

thedavidmeister/hoplon-auth0

That’s Hoplon!

Well, that’s all the fundamentals at least. There’s a lot more to learn about, but far more than I can write in a single post…

Hopefully I’ve piqued your interest though, join us in #hoplon in clojurians slack to hang out and learn more!

✉️ Subscribe to CodeBurst’s once-weekly Email Blast, 🐦 Follow CodeBurst on Twitter, view 🗺️ The 2018 Web Developer Roadmap, and 🕸️ Learn Full Stack Web Development.