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

rework hyperview HTML asides to be Hypermedia asides

Browse Source
This commit is contained in:
Carson Gross 2023-07-15 16:30:27 -06:00
parent b86f769f36
commit e17f6a2a75
3 changed files with 55 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
book/CH11_HyperviewAMobileHypermedia.adoc
View File

@ -1333,26 +1333,46 @@ In the next two chapters we'll show how by turning the Contact.app web applicati
:sectnums!:
[.html-note]
== HTML Notes: Maximize Your Server-Side Strengths
== Hypermedia Notes: Maximize Your Server-Side Strengths
A big advantage of the hypermedia-driven approach is that it makes the server-side environment far more important when building your web application. Rather than simply producing JSON, your back end is an integral component in the user experience of your web application.
In the HyperView sections of the book, since we aren't using HTML, we are going to make broader observations on hypermedia
rather than offer HTML-specific advice and thoughts.
Because of this, it makes sense to look deeply into the functionality available there. Many older web frameworks have incredibly deep functionality available around producing HTML. Features like server-side caching can make the difference between an incredibly snappy web application and a sluggish user experience.
A big advantage of the hypermedia-driven approach is that it makes the server-side environment far more important when
building your web application. Rather than simply producing JSON, your back end is an integral component in the user
experience of your hypermedia application.
Because of this, it makes sense to look deeply into the functionality available there. Many older web frameworks, for example,
have incredibly deep functionality available around producing HTML. Features like server-side caching can make the
difference between an incredibly snappy web application and a sluggish user experience.
Take time to learn all the tools available to you.
A good rule of thumb is to shoot to have responses in your application take less than 100ms to complete, and mature server side frameworks have tools to help make this happen.
A good rule of thumb is to shoot to have server responses in your hypermedia-driven application take less than 100ms to
complete, and mature server-side frameworks have tools to help make this happen.
Server-side environments often have extremely mature mechanisms for factoring (or organizing) your code properly. The Model/View/Controller pattern is well-developed in most environments, and tools like modules, packages, etc. provide an excellent way to organize your code.
Server-side environments often have extremely mature mechanisms for factoring (or organizing) your code properly. The
Model/View/Controller pattern is well-developed in most environments, and tools like modules, packages, etc. provide an
excellent way to organize your code.
Whereas SPAs user interfaces are typically organized via components, hypermedia-driven applications are typically organized via template inclusion, where the server-side templates are broken up according to the HTML-rendering needs of the application, and then included in one another as needed. This tends to lead to fewer, chunkier files than you would find in a component-based application.
Whereas today's SPA and mobile user interfaces are typically organized via components, hypermedia-driven applications
are typically organized via template inclusion, where the server-side templates are broken up according to the
hypermedia-rendering needs of the application, and then included in one another as needed. This tends to lead to fewer,
chunkier files than you would find in a component-based application.
Another technology to look for are Template Fragments, which allow you to render only part of a template file. This can reduce even further the number of template files required for your server-side application.
Another technology to look for are Template Fragments, which allow you to render only part of a template file. This can
reduce even further the number of template files required for your server-side application.
A related tip is to take advantage of direct access to the data store. When an application is built using the SPA approach, the data store typically lives behind a JSON API. This level of indirection often prevents front end developers from being able to take full advantage of the tools available in the data store. GraphQL can help address this issue, but comes with security-related issues that do not appear to be well understood by many developers.
A related tip is to take advantage of direct access to the data store. When an application is built using a thick client
approach, the data store typically lives behind a data API (e.g. JSON). This level of indirection often prevents front
end developers from being able to take full advantage of the tools available in the data store. GraphQL, for example,
can help address this issue, but comes with security-related issues that do not appear to be well understood by many developers.
When you produce your HTML on the server side, on the other hand, the developer creating that HTML can have full access to the data store and take advantage of, for example, joins and aggregation functions in SQL stores.
When you produce your hypermedia on the server side, on the other hand, the developer creating that hypermedia can have
full access to the data store and take advantage of, for example, joins and aggregation functions in SQL stores.
This puts far more expressive power directly in the hands of the developer producing the HTML. Because your hypermedia API can be structured around your UI needs, you can tune each endpoint to issue as few data store requests as possible.
This puts far more expressive power directly in the hands of the developer producing the final hypermedia. Because your
hypermedia API can be structured around your UI needs, you can tune each endpoint to issue as few data store requests as possible.
A good rule of thumb is that every request should shoot to have three or fewer data-store accesses.
A good rule of thumb is that every request to your server should shoot to have three or fewer data-store accesses. If
you follow this rule of thumb, your hypermedia-driven application should be extremely snappy.

