7.6 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 mentioned scripting briefly, advocating for inline scripting as enabled by libraries such as Alpine.js and hyperscript.
We also said this:
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 a bit on this last bit and discuss what scripting that does not "supersede" or "subvert" a REST-ful application looks like.
The Prime Directive
The prime directive of an HDA is to use Hypermedia As The Engine of Application State. A compatible 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 involve a hypermedia of some sort.
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:
Allowing features to be downloaded after deployment improves system extensibility.
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 UI-language of a larger JavaScript application.
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.
Pragmatism
Of course, there are JavaScript libraries that violate HATEOAS and that do not trigger events, making 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 they provide to integrate with the DOM and to trigger events, then that is a good route to go to adapt them to a Hypermedia-Driven approach.
But, if not, and if there are no good alternatives, then use the JavaScript library as it is designed, and then simply try to limit the conceptual exposer of that library to the rest of the application.