itsscb/htmx
1
0
Fork 0
mirror of https://github.com/bigskysoftware/htmx.git synced 2025-09-28 13:31:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into dev

Browse Source
This commit is contained in:
carson 2021-07-06 09:37:32 -06:00
commit 419c7c9d5a
3 changed files with 24 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
www/essays/locality-of-behaviour.md
View File

@ -10,7 +10,7 @@ title: </> htmx - high power tools for html
### The LoB Principle:
> The behaviour of a code unit should be as obvious as possible by looking only at that unit of code
> The behaviour of a unit of code should be as obvious as possible by looking only at that unit of code
### Discussion
@ -38,18 +38,26 @@ and the second in [jQuery](https://jquery.com/):
<button id="d1">Click Me</button>
```
In the former, the behaviour of the `div` element is obvious on inspection, satisfying the LoB principle.
In the former, the behaviour of the `button` element is obvious on inspection, satisfying the LoB principle.
In the latter, the behaviour of the `div` element is spread out amongst multiple files. It is difficult to know
exactly what the div does without a total knowledge of the code base.
In the latter, the behaviour of the `button` element is spread out amongst multiple files. It is difficult to know
exactly what the button does without a total knowledge of the code base. This "spooky action at a distance" is a source
of maintenance issues and stands in the way of developers understanding of the code base.
The htmx example demonstrates good Locality of Behavior, while the jQuery example has poor Locality of Behavior.
#### Surfacing Behaviour vs. Inlining Implementation
A common conflation is surfacing behaviour with inlining implementation of that behaviour. These are separate concepts
and, while inlining the implementation of a behaviour isn't *always* incorrect, it may *often* be incorrect.
A common objection to Locality of Behavior is that it is inlining implementation details within a code unit, making the
code unit less abstract and more brittle. However, it is important to make the distinction between inlining the
*implementation* of some behavior and inlining the invocation (or declaration) of some behavior.
Consider functions in most programming languages: there is a distinction between the declaration of function and its
use at call sites. A good function abstracts away its implementation details, but is also invoked in an obvious manner,
without any spooky action at a distance.
Increasing the obviousness of the behaviour of an element is, ceteris paribus, a good thing, but it falls to both end-developers
and especially framework developers to make LoB as easy as possible.
and especially framework developers to make LoB both as easy and as conceptually clean as possible.
#### Conflict With Other Development Principles
@ -58,7 +66,7 @@ are:
* [DRY - Don't Repeat Yourself](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)
Software developers typically strive to avoid redundancy in their code or data. This as come to be called "Staying DRY",
Software developers typically strive to avoid redundancy in their code or data. This has come to be called "Staying DRY",
i.e. Don't Repeat Yourself. Like other software design principles this, on its own, is a good thing. htmx, for example,
allows you to place many attributes on parent elements in a DOM and avoid repeating these attributes on children. This is a
violation of LoB, in favor of DRY, and such tradeoffs need to be made judiciously by developers.
@ -72,12 +80,12 @@ are:
* [SoC - Separation Of Concerns](https://en.wikipedia.org/wiki/Separation_of_concerns)
Separation of concerns a design principle for separating a computer program into distinct sections such that each
section addresses a separate concern. A canonical example of this is CSS vs. Javascript. Again, on its own and
in isolation this may, indeed, be a good thing. Inlining styles has become more prevalent lately, but there are
still strong arguments in favor of SoC in this regard.
section addresses a separate concern. A canonical example of this is splitting HTML, CSS, and Javascript. Again, on its own and
in isolation this may, indeed, be a good thing. Inlining styles [has become more prevalent lately](https://tailwindcss.com/),
but there are still strong arguments in favor of SoC in this regard.
Note that SoC is, however, in conflict with LoB. By tweaking a CSS file the look and, to an extent, behaviour of an
element can change dramatically, and it is not obvious where this dramatic change came from. Tools help to an extent
element can change dramatically, and it is not obvious where this dramatic change came from. Tools can help to an extent
here, but there is still "spooky action at a distance" going on.
Again, this isn't to condemn SoC wholesale, just to say that there are subjective tradeoffs that must be made when
@ -86,7 +94,7 @@ are:
#### Conclusion
LoB is a software design principle that can help make a code bases more humane and maintainable. It must be traded
Locality of Behavior is a subjective software design principle that can help make a code base more humane and maintainable. It must be traded
off against other design principles and be considered in terms of the limitations of the system a code unit is
written in, but, as much as is it is practical, adherence to this principle will increase your developer productivity
and well-being.
written in, but, as much as is it is practical, adherence to this principle will increase your software maintainability,
quality and sustainability.

1
www/extensions.md
View File

@ -63,7 +63,6 @@ against `htmx` in each distribution
| [`debug`](/extensions/debug) | an extension for debugging of a particular element using htmx
| [`path-deps`](/extensions/path-deps) | an extension for expressing path-based dependencies [similar to intercoolerjs](http://intercoolerjs.org/docs.html#dependencies)
| [`class-tools`](/extensions/class-tools) | an extension for manipulating timed addition and removal of classes on HTML elements
| [`rails-method`](/extensions/rails-method) | includes the `_method` parameter in requests for rails compatibility
| [`remove-me`](/extensions/remove-me) | allows you to remove an element after a given amount of time
| [`include-vals`](/extensions/include-vals) | allows you to include additional values in a request
| [`ajax-header`](/extensions/ajax-header) | includes the commonly-used `X-Requested-With` header that identifies ajax requests in many backend frameworks

2
www/server-examples.md
View File

@ -7,7 +7,7 @@ title: </> htmx - Server-Side Examples
There are many examples of integrating htmx with server-side frameworks available on GitHub. Generally speaking,
most server-side frameworks are already pretty well set up to integrate with htmx - after all, most of them were
rendering HTML long before before JSON became popular.
rendering HTML long before JSON became popular.
Different frameworks and platforms may offer alternative systems for installing htmx - for example, in the Java / JVM
ecosystem, [WebJars](https://www.webjars.org) allows the use of npm packages with popular Java build tools such as