sharpetronics/hypermedia-systems
1
0
Fork 0
mirror of https://github.com/bigskysoftware/hypermedia-systems.git synced 2025-11-28 00:04:56 -05:00
Code Issues Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/main'

Browse Source
This commit is contained in:
Carson Gross 2023-06-05 14:39:23 -06:00
commit aa69aaafb2
5 changed files with 23 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
book/CH00_Introduction.adoc
View File

@ -71,7 +71,7 @@ late 1990s. The web, at that point, was simply web browsers exchanging hypermed
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.
version of the web.
== Hypermedia-Driven Applications
@ -107,7 +107,7 @@ The book is broken into three parts:
application that many developers would expect to require a large, sophisticated front end library, such as React.
Thanks to htmx, we will be able to do this using hypermedia as our system architecture.
* Finally, we will look at a completely different hypermedia system, Hyperview. Hyperview is a _mobile_ hypermedia system, related to, but distinct from the web and created by one of the authors of this book -- Adam Stepinski. 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.
* Finally, we will look at a completely different hypermedia system, Hyperview. Hyperview is a _mobile_ hypermedia system, related to, but distinct from the web and created by one of the authors of this book -- Adam Stepinski. It supports _mobile specific_ features by providing not only a mobile specific hypermedia, but also a mobile hypermedia client. These novel components, combined with any HTTP server, provide a full _mobile hypermedia system_ for you to build your mobile application. In doing so, makes it possible to build mobile Hypermedia-Driven Applications.
Note that each section is _somewhat_ independent of the others. If you already know hypermedia in-depth and how basic Web
1.0 applications function, you may want to skip ahead to the second section on htmx and how to build modern web applications
@ -153,26 +153,17 @@ ____
****
At the end of each chapter you will find tips and best practices for writing HTML well.
It's very easy (and sometimes acceptable) to produce mediocre HTML that, within a purview limited to one particular application, works -- this seems to be enough for most websites.
But our websites, like men, are not islands.
That is, they are not applications of a _platform_,
but constituents of a _system_.
It's easy (and sometimes acceptable) to produce mediocre HTML that, for one particular application, works well enough. But websites are not islands.
That is, they are not applications of a _platform_, but constituents of a _system_. In a systems view of the web, the purpose of writing HTML is not just to develop a particular application, but also to play along with other members of the web.
In a systems view of the web, the purpose of writing HTML is not just to develop a particular application, but also to play along with other members of the Web.
Thankfully for us hypermedia advocates, a few components, most prominently search engines and assistive technologies, have enough sway to keep people caring about HTML.
Less fortunately, lack of awareness around hypermedia means that these components are seen as annoyances to get out of the way, demons to appease, or worse, legacy leftovers to ignore.
After all, web development is so much easier without all this Web stuff.
After all, web development is so much easier without all this web stuff.
So why resist the tide? Why shouldn't we discard hypermedia and rewrite the web into the application platform it can clearly be?
That's what the rest of this book will try to answer, in a practical, non theory-addled way.
And at the ends of chapters, these HTML Notes will connect the concepts of hypermedia we discuss and the code samples we present to day-to-day web development.
So why resist the tide? Why shouldn't we discard hypermedia and rewrite the web into the application platform it can clearly be? That's what the rest of this book will try to answer, in a practical, non theory-addled way. And at the ends of chapters, these HTML Notes will connect the concepts of hypermedia we discuss and the code samples we present to day-to-day web development.
The executive summary:
Well-written HTML is easier to read and debug, more accessible to all, ranked higher by search engines (not out of bias, but because they have an easier time scraping it).
The executive summary: well-written HTML is easier to read and debug, more accessible to all, and ranked higher by search engines (not out of bias, but because they have an easier time scraping it). We can't fix every problem by writing good HTML. The mantra that HTML is "accessible by default" is misleading, and shunning other technologies like JavaScript is misguided. Ultimately, testing is the best indicator of quality.
An important caveat:
The mantra that HTML is "accessible by default" is misleading and shunning other technologies like JavaScript is misguided.
Doing everything with "pure", "semantic" HTML is not a panacea, and testing is the ultimate indicator of quality over spec adherence.
But writing good, spec-compliant HTML lets browsers do a bunch of work for you. Furthermore, even when they don't, it makes it easier to write scripts that do. Fewer issues will be found during testing and you can release faster. When issues do come up, you can often fix them more easily by refactoring HTML as opposed to heaping JavaScript and ARIA attributes over everything.
****
****

4
book/CH02_ComponentsOfAHypermediaSystem.adoc
View File

@ -815,8 +815,8 @@ special nature of HTML, hypermedia and the web!
****
The best-known kind of messy HTML is `<div>` soup.
Advances in CSS and JavaScript technology have mostly obviated the need to add extraneous "wrapper" elements to out documents.
However, while the number of elements can fall, the quality of usage does not necessatily improve.
Advances in CSS and JavaScript technology have mostly obviated the need to add extraneous "wrapper" elements to our documents.
However, while the number of elements can fall, the quality of usage does not necessarily improve.
When developers fall back on the generic `<div>` and `<span>` elements instead of more meaningful tags,
we either degrade the quality of our websites or create more work for ourselves -- probably both.

2
book/CH08_TricksOfThehtmxMasters.adoc
View File

@ -808,7 +808,7 @@ Test manually.
Test automatically.
Test with screenreaders, test with a keyboard, test on different browsers and hardware, and run linters (while coding and/or in CI).
One common problem is with the use of `display: none;` in CSS. The issue is that it is not purely cosmetic -- it also removes elements from the accessibility tree and keyboard focus. This is often desirable to present the same content to visual and aural interfaces. If you want to hide an element visually without hiding it from assistive technology (e.g. the element contains information that is communicated through styling), you can use this utility class:
One common problem is with the use of `display: none;` in CSS. The issue is that it is not purely cosmetic -- it also removes elements from the accessibility tree and keyboard focus. This is sometimes done to present the same content to visual and aural interfaces. If you want to hide an element visually without hiding it from assistive technology (e.g. the element contains information that is communicated through styling), you can use this utility class:
[source,css]
----

