From 953ce54b7e8210748e8f3e2eb357808cd418d450 Mon Sep 17 00:00:00 2001 From: Carson Gross Date: Tue, 7 Nov 2023 10:02:07 -0700 Subject: [PATCH 01/13] update sha --- www/content/docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/www/content/docs.md b/www/content/docs.md index 9ab4f795..ad81f038 100644 --- a/www/content/docs.md +++ b/www/content/docs.md @@ -114,7 +114,7 @@ The fastest way to get going with htmx is to load it via a CDN. You can simply a and get going: ```html - + ``` While the CDN approach is extremely simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). From 62cabf3308bb130f002901e0b0dd70932fc532e1 Mon Sep 17 00:00:00 2001 From: Carson Gross Date: Wed, 8 Nov 2023 13:32:41 -0700 Subject: [PATCH 02/13] add scaling essay --- www/content/essays/_index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/www/content/essays/_index.md b/www/content/essays/_index.md index 7fa7b556..067bbd8b 100644 --- a/www/content/essays/_index.md +++ b/www/content/essays/_index.md @@ -22,6 +22,7 @@ page_template = "essay.html" * [A Response To "Have SPAs Ruined The Web"](@/essays/a-response-to-rich-harris.md) * [When To Use Hypermedia?](@/essays/when-to-use-hypermedia.md) * [The API Churn/Security Trade-off](https://intercoolerjs.org/2016/02/17/api-churn-vs-security.html) +* [Does Hypermedia Scale?](@/essays/does-hypermedia-scale.md) * [SPA Alternative](@/essays/spa-alternative.md) ### Building Hypermedia Applications From 2e5f813c91747312dad49d594ba9c5683c2e3591 Mon Sep 17 00:00:00 2001 From: Alexander Petros Date: Wed, 8 Nov 2023 16:33:26 -0500 Subject: [PATCH 03/13] Replace keyup with input event (#1952) `keyup` only works with a keyboard, and ignores pasting with a right click or programmatically updating the value with JS. `input` is a better event for detecting any "inputs to the input". Co-authored-by: Sam Eaton --- www/content/examples/active-search.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/www/content/examples/active-search.md b/www/content/examples/active-search.md index 1f48acd1..242a4c21 100644 --- a/www/content/examples/active-search.md +++ b/www/content/examples/active-search.md @@ -17,7 +17,7 @@ We start with a search input and an empty table: @@ -34,16 +34,16 @@ We start with a search input and an empty table: ``` -The input issues a `POST` to `/search` on the `keyup` event and sets the body of the table to be the resulting content. +The input issues a `POST` to `/search` on the [`input`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) event and sets the body of the table to be the resulting content. Note that the `keyup` event could be used as well, but would not fire if the user pasted text with their mouse (or any other non-keyboard method). We add the `delay:500ms` modifier to the trigger to delay sending the query until the user stops typing. Additionally, we add the `changed` modifier to the trigger to ensure we don't send new queries when the user doesn't change the -value of the input (e.g. they hit an arrow key). +value of the input (e.g. they hit an arrow key, or pasted the same value). Since we use a `search` type input we will get an `x` in the input field to clear the input. To make this trigger a new `POST` we have to specify another trigger. We specify another trigger by using a comma to separate them. The `search` trigger will be run when the field is cleared but it also makes it possible to override -the 500 ms delay on `keyup` by just pressing enter. +the 500 ms `input` event delay by just pressing enter. Finally, we show an indicator when the search is in flight with the `hx-indicator` attribute. @@ -78,7 +78,7 @@ Search Contacts From 4f75a3812306c17a7a89561132624113aad76bd4 Mon Sep 17 00:00:00 2001 From: Alexander Petros Date: Wed, 8 Nov 2023 18:34:49 -0500 Subject: [PATCH 04/13] Fix link on scaling essay (#1983) --- www/content/essays/does-hypermedia-scale.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/www/content/essays/does-hypermedia-scale.md b/www/content/essays/does-hypermedia-scale.md index de737db2..304db83c 100644 --- a/www/content/essays/does-hypermedia-scale.md +++ b/www/content/essays/does-hypermedia-scale.md @@ -12,7 +12,7 @@ One objection that we sometimes hear to htmx and hypermedia is some variation of > Well, it might work well for something small, but it won't scale. It is always dangerous to provoke us with essay-fodder and so lets dig into this claim a bit and see if we can -shed some light on whether [Hypermedia-Driven Applications]((@/essays/hypermedia-driven-applications.md)) (HDAs) can scale. +shed some light on whether [Hypermedia-Driven Applications](@/essays/hypermedia-driven-applications.md) (HDAs) can scale. ## Scaling From 798a32b1e8c8d8986a00253c54898a6d001a33e1 Mon Sep 17 00:00:00 2001 From: Cristi Date: Thu, 9 Nov 2023 23:20:47 +0200 Subject: [PATCH 05/13] documentation update php symfony (#1978) * docs: php (symfony sdk) * docs: twig support for fragments --------- Co-authored-by: Cristian Toma --- www/content/essays/template-fragments.md | 1 + www/content/server-examples.md | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/www/content/essays/template-fragments.md b/www/content/essays/template-fragments.md index bdb23f8e..9699edb3 100644 --- a/www/content/essays/template-fragments.md +++ b/www/content/essays/template-fragments.md @@ -143,6 +143,7 @@ Here are some known implementations of the fragment concept: * PHP * [Latte](https://latte.nette.org/en/template-inheritance#toc-blocks) - Use the 3rd parameter to only render 1 block from the template - `$Latte_Engine->render('path/to/template.latte', [ 'foo' => 'bar' ], 'content');` * [Laravel Blade](https://laravel.com/docs/10.x/blade#rendering-blade-fragments) - includes built-in support for template fragments as of v9.x + * [Twig](https://twig.symfony.com/doc/3.x/api.html#rendering-templates) - `$template->renderBlock('block_name', ['the' => 'variables', 'go' => 'here']);` * Python * [Django Render Block Extension](https://pypi.org/project/django-render-block/) - see [example code for htmx](https://github.com/spookylukey/django-htmx-patterns/blob/master/inline_partials.rst) * [jinja2-fragments package](https://github.com/sponsfreixes/jinja2-fragments) diff --git a/www/content/server-examples.md b/www/content/server-examples.md index 21da2c3e..cbeb41c9 100644 --- a/www/content/server-examples.md +++ b/www/content/server-examples.md @@ -138,6 +138,10 @@ These examples may make it a bit easier to get started using htmx with your plat - +### Symfony + +- + ## Elixir ### Phoenix From 9c87f40bd4b97d213f53921388ddcca629da31b2 Mon Sep 17 00:00:00 2001 From: Vincent Date: Fri, 10 Nov 2023 20:23:28 +0100 Subject: [PATCH 06/13] Homogenize configuration docs (#1973) * Homogenize configuration docs * Remove source change --- www/content/api.md | 17 ++++++++++++++--- www/content/docs.md | 11 ++++++++--- 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/www/content/api.md b/www/content/api.md index e19d6ab8..7dad8ce5 100644 --- a/www/content/api.md +++ b/www/content/api.md @@ -104,9 +104,10 @@ Note that using a [meta tag](@/docs.md#config) is the preferred mechanism for se ##### Properties * `attributesToSettle:["class", "style", "width", "height"]` - array of strings: the attributes to settle during the settling phase +* `refreshOnHistoryMiss:false` - boolean: if set to `true` htmx will issue a full page refresh on history misses rather than use an AJAX request * `defaultSettleDelay:20` - int: the default delay between completing the content swap and settling attributes * `defaultSwapDelay:0` - int: the default delay between receiving a response from the server and doing the swap -* `defaultSwapStyle:'innerHtml'` - string: the default swap style to use if [`hx-swap`](@/attributes/hx-swap.md) is omitted +* `defaultSwapStyle:'innerHTML'` - string: the default swap style to use if [`hx-swap`](@/attributes/hx-swap.md) is omitted * `historyCacheSize:10` - int: the number of pages to keep in `localStorage` for history support * `historyEnabled:true` - boolean: whether or not to use history * `includeIndicatorStyles:true` - boolean: if true, htmx will inject a small amount of CSS into the page to make indicators invisible unless the `htmx-indicator` class is present @@ -117,10 +118,20 @@ Note that using a [meta tag](@/docs.md#config) is the preferred mechanism for se * `swappingClass:'htmx-swapping'` - string: the class to place on target elements when htmx is in the swapping phase * `allowEval:true` - boolean: allows the use of eval-like functionality in htmx, to enable `hx-vars`, trigger conditions & script tag evaluation. Can be set to `false` for CSP compatibility. * `allowScriptTags:true` - boolean: allows script tags to be evaluated in new content +* `inlineScriptNonce:''` - string: the [nonce](https://developer.mozilla.org/docs/Web/HTML/Global_attributes/nonce) to add to inline scripts * `useTemplateFragments:false` - boolean: use HTML template tags for parsing content from the server. This allows you to use Out of Band content when returning things like table rows, but it is *not* IE11 compatible. * `withCredentials:false` - boolean: allow cross-site Access-Control requests using credentials such as cookies, authorization headers or TLS client certificates -* `wsReconnectDelay:full-jitter` - string/function: the default implementation of `getWebSocketReconnectDelay` for reconnecting after unexpected connection loss by the event code `Abnormal Closure`, `Service Restart` or `Try Again Later` -* `scrollBehavior:smooth` - string: the behavior for a boosted link on page transitions. The allowed values are `auto` and `smooth`. Smooth will smoothscroll to the top of the page while auto will behave like a vanilla link. +* `timeout:0` - int: the number of milliseconds a request can take before automatically being terminated +* `wsReconnectDelay:'full-jitter'` - string/function: the default implementation of `getWebSocketReconnectDelay` for reconnecting after unexpected connection loss by the event code `Abnormal Closure`, `Service Restart` or `Try Again Later` +* `wsBinaryType:'blob'` - string: the [the type of binary data](https://developer.mozilla.org/docs/Web/API/WebSocket/binaryType) being received over the WebSocket connection +* `disableSelector:"[hx-disable], [data-hx-disable]"` - array of strings: htmx will not process elements with this attribute on it or a parent +* `scrollBehavior:'smooth'` - string: the behavior for a boosted link on page transitions. The allowed values are `auto` and `smooth`. Smooth will smoothscroll to the top of the page while auto will behave like a vanilla link. +* `defaultFocusScroll:false` - boolean: if the focused element should be scrolled into view, can be overridden using the [focus-scroll](@/attributes/hx-swap.md#focus-scroll) swap modifier +* `getCacheBusterParam:false` - boolean: if set to true htmx will include a cache-busting parameter in `GET` requests to avoid caching partial responses by the browser +* `globalViewTransitions:false` - boolean: if set to `true`, htmx will use the [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) API when swapping in new content. +* `methodsThatUseUrlParams:["get"]` - array of strings: htmx will format requests with these methods by encoding their parameters in the URL, not the request body +* `selfRequestsOnly:false` - boolean: if set to `true` will only allow AJAX requests to the same domain as the current document +* `ignoreTitle:false` - boolean: if set to `true` htmx will not update the title of the document when a `title` tag is found in new content * `scrollIntoViewOnBoost:true` - boolean: whether or not the target of a boosted element is scrolled into the viewport. If `hx-target` is omitted on a boosted element, the target defaults to `body`, causing the page to scroll to the top. ##### Example diff --git a/www/content/docs.md b/www/content/docs.md index ad81f038..f9616dc6 100644 --- a/www/content/docs.md +++ b/www/content/docs.md @@ -1635,16 +1635,21 @@ listed below: | `htmx.config.allowEval` | defaults to `true`, can be used to disable htmx's use of eval for certain features (e.g. trigger filters) | | `htmx.config.allowScriptTags` | defaults to `true`, determines if htmx will process script tags found in new content | | `htmx.config.inlineScriptNonce` | defaults to `''`, meaning that no nonce will be added to inline scripts | +| `htmx.config.attributesToSettle` | defaults to `["class", "style", "width", "height"]`, the attributes to settle during the settling phase | | `htmx.config.useTemplateFragments` | defaults to `false`, HTML template tags for parsing content from the server (not IE11 compatible!) | | `htmx.config.wsReconnectDelay` | defaults to `full-jitter` | -| `htmx.config.disableSelector` | defaults to `[disable-htmx], [data-disable-htmx]`, htmx will not process elements with this attribute on it or a parent | -| `htmx.config.timeout` | defaults to 0 in milliseconds | +| `htmx.config.wsBinaryType` | defaults to `blob`, the [the type of binary data](https://developer.mozilla.org/docs/Web/API/WebSocket/binaryType) being received over the WebSocket connection | +| `htmx.config.disableSelector` | defaults to `[hx-disable], [data-hx-disable]`, htmx will not process elements with this attribute on it or a parent | +| `htmx.config.withCredentials` | defaults to `false`, allow cross-site Access-Control requests using credentials such as cookies, authorization headers or TLS client certificates | +| `htmx.config.timeout` | defaults to 0, the number of milliseconds a request can take before automatically being terminated | +| `htmx.config.scrollBehavior` | defaults to 'smooth', the behavior for a boosted link on page transitions. The allowed values are `auto` and `smooth`. Smooth will smoothscroll to the top of the page while auto will behave like a vanilla link. | | `htmx.config.defaultFocusScroll` | if the focused element should be scrolled into view, defaults to false and can be overridden using the [focus-scroll](@/attributes/hx-swap.md#focus-scroll) swap modifier. | | `htmx.config.getCacheBusterParam` | defaults to false, if set to true htmx will include a cache-busting parameter in `GET` requests to avoid caching partial responses by the browser | | `htmx.config.globalViewTransitions` | if set to `true`, htmx will use the [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) API when swapping in new content. | -| `htmx.config.methodsThatUseUrlParams` | defaults to `["get"]`, htmx will format requests with this method by encoding their parameters in the URL, not the request body | +| `htmx.config.methodsThatUseUrlParams` | defaults to `["get"]`, htmx will format requests with these methods by encoding their parameters in the URL, not the request body | | `htmx.config.selfRequestsOnly` | defaults to `false`, if set to `true` will only allow AJAX requests to the same domain as the current document | | `htmx.config.ignoreTitle` | defaults to `false`, if set to `true` htmx will not update the title of the document when a `title` tag is found in new content | +| `htmx.config.scrollIntoViewOnBoost` | defaults to `true`, whether or not the target of a boosted element is scrolled into the viewport. If `hx-target` is omitted on a boosted element, the target defaults to `body`, causing the page to scroll to the top. | From f716383716d86f3309d36d0fd42b8bedf10ca3f7 Mon Sep 17 00:00:00 2001 From: Joe Taber Date: Fri, 10 Nov 2023 20:31:29 -0600 Subject: [PATCH 07/13] Add configuration options list to reference docs (#1927) Could not figure out how to import directly from docs.md with zola. --- www/content/docs.md | 72 ++++++++-------------------------------- www/content/reference.md | 49 +++++++++++++++++++++++++++ 2 files changed, 63 insertions(+), 58 deletions(-) diff --git a/www/content/docs.md b/www/content/docs.md index f9616dc6..0f3c658b 100644 --- a/www/content/docs.md +++ b/www/content/docs.md @@ -944,7 +944,7 @@ For more on the `HX-Trigger` headers, see [`HX-Trigger` Response Headers](@/head Submitting a form via htmx has the benefit of no longer needing the [Post/Redirect/Get Pattern](https://en.wikipedia.org/wiki/Post/Redirect/Get). After successfully processing a POST request on the server, you don't need to return a [HTTP 302 (Redirect)](https://en.wikipedia.org/wiki/HTTP_302). You can directly return the new HTML fragment. - + ### Request Order of Operations {#request-operations} The order of operations in a htmx request are: @@ -1498,7 +1498,7 @@ to generate a different `ETag` for each content. ## Security -htmx allows you to define logic directly in your DOM. This has a number of advantages, the largest being +htmx allows you to define logic directly in your DOM. This has a number of advantages, the largest being [Locality of Behavior](@/essays/locality-of-behaviour.md), which makes your system easier to understand and maintain. @@ -1508,8 +1508,8 @@ ends. ### Rule 1: Escape All User Content -The first rule of HTML-based web development has always been: *do not trust input from the user*. You should escape all -3rd party, untrusted content that is injected into your site. This is to prevent, among other issues, +The first rule of HTML-based web development has always been: *do not trust input from the user*. You should escape all +3rd party, untrusted content that is injected into your site. This is to prevent, among other issues, [XSS attacks](https://en.wikipedia.org/wiki/Cross-site_scripting). There is extensive documentation on XSS and how to prevent it on the excellent [OWASP Website](https://owasp.org/www-community/attacks/xss/), @@ -1524,21 +1524,21 @@ mechanism in their templating language. This can be done for good reasons, but from a 3rd party then it _must_ be scrubbed, including removing attributes starting with `hx-` and `data-hx`, as well as inline `