Share options

Links to related pages

Essays about code. Essays about connection. Essays about context. Critiques of coding practices.

DOM to JSON and back

We can persist and rehydrate DOM objects with simple vanilla JS.

Time to read

, 1332 words, 4th grade

Here we will create two simple but powerful JavaScript functions.

The first, jsToDom, will take a JavaScript (or JSON) object and turn it into a DOM object that we can insert into our page. The second, domToJs, does the reverse. It takes a DOM object and converts it to JS.

Now we can stringify it and persist it in our database. And rehydrate it at will.

As you may know, JSON does not recognize functions. So we will need a way to deal with our event listeners. Donʼt worry! Weʼve got it covered.

Check out our example of DOM to JSON and back in action. We will explain it below.

Our reasoning

A key axiom of Craft Code is less is more. This influences several of the Craft Code methods, such as code just in time and keep it simple.

This means that we donʼt rush to load up dozens of frameworks, libraries, and other dependencies. Instead, we start with nothing: zero dependencies.

We build the site structure with semantically-correct and accessible HTML. Then we add just enough CSS to make it attractive, user-friendly, and responsive.

Finally, we add JavaScript to progressively enhance the user experience. But only if we need it.

This vanilla approach works very well. One goal of the Craft Code effort is to see how far we can go before we have to add a dependency on someone elseʼs code.

The code

For the impatient, letʼs take a look at the final code. Then weʼll explain it. The next two functions are the totality of the module. The rest are specific to this example.

Note: this is about concepts, not production-ready code. This is a first pass and might could use some refactoring. YMMV.

This function converts our JS or JSON to DOM objects.
// ./modules/js-to-dom.js
export default async function jsToDom(js) {
  const { attributes, children, events, tagName } = js

  const elem = document.createElement(tagName)

  for (const attr in attributes) {
    elem.setAttribute(attr, attributes[attr])
  }

  if (Array.isArray(children)) {
    for (const child of children) {
      typeof child === "object" ? elem.appendChild(await jsToDom(child)) : elem.appendChild(document.createTextNode(child))
    }
  }

  if (events) {
    for (const key in events) {
      if (!events[key]) {
        break
      }

      const handler = typeof events[key] === "function" ? events[key] : (await import(`./${events[key]}.js`)).default

      handler && elem.addEventListener(key, handler)
    }

    setDataEvents(elem, js.events)
  }

  return elem
}

function setDataEvents(elem, obj = {}) {
  const eventString = Object.keys(obj)
    .reduce((out, key) => {
      if (typeof obj[key] === "string") {
        out.push(`${key}:${obj[key]}`)
      }

      return out
    }, [])
    .join(",")

  if (eventString) {
    elem.setAttribute("data-events", eventString)
  }
}

The jsToDom function takes a JavaScript or JSON object as its sole parameter.

First, we extract the attributes, children, events, and tagName from the passed object into variables. Then we create an element of type tagName using document.createElement.

Next we loop through the attributes object using element.setAttribute to add each as an attribute to the DOM element.

Moving on, we loop through the children array, if it exists. For each child object, we call jsToDom recursively, passing it the object. In this way we build a tree of DOM elements. We use element.appendChild to append them to our element.

Next, we need to handle any events. If an events object exists, then we loop through it. Each key-value pair represents an event name and a function or function name, respectively. If the value is of type “function”, then we use element.addEventListener to add it to the element. If the value is a string, then we import the default function from a module with that name and use that as our handler.

For example, if we have a key “click” and a value of “log”, then we would import the default from ./modules/log.js and attach it with addEventListener("click", log).

Finally, we use a utility function called setDataEvents, passing it our element and our events object. This converts our object to a comma-separated string of key-colon-function-namne. The above example would yield “click:log”. We set this as an attribute on our element with name “data-events”.

This permits us to reverse our cast and recreate the JS or JSON object from our DOM element. But it only works for function names. If we pass a function, there is no easy way to get it back.

We grab the tagName from the JSON and create a DOM element of that type. Then we add the attributes to that element. Then we apply jsToDom recursively on the children, appending them to the element.

The events object is pretty clever, IOHO. The keys are the names of the events (e.g., click) and the values are the names of the handler functions. We will import those functions only when needed. See an example below.

