10 KiB
| layout | title |
|---|---|
| layout.njk | </> htmx - high power tools for html |
Hypermedia-Friendly Scripting
The final addition to our constraint set for REST comes from the code-on-demand style of Section 3.5.3 (Figure 5-8). REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts. This simplifies clients by reducing the number of features required to be pre-implemented. Allowing features to be downloaded after deployment improves system extensibility. However, it also reduces visibility, and thus is only an optional constraint within REST.
Scripting & The Web
In Hypermedia-Driven Applications we discuss how to build web applications in such a manner that they are hypermedia-driven, in contrast with the popular SPA approach, in which they are JavaScript and, at the network-level, RPC-driven.
In the HDA article we mention scripting briefly:
In an HDA, hypermedia (HTML) is the primary medium for building the application, which means that:
- All communication with the server is still managed via HTTP requests with hypermedia (HTML) responses
- Scripting is used mainly to enhance the front-end experience of the application
Scripting augments the existing hypermedia (HTML) but does not supersede it or subvert the fundamental REST-ful architecture of the HDA.
In this article we would like to expand on this last comment and describe what scripting that does not "supersede" or "subvert" a REST-ful, Hypermedia-Driven Application looks like. These rules of thumb apply to scripting written directly to support a web application, as well as to general purpose JavaScript libraries.
The Prime Directive
The prime directive of an HDA is to use Hypermedia As The Engine of Application State. A hypermedia-friendly scripting approach will not violate this directive. At a practical level, this means that scripting should avoid making non-hypermedia exchanges over the network with a backing store. (Recall, REST is a network architecture.)
This means that, in general, scripting should avoid the use of fetch() and XMLHttpRequest unless the responses
from the server are done in terms of a hypermedia of some sort, rather than a data API.
This also means that, in general, complicated state stored in JavaScript (rather than in the DOM) should be avoided.
However, this statement needs to be qualified: sophisticated state may be stored client-side in JavaScript
so long as it is directly supporting a more sophisticated front-end experience (e.g. widget) than pure HTML allows.
Reiterating what Roy Fielding says regarding the purpose of scripting in REST:
Allowing features to be downloaded after deployment improves system extensibility.
So scripting is allowed in a REST-ful system in order to allow the creation of additional features not directly implemented within the underlying hypermedia, making the hypermedia (e.g. HTML) more extensible.
A good example of this sort of feature is a rich-text editor: this may have an extremely sophisticated JavaScript model for the document being edited. However, this model should be encapsulated in the DOM. The rich text editor should participate in the DOM using the standard hypermedia API, such as using a hidden input to communicate the content of the editor to the surrounding DOM, rather than requiring a JavaScript API call to get the content.
The idea is to, yes, use scripting to improve the hypermedia experience by providing features and functionality that are not part of the standard hypermedia (HTML) tool set, but do so in a way that plays well with HTML, rather than flipping the script and making HTML a mere UI description language within a larger JavaScript application, as many SPA frameworks do.
State
Note that using Hypermedia As The Engine Of Application State does not mean that you cannot have any client-side state. Obviously, the rich-text editor example cited above may have a significant amount of client-side state, for example. But there are much simpler cases where client-side state might be warranted. Consider a simple visibility toggle, where clicking a button or anchor adds a class to another element, making it visible.
This ephemeral client-side state is perfectly acceptable in an HDA, because it does not fundamentally alter the system state. At some level it is a very simplified "feature", akin to the rich text editor.
Again, the crucial aspect to consider here is that hiding or showing an element in this manner does not communicate with the server and alter system state outside the normal hypermedia flow.
Events
An excellent way for a JavaScript library to enable hypermedia-friendly scripting is for it to have a rich custom event model.
A JavaScript-based component that triggers events allows for hypermedia-oriented JavaScript libraries, such as htmx, to listen for those events and trigger hypermedia exchanges. This, in turn, makes any JavaScript library a potential hypermedia control, able to drive the Hypermedia-Driven Application via user selected actions.
A good example of this is the Sortable.js example, in which htmx listens for
the end event triggered by Sortable.js:
<form class="sortable" hx-post="/items" hx-trigger="end">
<div class="htmx-indicator">Updating...</div>
<div><input type='hidden' name='item' value='1'/>Item 1</div>
<div><input type='hidden' name='item' value='2'/>Item 2</div>
<div><input type='hidden' name='item' value='3'/>Item 3</div>
<div><input type='hidden' name='item' value='4'/>Item 4</div>
<div><input type='hidden' name='item' value='5'/>Item 5</div>
</form>
The end event is triggered by Sortable.js when a drag-and-drop completes. htmx listens for this event via the
hx-trigger attribute and then issues an HTTP request, exchanging hypermedia with the backing
server. This turns this Sortable.js drag-and-drop powered widget into a new, powerful hypermedia control.
Islands
A recent trend in web development is the notion of "islands":
The islands architecture encourages small, focused chunks of interactivity within server-rendered web pages.
In cases where a more sophisticated scripting approach is required, and where, in particular, communication with a server outside of the hypermedia-exchange mechanism is necessary, the most hypermedia-friendly approach is to use the island architecture. This isolates non-hypermedia components from the rest of the Hypermedia-Driven Application.
Events are a clean way to integrate your non-hypermedia-driven islands within a broader Hypermedia-Driven Application, allowing you to convert an "inner" island into an "outer" hypermedia control, in the mode of the Sortable.js example above.
Deniz Akşimşek has made the observation that it is typically easier to embed non-hypermedia islands within a Hypermedia-Driven Application, rather than vice-versa.
Inline Scripts
Inline scripts are more controversial concept, and, as such, we do not consider it a hard constraint on hypermedia-friendly scripting. The idea with inline scripting is to place scripting directly in the hypermedia. In HTML, this means embedding scripts in attributes on elements.
This approach to scripting, while idiosyncratic, has been adopted by some HTML scripting libraries, notably Alpine.js and hyperscript.
Here is some example hyperscript, showing an inline script:
<button _="on click toggle .visible on the next <section/>">
Show Next Section
</button>
<section>
....
</section>
An advantage of this approach is that, conceptually, the hypermedia itself is emphasized over the scripting of the hypermedia. Contrast this with JSX Components, where the scripting language is the core concept, with hypermedia/HTML embedded within it.
Inline scripts also have the advantage of Locality of Behavior(LoB), and advantage they share with JSX.
Of course, with inline scripts, there should be a soft limit to the amount of scripting done directly within the hypermedia: you don't want to overwhelm the hypermedia with scripting, so that it becomes difficult to understand "the shape" of the hypermedia document. Using techniques like invoking library functions or using hyperscript behaviors allow you to still continue to use inline scripting while pulling significant abstractions out to a separate file or location.
Again, inline scripting isn't going to be as important as other concepts discussed in this post, but it is worth considering as a hypermedia-friendly alternative to a more traditional scripting/hypermedia split.
Pragmatism
Of course, here in the real world, there are many useful JavaScript libraries that violate HATEOAS and that do not trigger events. This often makes them difficult fits for a Hypermedia Driven Application. Nonetheless, they may provide crucial functionality that is difficult to find elsewhere.
In cases like this, we advise pragmatism: if it is easy enough to wrap the JavaScript API that a library provides, you may be able to integrate it with the DOM and trigger your own custom events. In this case, a simple wrapper may be a good route to go to adapt it to a Hypermedia-Driven approach. And, who knows?! Maybe the upstream author would consider your changes to help make their library more hypermedia friendly!
But, if not, and if there are no good alternatives, then just use the JavaScript library as it is designed.
Yes, try to isolate a non-hypermedia friendly library from the rest of the application, but, in general, do not spend too much of your complexity budget on maintaining conceptual purity: sufficient unto the day is the evil thereof.