From 0c143015978ff496eb703b7542c48802c9b370e4 Mon Sep 17 00:00:00 2001 From: Bill Talcott Date: Mon, 6 Mar 2023 17:28:51 -0500 Subject: [PATCH] edits, hypermedia-driven, reformat Ch12 conclusion --- book/CH00_Introduction.adoc | 2 +- book/CH01_HypermediaAReintroduction.adoc | 2 +- book/CH06_htmxPatterns.adoc | 2 +- book/CH07_MorehtmxPatterns.adoc | 4 +- book/CH08_ADynamicArchiveUIWithhtmx.adoc | 8 ++-- book/CH12_HyperviewAMobileHypermedia.adoc | 44 +++++++++++-------- ...H13_BuildingAContactsAppWithHyperview.adoc | 6 +-- book/CH14_ExtendingTheHyperviewClient.adoc | 4 +- 8 files changed, 39 insertions(+), 33 deletions(-) diff --git a/book/CH00_Introduction.adoc b/book/CH00_Introduction.adoc index 9ea5fdd..d2a7445 100644 --- a/book/CH00_Introduction.adoc +++ b/book/CH00_Introduction.adoc @@ -63,7 +63,7 @@ Unfortunately, today, you probably associate the term "`REST`" with JSON APIs, s 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 currently think "`REST == JSON`", please try to set that understanding aside while reading 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 diff --git a/book/CH01_HypermediaAReintroduction.adoc b/book/CH01_HypermediaAReintroduction.adoc index 8cc755b..c91adc1 100644 --- a/book/CH01_HypermediaAReintroduction.adoc +++ b/book/CH01_HypermediaAReintroduction.adoc @@ -275,7 +275,7 @@ and are often perfectly happy with the results. These two tags give a tremendous amount of expressive power to HTML. -=== So What _Isn't_ Hypermedia? +=== So What Isn't Hypermedia? So links and forms are the two main hypermedia-based mechanisms for interacting with a server available in HTML. diff --git a/book/CH06_htmxPatterns.adoc b/book/CH06_htmxPatterns.adoc index cf810d9..9ae832b 100644 --- a/book/CH06_htmxPatterns.adoc +++ b/book/CH06_htmxPatterns.adoc @@ -221,7 +221,7 @@ into this category. We will note when a feature is progressive enhancement frie Ultimately, it is up to you, the developer, to decide if the trade-offs of progressive enhancement (a more basic UX, limited improvements over plain HTML) are worth the benefits for your application users. -=== Adding `hx-boost` to Contact.app +=== Adding "`hx-boost`" to Contact.app For the contact app we are building, we want this htmx "`boost`" behavior... well, everywhere. diff --git a/book/CH07_MorehtmxPatterns.adoc b/book/CH07_MorehtmxPatterns.adoc index f283e76..c46ce01 100644 --- a/book/CH07_MorehtmxPatterns.adoc +++ b/book/CH07_MorehtmxPatterns.adoc @@ -418,13 +418,13 @@ https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching[MDN article on the top documentation] discusses this issue as well. **** -=== Updating The Navigation Bar With `hx-push-url` +=== Updating the Navigation Bar With "`hx-push-url`" One shortcoming of our current Active Search implementation, when compared with the normal form submission, is that when you submit the form version it updates the navigation bar of the browser to include the search term. So, for example, if you search for "`joe`" in the search box, you will end up with a url that looks like this in your browser's nav bar: -.The Updated Location After A Form Search +.The updated location after a form search ---- https://example.com/contacts?q=joe ---- diff --git a/book/CH08_ADynamicArchiveUIWithhtmx.adoc b/book/CH08_ADynamicArchiveUIWithhtmx.adoc index 5b747ec..2810ddc 100644 --- a/book/CH08_ADynamicArchiveUIWithhtmx.adoc +++ b/book/CH08_ADynamicArchiveUIWithhtmx.adoc @@ -501,7 +501,7 @@ bar appears. When the progress bar reaches 100%, it disappears and a link to do can then click on that link and download their archive. A nice, polished user experience when compared with the common click-and-wait experience of many websites. -== Smoothing Things Out: Animations in htmx +== Smoothing Things Out: Animations in Htmx As nice as this UI is, there is one minor annoyance with it: as the progress bar updates it "`jumps`" from one position to the next. This looks jerky and is reminiscent of the feel of a full page refresh in web 1.0 style applications. It @@ -523,7 +523,7 @@ with their SPA counterparts: it is hard to use CSS transitions without using som This is unfortunate, but htmx rectifies this situation with its swapping model. Let's look at how. -=== The "`Settling`" Step in htmx +=== The "`Settling`" Step in Htmx When we discussed the htmx swap model in Chapter 5, we focused on the classes that htmx adds and removes, but we skipped over the idea of "`settling`". What is "`settling`" in htmx terms? Settling is the following process: when htmx is @@ -542,14 +542,14 @@ So, in our case, all we need to do is to add a stable ID to our `progress-bar` e on every update, the progress bar should smoothly move across the screen as it is updating, using the CSS transition defined in our style sheet: -.Smoothing Things Out +.Smoothing things out [source, html] ----
<1>
---- -<1> The progress bar div now has a stable id across requests +<1> The progress bar div now has a stable id across requests. So, despite all the complicated mechanics going on behind the scenes in htmx, all we have to do, as an htmx user, is add a stable `id` attribute to the element we want to animate. diff --git a/book/CH12_HyperviewAMobileHypermedia.adoc b/book/CH12_HyperviewAMobileHypermedia.adoc index f1c6116..bf1453a 100644 --- a/book/CH12_HyperviewAMobileHypermedia.adoc +++ b/book/CH12_HyperviewAMobileHypermedia.adoc @@ -21,7 +21,7 @@ It requires different trade-offs and design decisions. Nonetheless, the concepts of hypermedia, HATEOAS, and REST can be directly applied to build delightful mobile applications! -== The state of mobile app development +== The State of Mobile App Development Before we can discuss how to apply hypermedia to mobile platforms, we need to understand how native mobile apps are commonly built. I'm using the word "`native`" to refer to code written against an SDK provided by the phone's operating system (typically Android or iOS). This code is packaged into an executable binary, and uploaded & approved through app stores controlled by Google and Apple. @@ -74,7 +74,7 @@ There are two approaches employing hypermedia to build & ship native mobile apps - Hyperview, a new hypermedia format we designed specifically for mobile apps -=== Web views +=== Web Views The simplest way to use hypermedia architecture on mobile is by leveraging web technologies. Both Android and iOS SDKs provide "`web views`": chromeless web browsers that can be embedded in native apps. Tools like Apache Cordova make it easy to take the URL of a website, and spit out native iOS and Android apps based on web views. @@ -212,7 +212,7 @@ HXML responses remain pure, with UI and interactions represented in declarative **** -=== Which Hypermedia architecture should you use? +=== Which Hypermedia Architecture Should You Use? We've discussed two approaches for creating mobile apps using Hypermedia architecture: @@ -225,10 +225,10 @@ Both approaches solve the fundamental issues with traditional, SPA-like mobile a - The backend controls the full state of the app. - Our app's logic is all in one place. -- The app always runs the latest version, there's no API churn to worry about +- The app always runs the latest version, there's no API churn to worry about. So which approach should you use for a Hypermedia-driven mobile app? -Based on my experience building both types of apps, we strongly believe the Hyperview approach results in a better user experience. +Based on our experience building both types of apps, we strongly believe the Hyperview approach results in a better user experience. The web-view will always feel out-of-place on iOS and Android; there's just no good way to replicate the patterns of navigation and interaction that mobile users expect. Hyperview was created specifically to address the limitations of thick-client and web view approaches. After the initial investment to learn Hyperview, you'll get all of the benefits of the Hypermedia architecture, without the downsides of a degraded user experience. @@ -1028,7 +1028,7 @@ This UI allows sharing URLs and messages from one app to another app. Hyperview has a `share` action to support this interaction. It involves a custom namespace, and share-specific attributes. -.System Share action +.System share action [source,xml] ---- ` of `` elements. The last item in the list includes a behavior with `trigger="visible"`. The `append` action will fetch the next page of items and append them to the list. -===== refresh +===== Refresh This trigger captures a "`pull to refresh`" action on `` and `` items. This interaction is associated with fetching up-to-date content from the backend. Thus, it's typically paired with an update or reload action to show the latest data on the screen. @@ -1184,12 +1184,12 @@ Thus, it's typically paired with an update or reload action to show the latest d ---- -<1> When the view is pulled down to refresh, reload the screen +<1> When the view is pulled down to refresh, reload the screen. Note that adding a behavior with `trigger="refresh"` to a `` or `` will add the pull-to-refresh interaction to the element, including showing a spinner as the element is pulled down. -===== `focus`, `blur`, and `change` +===== Focus, blur, and change These triggers are related to interactions with input elements. Thus, they will only trigger behaviors attached to elements like ``. `focus` and `blur` will trigger when the user focuses and blurs the input element, respectively. @@ -1242,13 +1242,9 @@ These concepts can be mixed together too. It's not unusual for a production Hyperview app to contain several behaviors, some triggering together and others triggering on different interactions. Using multiple behaviors with custom actions keeps HXML declarative, without sacrificing functionality. +=== Quick Sketch: Elements of Hyperview +We've covered a lot of new material, so here is a quick summary of the key aspects of Hyperview: -== Summary - -- Mobile app platforms push developers towards a thick-client architecture. But apps that use a thick client suffer from the same problems as SPAs on the web. -- Using the hypermedia architecture for mobile apps solves the problems with thick-client apps. -- HTML web views are one way to implement the hypermedia architecture for mobile apps. But HTML is not designed for mobile UIs, so this approach does not deliver a great user experience. -- Hyperview is an alternative approach to build mobile apps using the hypermedia architecture. Hyperview introduces a new format called HXML. It also provides an open-source mobile thin-client to render HXML. - HXML looks similar to HTML, but it uses elements that correspond to mobile UIs, like ``, `
`, `` and more. - HXML also includes input elements that implement common patterns in mobile apps, such as ``, ``, and ``. - New UI components can be added to HXML using namespaced elements. The Hyperview client can be easily extended to render these new elements. @@ -1257,4 +1253,14 @@ Using multiple behaviors with custom actions keeps HXML declarative, without sac - Updates to screens in Hyperview are defined using behaviors with update actions, such as `replace` and `append`. - System interactions in Hyperview are defined using behaviors with system actions, such as `alert` and `share`. - New actions can be added to HXML using namespaced attributes. The Hyperview client can be easily extended to interpret the new actions. -- The extensibility of HXML and the Hyperview client make it easy for developers to define custom elements and behaviors. Developers can evolve Hyperview to suit their apps' requirements, while fully embracing the hypermedia architecture. + + +== Summary + +Mobile app platforms push developers towards a thick-client architecture. But apps that use a thick client suffer from the same problems as SPAs on the web. Using the hypermedia architecture for mobile apps can solve these problems. + +One way to implement the hypermedia architecture for mobile apps is with HTML web views. But HTML is not designed for mobile UIs, so this approach does not deliver a great user experience. + +Hyperview offers an alternative approach using the hypermedia architecture, based on a new format called HXML. It also provides an open-source mobile thin-client to render HXML. Again, HXML looks similar to HTML, but it uses elements and patterns that correspond to mobile UIs. + +The extensibility of HXML and the Hyperview client make it easy to define custom elements and behaviors. Developers can evolve Hyperview to suit their apps' requirements, while fully embracing the hypermedia architecture. diff --git a/book/CH13_BuildingAContactsAppWithHyperview.adoc b/book/CH13_BuildingAContactsAppWithHyperview.adoc index c20f03e..451adac 100644 --- a/book/CH13_BuildingAContactsAppWithHyperview.adoc +++ b/book/CH13_BuildingAContactsAppWithHyperview.adoc @@ -65,7 +65,7 @@ Select an option based on which developer SDK you have installed. (The screenshots in this chapter will be taken from the iOS simulator.) With any luck, you will see the Expo mobile app installed in the simulator. The mobile app will automatically launch and show a screen saying "`Network request failed.`" -That's because by default, this app is configured to make a request to `http://0.0.0.0:8085/index.xml`, but our backend is listening on port 5000. +That's because by default, this app is configured to make a request to \http://0.0.0.0:8085/index.xml, but our backend is listening on port 5000. To fix this, we can make a simple configuration change in the `demo/src/constants.js` file: [source,js] @@ -77,7 +77,7 @@ export const ENTRY_POINT_URL = 'http://0.0.0.0:5000/'; <2> <2> Setting the URL to point to our contacts app We're not up and running yet. -With our Hyperview client now pointing to the right endpoint, we see a different error, a "`ParseError`". +With our Hyperview client now pointing to the right endpoint, we see a different error, a "`ParseError.`" That's because the backend is responding to requests with HTML content, but the Hyperview client expects an XML response (specifically, HXML). So it's time to turn our attention to our Flask backend. We will go through the Flask views, and replace the HTML templates with HXML templates. @@ -100,7 +100,7 @@ Every other action the user can take will be declared in the HXML of that first This minimal configuration is one elegant aspect of the Hypermedia-driven architecture! Of course, you may want to write more on-device code to support more features in your mobile app. -We will demonstrate how to do that later in this chapter, in the section called "`Extending the Client`". +We will demonstrate how to do that later in this chapter, in the section called "`Extending the Client.`" **** diff --git a/book/CH14_ExtendingTheHyperviewClient.adoc b/book/CH14_ExtendingTheHyperviewClient.adoc index dbd72a2..0b260f7 100644 --- a/book/CH14_ExtendingTheHyperviewClient.adoc +++ b/book/CH14_ExtendingTheHyperviewClient.adoc @@ -294,7 +294,7 @@ export default class HyperviewScreen extends PureComponent { // ... omitted for brevity } ---- -<1> Import the show-toast action +<1> Import the show-toast action. <2> Pass the action to the `Hyperview` component, as a prop called `behaviors`. All that's left to do is trigger the `show-toast` action from our HXML. @@ -369,7 +369,7 @@ By using a custom action, the toast UI remains visible even while the screens ch image::screenshot_hyperview_toast.png["Small gray box shows at top of screen: 'Deleted Contact!'"] -== Swipe gesture on Contacts +== Swipe Gesture on Contacts To add communication capabilities and the toast UI, we extended the client with custom behavior actions. But the Hyperview client can also be extended with custom UI components that render on the screen. Custom components are implemented as React Native components.