= Hypermedia In Action
:chapter: 8
:sectnums:
:figure-caption: Figure {chapter}.
:listing-caption: Listing {chapter}.
:table-caption: Table {chapter}.
:sectnumoffset: 7
// line above: :sectnumoffset: 7 (chapter# minus 1)
:leveloffset: 1
:sourcedir: ../code/src
:source-language:
= Client Side Scripting
This chapter covers
* How scripting can be effectively added to a Hypermedia Driven Application
* Adding a javascript-based confirmation dialog for deleting contacts
// js
* Adding a three-dot menu in our contacts table
// alpine
* Adding a keyboard shortcut for focusing the search input
// hyperscript
* Adding support for re-ordering contacts via drag-and-drop
// off the shelf
[partintro]
== Scripting in Hypermedia-Driven Applications
"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."
-- Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures
Thus far we have avoided writing any JavaScript for Contact.app, mainly because the functionality we implemented so far does not need it. Contrary to popular belief, hypermedia is not just for "documents" (where a document is considered essentially different to an "app"), and it has many affordances for building interactive experiences. We want to show that it is possible to build sophisticated web applications using the original model of the web without the abstractions provided by JavaScript frameworks. On the other hand, htmx itself is written in JavaScript, and we don't want our message to be interpreted as "JavaScript bad", or, more generally, "Client-side scripting bad."
The question isn't "Should we be scripting for the web?" but rather "How should we be scripting for the web?"
Scripting has been a massive multiplier of the Web's capabilities. Through its use, Web application authors are not only able to enhance their hypertext-based websites, but also create full-fledged client-side applications that can compete with native apps in how they work (although they don't always win when they do). In other terms, the Web became a distribution medium for non-REST apps in addition to being a RESTful system. When it's not used as a replacement for the RESTful architecture provided by the Web, however, scripting is extremely useful in Hypermedia Driven Applications.
You are scripting in a way compatible with HDAs if:
* The main data format exchanged between server of client is hypermedia, the same as it would be in an application with no scripting.
* Client-side state (other than the DOM) is minimized.
This style of scripting requires us to adopt different practices than what is typically recommended for JavaScript, as the most common advice often comes, naturally, from SPA or server-side backgrounds. We will see these new practices in action in the upcoming chapter.
Simply listing "best practices", however, is rarely convincing or edifying (and, frankly, it is often boring). So, we instead will frame them around shiny tools that work well for scripting in a HDA. We will use each of these tools to add a feature to ContactApp:
* An overflow menu to hold the _Edit_, _View_ and _Delete_ actions, to clean up visual clutter in our list of contacts
* Reordering contacts by dragging and dropping
* A dialog to confirm the deletion of contacts
* A keyboard shortcut for focusing the search box
The important idea in the implementation of each of these features is that they are implemented entirely client-side and yet they don't exchange information with the server using, for example, JSON. This constraint is what will keep the features within the bounds of a proper Hypermedia Driven Application.
== Scripting tools for the Web
The primary scripting language for the web is, of course, JavaScript, which is ubiquitous in web development today. A bit of interesting internet lore, however, is that JavaScript was not always the only built-in option. As the quote from Roy Fielding above indicates, _applets_ written in other languages such as Java were considered part of the scripting infrastructure of the web. In addition, there was a brief period when Internet Explorer supported VBScript, a scripting language based on Visual Basic.
Today, we have a variety of _transcompilers_ (often shortened to _transpilers_) that convert another language to JavaScript, such as TypeScript, Dart, Kotlin, ClojureScript, F#. There is also the WebAssembly bytecode format, which is supported as a compilation target for C, Rust, and the WASM-first language AssemblyScript. However, most of these are not geared towards an HDA-compatible style of scripting --- compile-to-JS languages are often paired with SPA-oriented libraries (Dart and AngularDart, ClojureScript and Reagent, F# and Elmish), and WASM is currently mainly geared toward linking to C/C++ libraries from JavaScript.
We bring this up because we are going to look at three different mechanisms for adding scripting to our Hypermedia Driven Application:
* Vanilla JS, that is, using JavaScript without depending on any framework.
* Alpine.js, a JavaScript library for adding behavior directly in HTML.
* _hyperscript, a non-JavaScript scripting language created alongside htmx. Like AlpineJS, it is usually embedded in HTML.
Let's take a quick look at each of these scripting options, so we know what we are dealing with. As with CSS, we are not going to deep dive into any of these options: we are going to show just enough to give you a flavor of each and, we hope, spark your interest in looking into each of them more extensively.
== Vanilla JavaScript
[quote, Merb]
No code is faster than no code.
Vanilla JavaScript is simply using JavaScript in your application without any intermediate layers. The term came into vogue as a play on the fact that there were so many ".js" frameworks out there to help you write JavaScript. As JavaScript matured as a scripting language, standardized across browsers and provided more and more functionality, the utility of many of these frameworks and libraries has diminished. (At the same time, however, SPAs have become more popular, requiring more elaborate JavaScript frameworks).
A quote from the humorous website http://vanilla-js.com captures the situation well:
[quote, http://vanilla-js.com]
Vanilla JS is the lowest-overhead, most comprehensive framework I've ever used.
The message of _VanillaJS_ here is that since the browser already has JavaScript baked into it, there isn't any need to download a framework for your application to function. This is true more often than we might like to admit, and is especially the case in HDAs, since hypermedia obviates many features provided by JavaScript frameworks:
* Client-side routing
* An abstraction over DOM manipulation, i.e.: templates that automatically update when referenced variables change
* Server side rendering (rendering here refers to HTML generation)
* Attaching dynamic behavior to server-rendered tags on load
* Network requests
Installation of VanillaJS couldn't be easier: you don't have to. You can just start writing JavaScript in your web application, and it will simply work.
That's the good news. The bad news is that, despite improvements over the last decade, JavaScript has some significant limitations as a scripting language that often make it less than ideal as a stand-alone scripting technology for Hypermedia Driven Applications:
* It is a relatively complex language that has accreted a lot of features and warts.
* JavaScript's asynchrony model involves _colored functions_, a concept described in Robert Nystrom's oft-cited _What Color is Your Function?_
footnote:[https://journal.stuffwithstuff.com/2015/02/01/what-color-is-your-function/]
* It is surprisingly clunky to work with events.
* DOM APIs (a large portion of which were originally designed for Java) are verbose and do not make common functionality easy to use.
None of these are deal-breakers, of course, and many people prefer the "close to the metal" (for lack of a better term) nature of vanilla JavaScript to more elaborate client-side scripting approaches.
To dive into Vanilla JavaScript as a front end scripting option, let's write a simple counter footnote:[The counter is a common example widget for UI development tools, a trend that seems to have been started by React. İt's unclear if the "counterexample" pun was intentional.]. It will have a number and a button that increments the number. Nothing too elaborate, but it will give you the flavor of each of the three scripting approaches we are going to use in this chapter.
A problem with tackling this problem in Vanilla JavaScript is that it lacks something most JavaScript frameworks
provide: a standardized code style. This is not an insurmountable issue, and in fact, it presents a great opportunity to take a small journey through various styles. For our counter, we will start with the simplest thing possible.
.Counter in vanilla JavaScript, inline version
[source,html]
----
<1>
----
<1> Our output element has an ID to help us find it
<2> We use the `onclick` attribute, a brittle but quick way to add an event listener
<3> Find the output
<4> JavaScript lets us use the `++` operator on a string because it loves us
So, not too bad. It's a little annoying that we needed to add an `id` to the span to make this work and `document.querySelector` is a bit verbose compared to, say, `$` (if you are familiar with jQuery) but (but!) it works, and it doesn't require any other JavaScript libraries.
So that's the simple, inline approach. A more standard way to write this code, however, would be to move it into a separate JavaScript file, either linked via a `
----
You can also install it from npm, or vendor it from your own server.
The main interface of Alpine is a set of HTML attributes, the main one of which is `x-data`. The content of `x-data` is a JavaScript expression which evaluates to an object, whose properties we can access in the element. For our counter, the only state is the current number, so let's create an object with one property:
.Counter with Alpine, line 1
[source,html]
----
----
We've defined our state, let's actually use it:
.Counter with Alpine, lines 1-2
[source,html,highlight=2..2]
----
<1>
----
<1> The `x-text` attribute.
This attribute sets the text content of an element to a given expression. Notice that we can access the data of a parent element.
To attach event listeners, we use `x-on`:
.Counter with Alpine, the full thing
[source,html,highlight=4..4]
----
<1>
----
<1> With `x-on`, we specify the attribute in the attribute _name_.
Would you look at that, we're done already! (It's almost as though we wrote a trivial example). What we created is, incidentally, nearly identical to the second code example in Alpine's documentation --- available at https://alpinejs.dev/start-here[].
=== `x-on:click` vs. `onclick`
The `x-on:click` attribute (or its shorthand `@click`) differs from the browser built-in `onclick` attribute in significant ways that make it much more useful:
* You can listen for events from other elements. For example, the `.outside` modifier lets you listen to any click event that is **not** within the element.
* You can use other modifiers to
** throttle or debounce event listeners,
** ignore events that are bubbled up from descendant elements, or
** attach passive listeners.
* You can listen to custom events, such as those dispatched by htmx.
=== Reactivity and templating
As you can see, this code is much tighter than the VanillaJS implementation. It helps that AlpineJS supports a notion
of variables, allowing you to bind the visibility of the `span` element to a variable that both it and the button
can access. Alpine allows for much more elaborate data bindings as well, it is an excellent general purpose client-side
scripting library.
=== Alpine.js in action: A confirmation dialog
Right now, clicking the `Delete` link on a contact instantly deletes it, making it prone to accidents. We'll use Alpine.js on our Delete button to show a confirmation before proceeding.
[source,js]
----
document.querySelectorAll("[data-confirm]") <1>
.forEach(el => {
// ...
})
----
<1> Find relevant elements. Our attribute is `data-confirm`, so we'll write this code in a file named `confirm.js`.
We need to show a confirmation dialog. There are libraries that let us show styled, rich alert dialogs, but let's just use `confirm()` for now. Adding in a library later will be a good test of how maintainable our code is.
[source,js,highlight=2..4]
----
document.querySelectorAll("[data-confirm]")
.forEach(el => {
el.addEventListener("...", e => { <1>
const didConfirm = confirm()
if (!didConfirm) {
event.stopImmediatePropagation(); <2>
event.stopPropagation(); <3>
}
})
})
----
<1> **What event?**
<2> Prevent listeners on this element from running
<3> Prevent listeners on parent elements from running
We need to decide what event we need to listen to:
* Hardcode `"click"`. It's simple and it covers most cases. However, there's not a clear escape hatch if you need a different event.
* Try to sniff what event you need to listen to based on the element. Complex and fragile (but I repeat myself).
* Let the author specify in the attribute. This is what we'll do.
[source,js]
----
el.addEventListener(
el.dataset.confirm || "click", <1>
e => {
// ...
}
)
----
<1> Specify a default for convenience.
In 9 lines of code, we have a generic confirmation library that we can use for any element as follows. It's definitely overengineered as a result of the forced decoupling, just like the counter earlier, but it works well and was reasonably fun to write.
[source,html]
----
----
.Async ruins everything
****
In the confirmation dialog code we wrote, we use `confirm()`, which is convenient, but displays a barebones dialog that cannot contain rich text. Can we write a similar script using a fancy alert dialog library, like SweetAlert2?
[source,js,highlight=4..5]
----
document.querySelectorAll("[data-confirm]")
.forEach(el => {
el.addEventListener("click", e => {
const result = await Swal.fire("Are you sure?", "", "question")
const didConfirm = result.isConfirmed
if (!didConfirm) {
event.stopImmediatePropagation();
event.stopPropagation();
}
})
})
----
[samp]
----
Uncaught SyntaxError: await is only valid in async functions, async generators and modules
----
Right. Let's fix that...
[source,js,highlight=3]
----
document.querySelectorAll("[data-confirm]")
.forEach(el => {
el.addEventListener("click", async e => {
const result = await Swal.fire("Are you sure?", "", "question")
const didConfirm = result.isConfirmed
if (!didConfirm) {
event.stopImmediatePropagation();
event.stopPropagation();
}
})
})
----
No more errors, but this code no longer works. This is because by the time we call `stopPropagation` and `stopImmediatePropagation`, the event has already propagated. We can avoid this when using the built-in `confirm` function because it has the privilege of blocking the main thread.
There is no general solution to this problem.
****
=== Reusable behavior in Alpine
Our menu component has a lot of attributes that will currently be repeated in every item of the table. This is hard to maintain when manually writing HTML and increases payload sizes when generating it via a template. We can rectify this using an nifty feature of the `x-bind` attribute:
[quote,"https://alpinejs.dev/directives/bind#bind-directives"]
____
x-bind allows you to bind an object of different directives and attributes to an element.
The object keys can be anything you would normally write as an attribute name in Alpine. This includes Alpine directives and modifiers, but also plain HTML attributes. The object values are either plain strings, or in the case of dynamic Alpine directives, callbacks to be evaluated by Alpine.
____
It's far easier to understand what this means after seeing the attribute in use. To begin, we create a JavaScript function which will encapsulate all of our menu's behavior:
[source,js]
----
function menu() {
return {
role: "menu",
"x-show"() { <1>
return this.open; <2>
},
"x-on:click.outside"() { this.open = false },
"x-on:keydown.up"() { document.activeElement.previousElementSibling?.focus() },
"x-on:keydown.down"() { document.activeElement.nextElementSibling?.focus() },
"x-on:keydown.space"() { document.activeElement.click() },
"x-effect"() { if (this.open) this.$el.firstElementChild.focus() },
"x-on:keydown"(event) { <3>
if (event.key === 'Home') $el.firstChild.focus()
else if (event.key === 'End') $el.lastChild.focus()
},
}
}
----
<1> JavaScript allows any string literal to be the name of an object member. This even works with classes!
<2> Values that would be globally accessible in an attribute are accessed through `this` in a function.
<3> We can clean up longer functions.
The return value is a map of attribute names to values, with Alpine attributes having functions as values instead of strings of code. We can then reference this function in HTML as follows:
[source,html]
----
----
This requires the function `menu` to be global. We can avoid that with `Alpine.data`, which is a function to make any data accessible to Alpine expressions:
[source,js]
----
Alpine.data("menu", () => {
return {
role: "menu",
"x-show"() { return this.open; },
// ...
}
})
----
Another useful tool in factoring Alpine code is calling functions in `x-data` as follows:
[source,js]
----
Alpine.data("toggleableMenu", () => ({ open: false }))
----
[source,html]
----