From 563ce5d042b0671572c38d6998be7a73a8b1600b Mon Sep 17 00:00:00 2001 From: Vincent Date: Mon, 6 Nov 2023 22:53:34 +0100 Subject: [PATCH] List extended selectors + caveats in hx-include doc (#1522) List extended selectors + caveats in hx-include doc --- www/content/attributes/hx-include.md | 31 ++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/www/content/attributes/hx-include.md b/www/content/attributes/hx-include.md index 2f00b459f..5001b8ea8 100644 --- a/www/content/attributes/hx-include.md +++ b/www/content/attributes/hx-include.md @@ -2,8 +2,19 @@ title = "hx-include" +++ -The `hx-include` attribute allows you to include additional element values in an AJAX request. The value of - this attribute is a CSS query selector of the element or elements to include in the query. +The `hx-include` attribute allows you to include additional element values in an AJAX request. The value of this +attribute can be: + +* A CSS query selector of the elements to include. +* `this` which will include the descendants of the element. +* `closest ` which will find the [closest](https://developer.mozilla.org/docs/Web/API/Element/closest) + ancestor element or itself, that matches the given CSS selector + (e.g. `closest tr` will target the closest table row to the element). +* `find ` which will find the first child descendant element that matches the given CSS selector. +* `next ` which will scan the DOM forward for the first element that matches the given CSS selector. + (e.g. `next .error` will target the closest following sibling element with `error` class) +* `previous ` which will scan the DOM backwards for the first element that matches the given CSS selector. + (e.g `previous .error` will target the closest previous sibling with `error` class) Here is an example that includes a separate input value: @@ -24,3 +35,19 @@ Note that if you include a non-input element, all input elements enclosed in tha ## Notes * `hx-include` is inherited and can be placed on a parent element +* While `hx-include` is inherited, it is evaluated from the element triggering the request. It is easy to get confused + when working with the extended selectors such as `find` and `closest`. + ```html +
+ + Enter email: +
+ ``` + In the above example, when clicking on the button, the `find input` selector is resolved from the button itself, which + does not return any element here, since the button doesn't have any `input` child, thus in this case, raises an error. +* A standard CSS selector resolves + to [document.querySelectorAll](https://developer.mozilla.org/docs/Web/API/Document/querySelectorAll) and will include + multiple elements, while the extended selectors such as `find` or `next` only return a single element at most to + include \ No newline at end of file