6
book/CH09_ScriptingInAHypermediaApplication.adoc
View File

@ -747,12 +747,10 @@ To get a flavor of AlpineJS, let's look at how to implement our counter example
For the counter, the only state we need to keep track of is the current number, so let's declare a JavaScript object
with one property, `count`, in an `x-data` attribute on the div for our counter:
// TODO wt (please restore, used in scripting): check: removed class="counter" to avoid confusion
.Counter with Alpine, line 1
[source,html]
----
<div x-data="{ count: 0 }">
<div class="counter" x-data="{ count: 0 }">
----
This defines our state, that is, the data we are going to be using to drive dynamic updates to the DOM. With the state
@ -1386,7 +1384,7 @@ The keyboard interactions can be error-prone too.
It's not impossible, not even that hard, to make your own tab set implementation.
However, it's difficult to trust that a new implementation will work for all users in all environments, since most of us have limited resporces for testing.
*Stick with established libraries* for UI interactions. If a use case requires a bespoke solution, *test exhaustively* for keyboard interaction and accessibility.
_Stick with established libraries_ for UI interactions. If a use case requires a bespoke solution, _test exhaustively_ for keyboard interaction and accessibility.
Also consider: Does the information need to be presented as tabs?
Sometimes the answer is yes, but if not, a sequence of details and disclosures fulfills a very similar purpose.

20
book/CH13_ExtendingTheHyperviewClient.adoc
View File

@ -49,7 +49,7 @@ So let's define two new actions, "`open-phone`" and "`open-email`".
.Phone and Email actions
[source,xml]
----
<view xmlns:comms="https://manning.com/hyperview/communications"> <1>
<view xmlns:comms="https://hypermedia.systems/hyperview/communications"> <1>
<text>
<behavior action="open-phone" comms:phone-number="555-555-5555" /> <2>
Call
@ -92,7 +92,7 @@ Next, we'll create a new file, `phone.js`, that will implement the code associat
----
import { phonecall } from 'react-native-communications'; <1>
const namespace = "https://manning.com/hyperview/communications";
const namespace = "https://hypermedia.systems/hyperview/communications";
export default {
action: "open-phone", <2>
@ -165,7 +165,7 @@ In fact, let's do that now by updating the `show.xml` template in our Flask app:
<view style="contact-section">
<behavior <1>
xmlns:comms="https://manning.com/hyperview/communications"
xmlns:comms="https://hypermedia.systems/hyperview/communications"
trigger="press"
action="open-phone" <2>
comms:phone-number="{{contact.phone}}" <3>
@ -176,7 +176,7 @@ In fact, let's do that now by updating the `show.xml` template in our Flask app:
<view style="contact-section">
<behavior <4>
xmlns:comms="https://manning.com/hyperview/communications"
xmlns:comms="https://hypermedia.systems/hyperview/communications"
trigger="press"
action="open-email"
comms:email-address="{{contact.email}}"
@ -248,7 +248,7 @@ Now, we can write the code to implement the toast UI as a custom action.
----
import Toast from 'react-native-root-toast'; <1>
const namespace = "https://manning.com/hyperview/toast";
const namespace = "https://hypermedia.systems/hyperview/toast";
export default {
action: "show-toast", <2>
@ -312,7 +312,7 @@ Since the actual behaviors will be the same in both templates, let's create a sh
----
{% for message in get_flashed_messages() %}
<behavior <1>
xmlns:toast="https://manning.com/hyperview/toast"
xmlns:toast="https://hypermedia.systems/hyperview/toast"
trigger="load" <2>
action="show-toast" <3>
toast:message="{{ message }}" <4>
@ -407,7 +407,7 @@ For the swipeable row, we need a way to represent the entire component, the main
[source,xml]
----
<swipe:row xmlns:swipe="https://manning.com/hyperview/swipeable"> <1>
<swipe:row xmlns:swipe="https://hypermedia.systems/hyperview/swipeable"> <1>
<swipe:main> <2>
<!-- main content shown here -->
</swipe:main>
@ -461,7 +461,7 @@ import React, { PureComponent } from 'react';
import Hyperview from 'hyperview';
import Swipeable from 'react-native-swipeable';
const NAMESPACE_URI = 'https://manning.com/hyperview/swipeable';
const NAMESPACE_URI = 'https://hypermedia.systems/hyperview/swipeable';
export default class SwipeableRow extends PureComponent { <1>
static namespaceURI = NAMESPACE_URI; <2>
@ -585,7 +585,7 @@ So let's start by adding `<row>` and `<main>` as parent elements.
[source,xml]
----
<item key="{{ contact.id }}">
<swipe:row xmlns:swipe="https://manning.com/hyperview/swipeable"> <1>
<swipe:row xmlns:swipe="https://hypermedia.systems/hyperview/swipeable"> <1>
<swipe:main> <2>
<view style="contact-item"> <3>
<behavior trigger="press" action="push" href="/contacts/{{ contact.id }}" /> <1>
@ -613,7 +613,7 @@ Let's add two buttons to the swipeable row.
[source,xml]
----
<item key="{{ contact.id }}">
<swipe:row xmlns:swipe="https://manning.com/hyperview/swipeable"> <1>
<swipe:row xmlns:swipe="https://hypermedia.systems/hyperview/swipeable"> <1>
<swipe:main>
<!-- omitted for brevity -->
</swipe:main>