This is a reference implementation of an Augmented Hypermedia Hub.
It's an http web app that provides a UI, API and proxy for any number of Augmented Hypermedia Registries.
See the Architecture docs for more details.
Deno is required to run the server, using Homebrew on a Mac...
brew install deno
or see the installation guide for alternatives.
Start the server:
PORT=8888 deno task start
(That's really all there is to it, no need to install any npm packages!)
The service has no homepage as such, but instead provides a UI for a named registry, given in the path of the URL.
For example, to open the 'ref' registry in your browser: http://localhost:8888/ref
(WIP: This info is to be gradually moved into docs)
Our augmentations are built on top of htmx, which is a Javascript library that extends the hypermedia controls of HTML via custom attributes. It's worth familiarising yourself with htmx to understand what we are doing below.
Augmentations are applied via CSS rules in a regular CSS stylesheet, and this what you registered above.
The example stylesheet above contains the following:
#x-footer-below::after {
--hx-get: url("footer-blurb.html");
--hx-trigger: load once;
}
This project provides a htmx extension called
css-rules
.
Which searches for
custom CSS properties
that begin --hx-
and copies those properties to the attributes of any element
that matches the selector.
It also supports insertion of pseudo elements if you use the ::before
or
::after
CSS pseudo-element selector.
So in this case:
<div id="x-footer-below">
becomes...
<div id="x-footer-below">
<span class="htmx-pseudo" hx-get="http://localhost:8000/registry/1/footer-blurb.html" hx-trigger="load once">
(the relative URL is resolved against the URL of the stylesheet to create the absolute URL above)
and we then tell htmx to process this element to wire up it's hypermedia controls.
In our example, those hx-*
attributes will trigger a GET
request to the
given URL immediately but only once, and inject the returned HTML content into
the <div>
element.
See hx-get
and
hx-trigger
for more information
about these attributes.
Also, take a look at the addons service for more
.css
augmentations that can be registered.
For example: http://localhost:8100/message/clear.css
, and take a look at the
DOM Mutations Example.
The default behaviour is prevent augmentations from executing any script, but allowing them access to the full range of hypermedia controls provided by htmx. We have a few security measures in place to ensure this:
- All htmx initiated requests are restricted to the same origin as the host
app, using a
htmx:beforeRequest
event listener. See hx/config.js - So all augmentation content is fetched via the host app proxy, and in turn the registry proxy.
- The registry proxy restricts the type of content that can be fetched, and performs sanitation on the content. For HTML content we use Ammonia. See lib/cleanser
NOTE: this is work in progress, it needs a much more thorough test/audit before being production ready.