A book on building Hypermedia Driven Applications with htmx and Hyperview
License: Other
Hypermedia Systems is a book about hypermedia.
The book is divided into three parts:
The book is available online here: https://hypermedia.systems
All content found in the /book directory is licenced under Attribution-NonCommercial-ShareAlike 4.0 International.
All other content is licensed under Zero-Clause BSD
https://hypermedia.systems/book/hypermedia-systems
<title><span class="allcaps big">Hypermedia Systems</span></title>
Possibly related issue that was previously closed: #61
The HOWL sidebar says:
The htmx community is multi-language and multi-framework, there are rubyists as well as pythonistas, lispers as well as haskellers
There's no Ruby channel in the Discord and whilst I guess many Rails-heads use DHH's Turbolinks / Hotwire etc, there's a bunch of people in the Ruby community running Ruby without Rails, especially on Sinatra, which fits the Hypermedia and htmx ideology pretty well.
My first reading of the book was on mobile, the second reading on desktop.
This is a screenshot of a couple of the first paragraphs, notice "sophisticated", "ignore" and "applications" are needlessly broken across two lines and hyphenated:
Mobile doesn't have this problem:
If anything I would say it makes more sense to have word-breaking on mobile, it seems pointless on desktop. Although I would argue for no word-breaks on either.
https://github.com/bigskysoftware/hypermedia-systems/blob/main/book/CH06_htmxPatterns.adoc
This hx-boost attribute is unlike most other attributes in htmx: whereas other htmx attributes tend to be very focused on one aspect of improving HTML (e.g. hx-trigger focuses on the events that trigger a request, hx-swap focuses on how responses are swapped into the DOM, etc.) the hx-boost attribute, in contrast, is a high-level .
is a high-level what?
I could be misinterpreting this:
Note also that, especially in web development parlance, the humble “server” is usually a whole fleet of racks, virtual machines, containers and more. Even a worldwide network of datacenters is reduced to “the server” when discussing the client-side of a Hypermedia Driven-Application.
(emphasis mine)
But I'm pretty sure the emboldened text should read server-side
The fantastic progressive enhancement section says:
One thing to note about this solution, however, is that it is not a progressive enhancement to our web application: if someone has disabled JavaScript then this “Delete Contact” button will no longer work. We could do additional work to keep the older mechanism working in a JavaScript-disabled environment, but this would introduce additional HTML and redundant server-side code.
I don't understand how it is "redundant server-side code" if it enables functionality to noJS users.
"The content within the form is more important than the content within an anchor tag."
Suggest changing to:
"The content within the form does different work than the content within an anchor tag."
What does JSON mean in the first HTMX response in the book?
I assume this is an error, correct?
I saved the book as PDF so that I can underline or highlight
A few code snippets in part II have horizontal scroll bar
These code blocks are cropped when printed to pdf
the part of the line that goes beyond right edge is not printed.
I started reading the book, I'm now on chapter 2. I came across these random equal signs and I figured they're supposed to actually be a header.
It wasn't immediately clear to me what toast messages are, so I think these need an introduction.
Hi, I am reading the book and enjoy it a lot. Your arguments and facts really stick! Great way to get developers thinking and rethinking current (best) practices.
While reading the conclusion of chapter 4, you write, there is no HTML API for creating modals. There is one now, in the form of the dialog element.
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog
I think, it would be good to revise the example and stick to the tabs example and a missing tabs element.
The hyphen isn't necessary here, so I've edited them out.
But it's optional.
There's some inconsistency with title casing in the book, for exampe all of these are h3 titles:
Showing A Searchable List Of Contacts
Adding A New Contact
Handling The Post to/contacts/new
And:
VanillaJS in action: an overflow menu
_hyperscript in action: a keyboard shortcut
I'll defer to @codetalcott on style
Address: https://hypermedia.systems/book/contents/
Browser: Chromium v 113.0.5672.126
It would be nice to be able to review the code in it's entirety at various points throughout the book. Between the hardcover book, the web version, and the HTMX documentation. I'm finding it difficult to answer some of my own questions and having some full sets of working source could be a major help! I'm really enjoying the book, but the index at the back of the hardcover book is surprisingly bare too.
Lots of love though too, I'm super excited to work with this technology. I have landed on HTMX and F# for a rewrite of my corporate web portal.
There are:
64 instances of "server side"
23 instances of "server-side"
16 instances of "client side"
29 instances of "client-side"
If you decided on the hyphenated version, I'm sure there's instances that would be correct in the none hyphenated, e.g. if you were referring to something being "an app on the server side" rather than a "server-side app", but on my reading this seemed like an inconsistency.
Hello,
Thank you for publishing this book for free! I just wanted to offer some feedback on an introductory section that I found confusing as someone who hadn't heard the term hypermedia before. The section reads (emphasis, in bold and italics, is my own):
To understand what a hypermedia system is we’ll first take an in-depth look at the canonical hypermedia system: the World Wide Web. Roy Fielding, an engineer who helped create specifications and build the implementations of many early pieces of the web, gave us the term REpresentational State Transfer, or REST. In his PhD dissertation he described REST as a network architecture, and he contrasted it with earlier approaches to building distributed software.
We define a hypermedia system as a system that adheres to the RESTful network architecture in Fielding’s original sense of this term.
Unfortunately, today, you probably associate the term “REST” with JSON APIs, since that is where the term is typically used in industry. This is a misapplied use of the term REST because JSON is not a natural hypermedia due to the absence of hypermedia controls. The exchange of hypermedia is an explicit requirement for a system to be considered “RESTful.” It is a long story how we got here, using the term REST so incorrectly, and we will go into the details later in this book. But, for now, if you think REST implies JSON, please try to set that understanding aside while reading this book, and come to the concept with fresh eyes.
It is important to understand that, in his dissertation, Fielding was describing The World Wide Web as it existed in the late 1990s. The web, at that point, was simply web browsers exchanging hypermedia. That system, with its simple links and forms, was what Fielding was calling RESTful.
JSON APIs were a decade away from becoming a common tool in web development: REST was about hypermedia and the 1.0 version of the web.
The main reason I find this confusing is because the book has not yet defined "hypermedia" in concrete terms—are we talking about media as in images, videos, audio, fonts, and other resources that HTML uses and that servers can host and send to clients? Or is the "media" in "hypermedia" something entirely different?
The prior section reads:
What do you mean hypermedia systems?
Well, yes, HTML is a hypermedia. But there is more to the way the web works than just HTML: HTTP, the Hyper Text Transfer Protocol, is what transfers HTML from servers to clients, and there are many details and features associated with it: caching, various headers, response codes, and so forth.
And then, of course, there are hypermedia servers, which present hypermedia APIs (yes, APIs) to clients over the network.
And, finally, there is the all-important hypermedia client: a software client that understands how to render a hypermedia response intelligibly to a human, so that a human can interact with the remote system. The most widely known and used hypermedia clients are, of course, web browsers.
All of these feel like very loosely defined terms, with no concrete examples. The book says HTML is a hypermedia, but then it introduces the term hypermedia server and circularly defines it to be "a server that presents a hypermedia API." I walked away from this feeling like there's some prerequisite knowledge I don't yet have.
Second, I don't think this section does a good job of defining either Fielding's definition of the term "hypermedia" or the book's definition. My only takeaway from this section ends up being that "REST isn't just about JSON."
I think adding some examples would be helpful.
In 2.1 URL is defined as "Universal Resource Locator". I think this would be commonly seen by readers as a mistake, I recognise this is one old school meaning of URL but I'd suggest, either:
In the book there's both HyperText and Hypertext. It has this inconsistency in common with the Wikipedia page which uses Hypertext mainly with a few scattered mentions of HyperText.
It could make sense to use HyperText when talking about it in the context of HTTP and HTML (both Wikipedia and the HS book use HyperText outside of these contexts), but it should probably be standardised in the book to one or the other.
As great as htmx is, and as wonderful a collaboration this book is, I do not think you want to refer to HTMX in the callout section. See attached image; I will push a PR to cure.
(If I'm in the wrong, then apologies and urge you to use the conventional LowerCase usage of htmx.)
The example here doesn't work because:
key == 'L' seems to refer to shift + L rather than just the L buttonkey == 'l'This issue is based on a comment in my PR that I just closed.
There are:
I would have considered this a typo (British English instead of American English) but both are in the locality section in Chapter 10, with one referring to a URL:
https://htmx.org/essays/locality-of-behaviour/
I think if that's the spelling of the LoB principle then that's fine (Rule Britannia! 🇬🇧) but it brings some inconsistency to the book.
(Incidentally, the page at that URL also has quite a bit of inconsistency too but realise that's out of the scope of the issues for this repo).
I'm not suggestion all mentions of behavior should be changed to the British English spelling, but it's important to note that @adamstep points out in the PR conversation:
In the Hyperview chapters, behavior is a keyword of the XML syntax, so those should definitely not be changed! :)
There are over 500 mentions of htmx in the book (epic plugging!) and almost all of them come after the declaration of vested interest in Chapter 1:
One such hypermedia oriented library is https://htmx.org[htmx], created by the authors of this book
Except for the one in the introduction:
Next we will look at how we can use https://htmx.org[htmx], a hypermedia-oriented JavaScript library, to improve
Contact.app. By using htmx, we will be able to achieve a level of interactivity in our application that many developers
would expect requires a large, sophisticated front end library, such as React. Thanks to htmx, we will be able to do
this without abandoning hypermedia as a system architecture.
There are over 200 mentions of Hyperview and the declaration of vested interest in 12.2 comes before most of them:
Hyperview, a new hypermedia format we designed specifically for mobile apps ...
But not all.
Perhaps the Book Layout or elsewhere in the introduction could be the best place to declare these vested interests by the authors?
I could understand you not wanting readers to think the entire book is a sales pitch, in case they abandon it in the introduction, but I think by the time they get to the book layout section you've done a really good job of piquing interest.
Additionally, you could consider moving the "book layout" section to the end of the Introduction, after the "Hypermedia: A New Generation" so that you've really got them locked in before you declare interest. I'm not commenting on whether that re-order would still flow well, I'd need need to take a re-read to consider that.
When I read this
When you put hx-boost on a given element with the value true, it will “boost” all anchor and form elements within that element. “Boost”, here, means that htmx will convert all those anchors and forms from “normal” hypermedia controls into AJAX-powered hypermedia controls. Rather than issuing “normal” HTTP requests that replace the whole page, the links and forms will issue AJAX requests and then htmx will swap the response to these requests into the body tag. This makes navigation feel faster because the browser will not be re-interpreting the tags and so forth.
(emphasis mine)
It confused me because surely it's only the <body> tag that gets swapped into the body tag.
How to reproduce:
Expected result: going to https://hypermedia.systems/book/introduction/#_what_is_a_hypermedia_system
What actually happens: Nothing. We stay on the page.
Chromium Version 107.0.5304.87 (Official Build) (64-bit)
I really like your book and it would be great to read it on my e-reader (no Kindle).
Would it be possible to get a paid version (also Adobe DRM possible) on another platform than Amazon (Leanpub for example)?
Thanks a lot.
The first four quotes are:
I like all of the quotes, but the haters (SPA boys) might jump on the author quoting himself.
In What is a Hypermedia System it says:
Unfortunately, today, you probably associate the term "REST" with JSON APIs, since that is where the term is typically used in industry. This is a misapplied use of the term REST because JSON is not a hypermedia, which is an explicit requirement for a system to be considered "REST-ful."
(emphasis mine)
But earlier you refer to HAL (which comes in hal+json form) as a Hypermedia:
Not everyone abandoned hypermedia, of course. There have been heroic efforts to continue to advance hypermedia outside of HTML, efforts like HyTime, VoiceXML, and HAL.
I'd suggest that it's not the language (data serialisation / markup) that makes it not a hypermedia, but the absence of hypermedia controls, to quote earlier in the book:
what makes a hypermedia a hypermedia is the presence of hypermedia controls, that is, elements in the hypermedia that allow users to select non-linear actions within the hypermedia
There are 19 instances of bold text being used in the book, e.g, the first is in the introduction: "That":
It is important to understand that, in his dissertation, Fielding was describing The World Wide Web as it existed in the late 1990s. The Web, at that point, was simply web browsers exchanging hypermedia. That system, with its simple links and forms, was what Fielding was calling REST-ful
There are over 400 instances where italics are used, starting from the first paragraph:
This is a book about building applications using hypermedia systems. Hypermedia systems might seem like a strange phrase: how is hypermedia a system? Isn’t hypermedia just a way to link documents together?
There could be some reasoning as to why a small amount of text is emboldened and not italicised but it's not obvious to me. Unless there's a reason, I'd suggest switching it all to italics.
I know we're all about the server responding with HTML, but ...
https://hypermedia.systems/book/part/hyperview
https://hypermedia.systems/book/part/conclusion
In the book there is:
Let's standardise to "JavaScript", beware that all lowercase javascript is used in codeblocks and updating these instances could cause problems with rendering.
In Book Layout it says:
Finally, we will look at a completely different hypermedia system, Hyperview. Hyperview is a mobile hypermedia system ,related to, but distinct from The Web. It supports mobile specific features by providing not only a mobile specific hypermedia, but also a mobile hypermedia client, a network protocol and so on. It provides a full mobile hypermedia system for you to build your mobile application with, and, in doing so, makes it possible to build mobile Hypermedia-Driven Applications.
I read this: "It supports mobile specific features by providing not only a mobile specific hypermedia, but also a mobile hypermedia client, a network protocol and so on" to mean that Hyperview operated with a mobile-specific network protocol, other than HTTP but I don't believe that's the case.
Suggest adding a 's' to make for better style/flow:
On the Entire book in one page view the page's <title> appears as
<span class="allcaps big">Hypermedia Systems</span>—Hypermedia Systems
rather than just
Hypermedia Systems
This whole mechanism just seems to be wrong.
https://github.com/bigskysoftware/hypermedia-systems/blame/main/book/CH05_htmxPatterns.adoc#L954
For hx-target, does closest even find the last/final tr? The docs make it sound like it would find the whichever tr is closest to... whichever DOM element is currently selected, which could be the first, last or one in the middle? Wouldn't tbody be more appropriate? Though that wouldn't work for the infinite scroll revealed mechanism...
Either way, hx-swap of outerhtml seems inappropriate for appending. If sticking with tr, shouldn't it use afterend so as to append rather than replace? If switching to tbody, use beforeend?
The changes would need to be made in the infinite scroll section further down as well, along with all of the associated language.
If I'm just misunderstanding all of this, perhaps some text to explain why that's the case would be useful so as to prevent confusion in others?
Also, the logic for the next page button should probably account for the situation when there's only 10 contacts - you wouldn't want to show next page in that situation (or at least acknowledge this in the text and say we're ignoring for simplicity). Perhaps also add a mechanism to show the total number of contacts and which ones you're currently viewing? It's a common and useful thing to display and surely well within the capabilities of HTMX
Ch 6 starts with this search form
<form action="/contacts" method="get" class="tool-bar">
<label for="search">Search Term</label>
<input id="search" type="search" name="q" value="{{ request.args.get('q') or '' }}"/> (1)
<input type="submit" value="Search"/>
</form>It is the form initially created in Ch 3,
However in Ch4, it was changed significantly
<div id="main">
<form> <1>
<label for="search">Search Contacts:</label>
<input id="search" name="q" type="search" placeholder="Search Contacts"> <2>
<button hx-post="/contacts" hx-target="#main"> <3>
Search The Contacts
</button>
</form>
</div>and then changed again to this:
<div id="main">
<label for="search">Search Contacts:</label>
<input id="search" name="q" type="search" placeholder="Search Contacts">
<button hx-post="/contacts" hx-target="#main" hx-include="#search"> (1)
Search The Contacts
</button>
</div>Interestingly, this form does not use the value="{{ request.args.get('q') or '' }}"/> mechanism used in Ch 3 and 6.
I'm not sure which mechansims (a form with request.args.get vs no form, hx-post and hx-include) should be used where (ch 3 vs 4 vs 6), but there should probably be consistency between them.
Or, perhaps just add a comment in Ch 6 to say that we're ignoring the form-less search form developed in Ch 4 in order to have progressive enhancement/fallback to no-JS.
Still, the initial Ch 4 search mechanism should at least start with what was developed in Ch 3.
There's some inconsistency with "I" and "We" in the book.
In some sections, the author writes in a singular style ("I"), a few examples:
For the remaining templates I am going to omit the layout directive
I am the first to admit that conversations around REST and which HTTP Action is right for a given operation can become very tedious
Again, this is not a CSS book and I am not going to go deeply into the details of CSS transitions
And for others, it's a plural style ("We"), a few examples:
Well, we are glad you asked
We are going to talk more about the various ways that htmx enhances regular HTTP requests
We are not hypermedia puritans and encourage you to learn many different web technologies
This could confuse the reader, because "we" is also used extensively when working through exercises with the reader, e.g.:
we are going to create a simple contact management web application called Contacts.app
We are using the Jinja2 templating language
we are seeing the flexibility of hypermedia in action.
I can totally see how this happens with multiple contributors, I'd suggest:
(Note: I've only given a few examples for each, not an exhaustive list)
👋 I didn't see a contributing.md or equivalent file, but noticed that BulkDelete is using hx-delete and it feels like it should be using something else for maximum compatibility with different frameworks. I've been following along in go's standard library. Go doesn't read the payload body of a DELETE request. Maybe it's better to use hx-get or something else? I did verify that python/flask code included is able to read the payload body with a DELETE request. However, based on the way that the book is written, shouldn't it side on being more backend agnostic? Maybe a small blurb would suffice that the payload body might be dropped if you stray from the stack mentioned in
I'm interesting to translate the book into Indonesian language. Any guideline or directions I should follow?
THis is from Chapter 6
The solution to this problem is to use the HTTP Response Vary header and call out the htmx headers that you are using to determine what content you are returning. A full explanation of HTTP Caching is beyond the scope of this book, but the MDN article on the topic is quite good, and the htmx documentation discusses this issue as well.
There's no need to do a deep-dive into HTTP caching, but it would be great if you could add just a line or two about how to use Vary in this context. Likewise in the HTMX docs. Its not at all clear to me (even after consulting MDN) how to use it.
There seems to be an inconsistency in how GET, POST, PUT etc are referred to.
Sometimes it's HTTP Method:
The replacement content will be fetched with the
GETHTTP method
using different HTTP methods: a
GETto/contacts/<contact_id>/editwill return a form
When building a Hypermedia-Driven Application, you want, instead, to go "
with the grain" of The Web and use HTTP methods and response codes as they were designed to be used.
Other times it's HTTP Action:
From a technical perspective, all the updates are done with the
POSTHTTP action
HTML could be extended so that it could access these missing three HTTP actions,
PUT,PATCHandDELETE.
As usual, this is pretty straight forward: we simply create a new handler for the
DELETEHTTP Action
You guys are the hypermedia wizards, and I'm not claiming to be an expert here, but my understanding is that these are HTTP Methods (or more formally "HTTP Request Methods") but GET and POST correspond to an HTML form action?
This section confused me because it says:
The head tag, etc. are all ignored; and
continue to update the navigation bar.
I'm not sure the navigation bar terminology is clear, I'm guessing it means the URL address bar? I also wasn't sure how this deals with page titles – is the page title in the new page ignored too?
A second question you might have is: does the response need to be formatted specially to work with hx-boost? After all, the settings page would normally render an html tag, with a head tag and so forth. Do you need to handle “boosted” requests specially?
The answer is no: htmx is smart enough to pull out only the content of the body tag to swap in to the new page. The head tag, etc. are all ignored. This means you don’t need to do anything special on the server side to render templates that hx-boost can handle: just return the normal HTML for your page, and it should work fine.
Note that boosted links (and forms) will also continue to update the navigation bar and history, just like normal links, so users will be able to use the browser back button, will be able to copy and paste URLs (or “deep links”) and so on. Links will act pretty much like “normal”, they will just be faster.
This is a really technical nit, but since this is a technical book I thought I'd mention it.
A couple of times in the book there's an incorrect statement about CSS transitions being unavailable / impossible without JS:
Unfortunately, CSS transitions are not available in plain HTML
it isn’t possible to use CSS transitions without using JavaScript.
As you'll see from the following link (ironically hosted at JS Fiddle but without JS), this isn't correct:
https://jsfiddle.net/elliottinvent/hL9pa1mk/10/
You guys are doing a great job.
In the write useful link text section, it says:
Wherever possible, the text of a link should describe what the link points to without much context needed. Of course, you might need to alter it to fit a sentence structure, but you should avoid links that don’t give information other than “this is a link”.
Do Don’t For user records, [click here] [User records]
I think it's probably as simple as the "do" and "don't" examples being the wrong way around.
If not, the "do" example doesn't fit the guidance since link text "click here" does not "describe what the link points to without much context needed".
If the search result is larger than the pagination number, then scrolling will extend to the entire queryset, since the search field is not sent on infinite scroll request.
Some of the book has been written for print, with links written in a book style like this (ie the full URL in brackets):
... the most common approach today is to tie the DOM to a JavaScript model and then let an SPA framework like react (https://reactjs.org/) or vue (https://vuejs.org/) reactively update the DOM when a JavaScript model is updated ...
But other parts are written with hyperlinks which won't be suitable for print:
Next we will look at how we can use htmx, a hypermedia-oriented JavaScript library, to improve Contact.app.
I'd suggest standardising on the first style.
There is some inconsistency to how the book refers to this:
The early chapters talk about "The Web" and I think this is a good style showing respect, since the book is all about building on top of this hypermedia system but will defer to @codetalcott
Personally, I'd go with re-render.
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.