We also create a string representation of the events object. We could have simply stringified it, but we wanted to make it human readable, so we wrote our own (lines #39 to #52).

This function converts our DOM object to JavaScript.
// ./modules/dom-to-js.js
export default function domToJs(dom) {
  const { attributes, childNodes, tagName } = dom

  const eventList = dom.getAttribute("data-events")

  const events = eventList?.split(",").reduce((out, evt) => {
    const [key, value] = evt.split(":")

    if (key) {
      out[key] = value
    }

    return out
  }, {})

  const attrs = Object.values(attributes)
    .map((v) => v.localName)
    .filter((name) => name !== "data-events")

  return {
    tagName,
    attributes: attrs.reduce((out, attr) => {
      out[attr] = dom.getAttribute(attr)

      return out
    }, {}),
    events,
    children: Array.from(childNodes).map((_, idx) => {
      const child = childNodes[idx]

      return child.nodeType === Node.TEXT_NODE ? child.nodeValue : domToJs(child)
    }),
  }
}

The domToJs function takes a single parameter. This is the root DOM element that we want to convert to JavaScript or JSON.

We begin by extracting the attributes, childNodes, and tagName from the element. First, we will deal with the events. We get the data-events attribute with element.getAttribute. If it exists, we split the string on the commas, then loop through our array using reduce. We recreate our events object in this way and store it in an events variable.

Next we use Object.values to get the attributes and map through them using attribute.localName to get the attribute name. We filter out our data-events attribute as weʼve handled that already.

Finally, we return an object. Our first key is our tagName. Using our attribute names, we create an attributes key and set its value to an object we create with reduce and getAttribute. We drop in our events object.

Lastly, we turn our childNodes NodeList into an Array with Array.from. Then we map it to an array of strings (if the child is a text node), or JS objects by calling domToJs recursively.

This is a bit tricky as nothing in the DOM is simple. Go figure. We explain below.

This extracts the attributes, the childNodes, and tagName from the passed DOM element. Then we use these to create a simple JS/JSON object, recursing through the child nodes.

We pull the data-events attribute out and treat it separately. We parse the value back into an actual object and add it at the events key.

The output is JS, but we can stringify it to JSON as required. The JSON shown below is a typical example. It creates our test form.

The JSON representation of our example form.
{
  "tagName": "FORM",
  "attributes": {
    "action": "#",
    "method": "POST",
    "name": "form"
  },
  "events": {
    "focusin": "log",
    "submit": "parse-submission"
  },
  "children": [
    {
      "tagName": "TEXTAREA",
      "attributes": {
        "data-type": "json",
        "name": "json"
      },
      "children": ["{\"tagName\":\"DIV\",\"attributes\":{\"class\":\"sb-test\",\"data-type\":\"string\",\"id\":\"sb-test-id\"},\"events\":{\"click\":\"log\"},\"children\":[{\"tagName\":\"STRONG\",\"children\":[\"Bob's yer uncle.\"]}]}"]
    },
    {
      "tagName": "BUTTON",
      "attributes": {
        "aria-label": "Run this baby",
        "type": "submit"
      },
      "children": ["Run"]
    }
  ]
}

Our JSON is simple. We have a tagName key with the value “FORM”. This will create a form element.

Next we have an attributes key whose value is an object. The object contains key-value pairs where the key is the name of the attribute and the value is the attributeʼs value. Here we set action to “#”, method to “POST”, and name to “form”. Not very imaginative, we admit.

Next is a children key with value set to an array of similar JSON objects for each of the children. These are nested successively.

Finally, we have an events key whose value is an object. The keys are event names, such as “focusin”, and the values are the names of functions to import and use as handlers, e.g., “log”.

We import this JSON and pass it to jsToDom in our index.js file below.

We append the output div and the form into main on DOMContentLoaded.
// index.js
import jsToDom from "./modules/js-to-dom.js"
import formJson from "./modules/form-json.js"
import outJson from "./modules/out-json.js"

export async function injectForm() {
  const main = document.querySelector("main")

  main.appendChild(await jsToDom(outJson))

  main.appendChild(await jsToDom(formJson))
}

globalThis.addEventListener("DOMContentLoaded", injectForm)

This is our main JS file, index.js. We begin by importing the jsToDom function, our form JSON and the JSON to produce a div element for our output.

Then we create an asyncronous function called injectForm. We use document.querySelector to get the main element. Then we convert our output JSON to a DOM element with jsToDom and use appendChild to append it to main.

Finally, we use jsToDom again on our form JSON this time, and append that element to main. Now that we have our function ready, we use globalThis.addEventListener to run it on DOMContentLoaded, injecting the form.

Pretty self-explanatory. Now, how do we handle our events?

Simple. We take our events object from the passed JSON/JS. Then we loop through the keys, which are the event types. The values are the names of the handler functions.

We add an event listener for each type and assign it the default function from the module with that name. For example, our output div gets a click handler called “log”. This function is in ./modules/log.js.

We import the handler: (await import("./log.js")).default. We assign it to handler.

Then we add it like this: addEventListener("click", handler).

Drop dead simple. And we only import the modules that we need. See the actual log handler below.

A simple logger for our example.
// ./modules/log.js
export default function log({ target }) {
  console.log(target?.tagName, target?.innerText || target?.value)
}

This super simple function, for example purposes only, gets the target element and logs out the tagName and the innerText or the value to the console.

Kinda dumb, but it is merely an example. We add this log function as a click handler on our output strong element and as a focusin handler on our form.

The submit handler for the form is a bit more exciting:

Our event listener to handle form submission.
// ./modules/parse-submission.js
import domToJs from "./dom-to-js.js"
import jsToDom from "./js-to-dom.js"

export default async function (event) {
  event.preventDefault()

  const form = event.target
  const textarea = form.querySelector("textarea")
  const out = document.querySelector(".out")

  const js = JSON.parse(textarea.value)

  out.appendChild(await jsToDom(js))

  const newForm = domToJs(form)

  document.querySelector("main").appendChild(await jsToDom(newForm))
}

Here we begin by importing our functions, domToJs and jsToDom. Then we export as default an asynchronous anonymous function. It takes one parameter: the event.

First we call event.preventDefault to prevent the form from reloading the page. Then we get the form element from the event.target.

From this element, we use querySelector to get the formʼs textarea element. And we use querySelector again on the document to get the output dive.

We use JSON.parse to parse the textarea.value into a JS object. We pass this to jsToDom and use appendChild to append it to our output div.

So we have used the JSON in the textarea to generate a DOM element and have appended it to the page. Nice. Now, for fun, we pass the form element to the domToJs to convert it to JS. Then we use the jsToDom function again to convert it right back and we append this copy of the form to the main element, proving that we can make the round trip.

We canʼt store functions in JSON, so we put them into modules. Then we will import them as needed when we rehydrate the DOM elements.

We attach parseSubmission as the submit handler for our form element.

What can we do with this?

Ooo. All sorts of cool things.

Easy element creation

Instead of messing around with createElement, setAttribute, etc., we can use jsToDom. We pass it a JS or JSON object representing the DOM elements we want.

We create handler functions ahead of time in modules. When we need an event listener, jsToDom imports it just in time and assigns it to the element.

This works like Reactʼs createElement function. Or a library such as hyperscript. Sure, weʼd prefer JSX for its much reduced cognitive load. But our alternative here is the DOM methods such as createElement. Unless we want to load up a bulky library such as React, that is.

We donʼt.

Suppose I wanted to inject a password field with a show/hide button. First, we create a toggle handler such as this:

This toggles an input from password to text and back.
// ./modules/toggle-visibility.js
export default function (event) {
  const button = event.target
  const div = button.closest(".form-field")
  const input = div?.querySelector("input")

  if (input) {
    if (input.type === "password") {
      input.type = "text"
      button.innerText = "hide"
      button.setAttribute("aria-label", "Hide password.")
      return
    }

    input.type = "password"
    button.innerText = "show"
    button.setAttribute("aria-label", "Show password.")
  }
}

This is an example of an event handler. We create these in advance so that we can import them by name as needed. Here, we put them in a modules folder.

Our code exports as default an anonymous function which takes a single parameter. This is the event object, of course.

Next we assign the event.target to a button variable. (The target is a button.) We use closest to find the closest element to the button with class “form-field”. This will be the div wrapper.

Then, using that wrapper, we can use querySelector to get the password input.

With these three variables — button, div, and input — we go to work.

If the input type is “password”, then we want to toggle it to “text” to unhide the password. We set input.type to “text”. We also set the button.innerText to “hide” (the password is now showing) and the buttonʼs aria-label to “Hide password.” And we return.

Otherwise, we set input.type to “password”, button.innerText to “show”, and the aria-label to “Show password.”

Now I can call jsToDom with the following JSON and it will create my password input. Try pasting it into the example form. Remember that the click event handler is already available at ./modules/toggle-visibility.js.

This will create a password field with show/hide capability.
{
  "tagName": "DIV",
  "attributes": {
    "class": "form-field"
  },
  "events": {
    "click": "log"
  },
  "children": [
    {
      "tagName": "INPUT",
      "attributes": {
        "type": "password"
      }
    },
    {
      "tagName": "BUTTON",
      "attributes": {
        "aria-label": "Show password.",
        "class": "xx-toggle-password",
        "type": "button"
      },
      "events": {
        "click": "toggle-visibility"
      },
      "children": ["show"]
    }
  ]
}

The password field JSON object starts with an outer div element, so we set the tagName key to the value “DIV”. We want this div to have a class name “form-field”, so we set our attributes value to an object with a single key of class having the value “form-field”.

Then we add a click event set to use the “log” module. When we click on the div, it will log its tagName and innerText to the console.

Finally, we want to add children to our div wrapper. We set the children key to an array of objects. The first represents an input element with attribute type set to “password”.

The second child is a button. We set three attributes: aria-label to “Show password.”, type to “button” to prevent form submission, and a class of “xx-toggle-password” just because.

Now we add the events key. It is an object with one key-value pair. The key is click and the value is “toggle-visibility”, which is the name of the module holding our visibility toggle event handler.

Finally, we set the buttonʼs children to a single text element, “show”.

We hope that it is straightforward how all this works.

Easy element persistance

What if I want to save current UI state? We can use domToJs to do just that.

We took the example page (linked above) and passed the html element to domToJs. Then we stringified it. Now we have preserved both the head and body elements.

So we can take a blank HTML document like this:

Our HTML skeleton into which we will inject our head and body elements.
<html lang="en">
  <head> </head>
  <body>
    <script
      src="./modules/make-page.js"
      type="module"
    ></script>
  </body>
</html>

This example is a very simple HTML document. It has a html element with the lang attribute set to “en”. Inside the html element are an empty head element and a body element containing a single script element. This script loads the “make-page.js” module which then injects the actual page.

And we can use our persisted JSON head and body elements to create the page on the fly. We can store the JSON in a database or load it from an API.

Below is the code minus the JSON. Or view the actual code.

Then see it in action. View the source on that page to see what we mean.

Injecting our dynamically-generated head and body elements.
import jsToDom from "./js-to-dom.js"

globalThis.addEventListener("DOMContentLoaded", async () => {
  const h = document.documentElement.querySelector("head")
  const b = document.documentElement.querySelector("body")

  h.replaceWith(await jsToDom(/* head JSON here */))

  b.replaceWith(await jsToDom(/* body JSON here */))
})

This is the very simple script that generates our example page. We begin by importing the jsToDom function. Then we add an event listener to globalThis to run on DOMContentLoaded and we pass it an asynchronous anonymous arrow function.

In the function we use querySelector to grap the head and body elements. Then we use element.replaceWith and our jsToDom utility function to convert our head and body JSON objects to DOM elements and inject them into our page. Done!

A whole page generated from simple JSON!

Data-driven user interfaces

One idea that we have been promoting for several years now is that of a data-driven interface. Weʼve got an article in the pipeline on that coming soon. But we can give a quick overview here.

The idea is quite simple. The easiest example to visualize is automated form rendering.

Forms collect data. Typically, that data is then persisted in a database.

Databases have schemas. That means that the database already knows the types it expects. If we have defined our schema well, then it knows those types precisely.

Particular data use particular interface widgets. For example, an email address would use an input element of type “email”. An integer might use an input element of type “number” with its step attribute set to “1”.

An enum might use a select or radio buttons or a checkbox group.

From this schema we should be able to determine how to both display and validate that data. After all, there is only a small number of widgets.

So what if the response to our database query for the data included the schema? Some GraphQL queries already make this possible. From that schema, we can generate validation functions. And we know which widgets to display.

So we can generate our form and our validators automatically.

Best of all, we have a single source of truth: our database schema.

In a coming article, we will explain how easy it is to achieve this.

(There is an advanced version of this that uses a SHACL ontology and a triple store such as Fuseki. We then use SPARQL queries to generate the HTML, CSS, and JS straight from the database. Wee ha! Weʼll get to that sometime soon, too. Promise.)

If anyone requests it, weʼll give a detailed explanation of the above code in a separate article. This one is long enough.

Links to related pages

Essays about code. Essays about connection. Essays about context. Critiques of coding practices.

Get notified form

Get notified of site updates
Button bar

Carbon emissions for this page

Cleaner than 98% of pages tested
0.016g on first visit; then on return visits 0.010g
QR Code

Scan this code to open this page on another device.