Declarative client-side transclusion with h-include

ND

Nicolás Delfino / September 12, 2020

2 min read

Declarative Client-Side Transclusion

In its most basic, h-include is simply a custom element that accepts a src attribute which it will use to fetch content through AJAX, then depending on the outcome of that call, it will transclude the content of the ajax response into itself.

h-include

The outcome of the attempted inclusion is represented in class attributes included_(req status)

h-include

H-Include Types#

h-include ships with different types out of the box, here´s a short description of what they are

h-include
default
h-include-lazy
Includes the HTML resource when element enters the viewport (Intersection Observer)
h-import
Request an HTML resource and include all found scripts and stylesheet references
h-import-lazy
Like h-import + Intersection Observer
h-import requires loadjs to be available on the window object
h-include-navigate
link events are captured by the element itself, changes the src attribute and triggers a refresh

Advanced Usage#

conditional inclusion using WHEN

Since I started using h-include at a client I've gotten more involved in the project and have made some contributions that further mimics the esi spec, one of them being the usage of WHEN and WHEN-FALSE-SRC

Inclusion Based on Predicate

<h-include
  src="logged-in.html"
  when="org.project.predicateFunction"
  when-false-src="log-in.html"
></h-include>

Unlimited Namespacing

<h-include
  src="logged-in.html"
  when="org.project.predicateFunction"
  when-false-src="log-in.html"
></h-include>
request errors and alternative inclusion using WHEN-FALSE-SRC

WHEN-FALSE-SRC can also be used not only as a backup for when the predicate returns false but also to handle request errors

<h-include
  src="unavailable_document.html"
  when-false-src="alternative.html"
></h-include>

Extending H-Include#

Extending h-include to handle different use cases is quite simple to do, for instance - if we imagine needing an h-include element that adds a date as a data attribute to the included element - we could extend the H-include element prototype and override the connected callback method.

window.HInclude.HincludeDateElement = (function () {
  var proto = Object.create(HInclude.HIncludeElement.prototype);
  var addDate = function (element) {
    element.setAttribute('data-date', new Date());
  };

  proto.connectedCallback = function () {
    addDate(this);
  };

  var HincludeDateElement = function () {
    return Reflect.construct(HTMLElement, arguments, HincludeDateElement);
  };
  HincludeDateElement.prototype = proto;

  Elements.define('h-include-date', HincludeDateElement);
  return HincludeDateElement;
})();

Summary#

The h-include library refered in this article is written by Gustaf Nilsson Kotte and is based on hinclude.js by @mnot. Make sure to checkout the github repo if this sounds interesting, there's alot more that I haven't mentioned in this article.