18
book/CH12_BuildingAContactsAppWithHyperview.adoc
View File

@ -1336,13 +1336,19 @@ In the next chapter we'll implement custom behaviors and UI elements to finish o
:sectnums!:
[.html-note]
== HTML Notes: API Endpoints
== Hypermedia Notes: API Endpoints
Unlike a JSON API, the hypermedia API you produce for your hypermedia-driven application should feature endpoints specialized for your particular application’s UI needs.
Unlike a JSON API, the hypermedia API you produce for your hypermedia-driven application should feature endpoints
specialized for your particular application’s UI needs.
Because hypermedia APIs are not designed to be consumed by general-purpose clients you can set aside the pressure to keep them generalized and produce the content specifically needed for your application.
Your endpoints should be optimized to support your particular applications UI/UX needs, not for a general-purpose data-access model for your domain model.
Because hypermedia APIs are not designed to be consumed by general-purpose clients you can set aside the pressure to keep
them generalized and produce the content specifically needed for your application. Your endpoints should be optimized to
support your particular applications UI/UX needs, not for a general-purpose data-access model for your domain model.
A related tip is that, when you have a hypermedia-based API, you can aggressively refactor your API in a way that is heavily discouraged when writing JSON API-based SPAs. Because hypermedia-based applications use Hypermedia As The Engine Of Application State, you are able and, in fact, encouraged, to change the shape of them as your application developers and as use cases change.
A related tip is that, when you have a hypermedia-based API, you can aggressively refactor your API in a way that is
heavily discouraged when writing JSON API-based SPAs or mobile clients. Because hypermedia-based applications use
Hypermedia As The Engine Of Application State, you are able and, in fact, encouraged, to change the shape of them as
your application developers and as use cases change.
A great strength of the hypermedia approach is that you can completely rework your API to adapt to new needs over time without needing to version the API or even document it.
A great strength of the hypermedia approach is that you can completely rework your API to adapt to new needs over
time without needing to version the API or even document it. Take advantage of it!

28
book/CH13_ExtendingTheHyperviewClient.adoc
View File

@ -737,23 +737,19 @@ Yes, there is a story for Hypermedia-Driven Applications on mobile.
:sectnums!:
[.html-note]
== HTML Notes: Good-Enough UX and Islands of Interactivity
== Hypermedia Notes: Good-Enough UX and Islands of Interactivity
A problem many SPA developers face when coming to the HDA approach is that they look at their current SPA application and imagine implementing it exactly using hypermedia. While htmx and other hypermedia-oriented libraries significantly close the interactivity gap between hypermedia-based applications and SPAs, that gap still exists.
A problem many SPA and native mobile developers face when coming to the HDA approach is that they look at their current
application and imagine implementing it exactly using hypermedia. While htmx and HyperView significantly improve the
user experience available via the hypermedia-driven approach, there are still times when it won't be easy to pull of
a particular user experience.
As we saw in Chapter Two, Roy Fielding noted this tradeoff with respect to the web’s RESTful network architecture, where "information is transferred in a
standardized form rather than one which is specific to an application's needs."
As we saw in Chapter Two, Roy Fielding noted this tradeoff with respect to the web’s RESTful network architecture,
where "information is transferred in a standardized form rather than one which is specific to an application's needs."
Accepting a slightly less efficient and interactive solution to a particular UX can save you a tremendous amount of complexity when building a web application.
Accepting a slightly less efficient and interactive solution to a particular UX can save you a tremendous amount of
complexity when building your applications.
Do not let the perfect be the enemy of the good.
Still, there may come a point in your application where the hypermedia approach, on its own, just doesn’t cut it.
A good example of this is re-ordering a list of things. This can be done in “`pure`” hypermedia by clicking up and down arrows or having order # drop-downs next to items.
But this experience stinks compared to what people are used to: drag-and-drop.
In cases like this, it is perfectly fine to use a front-end heavy approach, such as SortableJS, as an “`Island of Interactivity.`”
This is an excellent way to encapsulate richer UX within an HDA.
Do not let the perfect be the enemy of the good. Many advantages are to be gained by accepting a slightly less
sophisticated user experience in some cases, and tools like htmx and HyperView make that compromise much more palatable
when they are used properly.