an `hx-swap` option to target attributes rather than content #2946

j-n-f · 2024-10-06T21:50:55Z

j-n-f
Oct 6, 2024

tl;dr - I'd like a version of hx-swap/hx-swap-oob that targets a node's attributes without having to change/update its contents.

edit: A working prototype in extension form is here

I'm developing techniques to make gracefully degrading apps without having to create multiple templates.

Imagine a page which has a left and right panel:

.----------------.----------------------------------------.
|                |                                        |
|                |                                        |
|    Listing     |                Details                 |
|                |                                        |
|                |                                        |
|________________|________________________________________|

If we assume the happy path, the markup (ignoring CSS) might look something like:

<!-- I'll explain this below -->
<div id="js"></div>
<!-- what you would expect -->
<div id="item-browser">
    <ul id="item-list">
        <li><a href="/item/1" hx-get="/item/1" hx-target="#item-details">Item 1</a></li>
        <li><a href="/item/2" hx-get="/item/2" hx-target="#item-details">Item 1</a></li>
        <li><a href="/item/2" hx-get="/item/3" hx-target="#item-details">Item 1</a></li>
        <!-- so on -->
    </ul>
    <div id="item-details">
    </div>
</div>

The user clicks on a link in the left pane:

JS Enabled: The item details will appear in the right-side pane (hx-get + hx-target)
JS Disabled: The browser will navigate to the detail page (href)

There's only one downside: the page looks kind of goofy to a non-JS user (there's a panel that doesn't do anything). It would be ideal if the pane for item details didn't display until it was reasonably certain that the user had JS enabled.

On the backend side, we can look for the HX-Request header, and any time we see it we can send back a fragment after the usual content:

<!-- usual content of the response -->
<div id="js" class="confirmed" hx-swap-oob="true"></div>

The #js div can be combined with CSS to control content on the rest of the page:

#item-details {
    /* Initial assumption: we don't know if the user has JS */
    display: none;
}

/* assume #js is an earlier sibling of elements where we want to consider JS support */
#js.confirmed + #item-browser #item-details {
    display: unset;
}

Now it's possible to give a good experience to both JS/non-JS users without having to create two copies of the template. The fragment that does the OOB update can be part of a middleware in your application so individual route handlers don't have to care about JS support.

The only possible improvement from here would be to avoid having to use the sibling selector.

Imagine if that same OOB fragment could do:

<body class="js" hx-swap-oob="attributesAdd"></body>

HTMX would take all the attributes in the fragment, and add them to the target (probably merging in this case, but you could imagine attributesReplace as well).

Now your CSS selectors could look like:

#item-details {
    /* Initial assumption: we don't know if the user has JS */
    display: none;
}

/* We have less work to do because we were able to directly change
 * the attributes on an existing element without having to worry
 * about its content. */
.js #item-details {
    display: unset;
}

To recap on the benefits of this approach:

Write your templates once, individual templates don't have to care about general concerns (graceful degredation) in their specific context (i.e. DRY)
Achieve graceful degradation by having href for non-JS, and hx-get for JS
Templates can display differently based on attributes of containing elements (i.e. leverage CSS selectors)
No need for complicated client-side tests; if HX-Request comes in, we can be almost 100% certain that we can provide the upgraded experience
No need to re-render content which is already present (e.g. in the example above, without the ability to swap attributes we'd have to re-render the entire page just to update the <body> tag); i.e. save bandwidth and maybe DOM update time.

The ability to swap attributes (either with hx-swap or hx-swap-oob) probably has more applications I haven't thought of.

The only question I have now is: could this cause any problems?

j-n-f · 2024-10-07T02:07:32Z

j-n-f
Oct 7, 2024
Author

Here's what I've worked out (to try implementing as an extension):

(function() {
    var api;

    htmx.defineExtension('my-ext', {
        init: function(apiRef) {
            api = apiRef;
        },
        onEvent: function(name, evt) {
            //console.debug("onEvent", {name, evt});
        },
        transformResponse: function(text, xhr, elt) {
            let fragment = api.makeFragment(text);
            console.debug("frag", fragment);

            // TODO: remove elements that I don't want handled by the existing OOB logic
            // TODO: turn the remaining fragment back into text and return

            return text;
        },
        isInlineSwap: function(swapStyle) {
            //console.debug("isInlineSwap", {swapStyle});
            return false;
        },
        handleSwap: function(swapStyle, target, fragment, settleInfo) {
            // OOB swaps don't happen here
            //console.debug("handleSwap", {swapStyle, target, fragment, settleInfo});
            return false;
        },
        encodeParameters: function(xhr, parameters, elt) {
            //console.debug("encodeParameters", {xhr, parameters, elt});
            return null;
        }
    })
})()

I can pick out fragments with [hx-swap-oob="attributesOnly"] (or similar) so they don't cause errors later on (anything with an "invalid" value in hx-swap-oob will be missing evt.detail.fragment in the htmx:oobBeforeSwap event; this means that we won't have the information necessary to handle it when that event fires later on; this might be a bug?)
- maybe I can look at how htmx.js queues up these OOB swaps and send out my own version of the event with the fragment included again. I don't think this will work because the event may get sent too early.
I can't pick up a <body> fragment (makeFragment() doesn't pick it up); this means that my particular goal would have to be done with a wrapper <div> or something
I still have to work out how/when to make the changes I want to make, as it's clear that any kind of swapping has a lifecycle that has to be followed (adding/removing classes as things are modified and become settled, etc.)

I'll keep trying and see if I can work around these issues.

0 replies

j-n-f · 2024-10-07T04:11:52Z

j-n-f
Oct 7, 2024
Author

All right, got it working.

(function() {
    var api;

    htmx.defineExtension('oob-attribute-swap', {
        init: function(apiRef) {
            api = apiRef;
        },
        onEvent: function(name, evt) {
            //console.debug("onEvent", {name, evt});
            return true;
        },
        transformResponse: function(text, xhr, elt) {
            let fragment = api.makeFragment(text);
            console.debug("frag", fragment);

            // N.B. You will need to get your backend to echo this back (until I can find a way
            //      around the issue with boosted responses. I don't see any issue as someone
            //      looking at the network tab can see that it was set on request.
            if (xhr.getResponseHeader("hx-boosted")) {
                // Running the code below with a boosted response causes issues. The conversion from
                // text to fragment and back yields a different result somehow.
                return text;
            }

            // Take out all fragments where an attribute update is requested
            let taken = fragment.querySelectorAll("[hx-swap-oob=attributes]");
            // Collect all the fragments that we aren't going to touch
            let preserved = fragment.querySelectorAll(":not([hx-swap-oob=attributes])");

            // For each node where we're swapping attributes...
            Array.from(taken).forEach(node => {
                // Take the existing node in the document...
                let target = document.querySelector(`#${node.getAttribute('id')}`);
                // Copy all the attributes from the OOB fragment to the target node
                [...node.attributes].map(({name, value}) => {
                    target.setAttribute(name, value);
                })
            })

            let preservedHtml = Array.from(preserved).map((n) => n.outerHTML).join("");

            // Return HTML that we didn't do attribute updates for
            return preservedHtml;
        },
        isInlineSwap: function(swapStyle) {
            //console.debug("isInlineSwap", {swapStyle});
            return false;
        },
        handleSwap: function(swapStyle, target, fragment, settleInfo) {
            // OOB swaps don't happen here
            //console.debug("handleSwap", {swapStyle, target, fragment, settleInfo});
            return false;
        },
        encodeParameters: function(xhr, parameters, elt) {
            //console.debug("encodeParameters", {xhr, parameters, elt});
            return null;
        }
    })
})()

add code to your page
add hx-ext="oob-attribute-swap" to an element where you want this functionality to exist
send a fragment with a matching id and hx-swap-oob="attributes"
note that attributes have been updated but innerHTML of the node is unchanged

That's all I need for my purposes, but maybe someone can think of a better way to do it. I'm not sure what the consequences of doing this so hackishly would be.

edit: found a small issue when running this on boosted responses, so I added a check which skips the logic if the response isn't a partial.

0 replies

j-n-f · 2024-10-07T05:16:47Z

j-n-f
Oct 7, 2024
Author

I see the issue. The use of querySelectorAll is basically flattening the tree. This is breaking other things so I'm going to have to fix it.

0 replies

j-n-f · 2024-10-07T05:27:47Z

j-n-f
Oct 7, 2024
Author

Fixed it. Now it works on boosted responses without the header passing trick as well.

(function() {
    var api;

    htmx.defineExtension('oob-attribute-swap', {
        init: function(apiRef) {
            api = apiRef;
        },
        onEvent: function(name, evt) {
            //console.debug("onEvent", {name, evt});
            return true;
        },
        transformResponse: function(text, xhr, elt) {
            let fragment = api.makeFragment(text);

            // Take out items which:
            //
            // 1. Are direct descendants of the root
            // 2. Which have [hx-swap-oob="attributes"]
            let taken = Array.from(fragment.children).filter(node => {
                let swap_attr = node.attributes.getNamedItem("hx-swap-oob");
                if (swap_attr && swap_attr.value === "attributes") {
                    return true;
                }
                return false;
            });

            // Preserve and pass on everything else.
            let preserved = Array.from(fragment.children).filter(node => {
                let swap_attr = node.attributes.getNamedItem("hx-swap-oob");
                if (swap_attr === null) {
                    return true;
                } else if (swap_attr && swap_attr.value !== "attributes") {
                    return true;
                }
                return false;
            });

            // For each node where we're swapping attributes...
            Array.from(taken).forEach(node => {
                // Take the existing node in the document...
                let target = document.querySelector(`#${node.getAttribute('id')}`);
                // Copy all the attributes from the OOB fragment to the target node
                [...node.attributes].map(({name, value}) => {
                    target.setAttribute(name, value);
                })
            });

            let preservedHtml = Array.from(preserved).map((n) => n.outerHTML).join("");

            // Return HTML that we didn't do attribute updates for
            return preservedHtml;
        },
        isInlineSwap: function(swapStyle) {
            //console.debug("isInlineSwap", {swapStyle});
            return false;
        },
        handleSwap: function(swapStyle, target, fragment, settleInfo) {
            // OOB swaps don't happen here
            //console.debug("handleSwap", {swapStyle, target, fragment, settleInfo});
            return false;
        },
        encodeParameters: function(xhr, parameters, elt) {
            //console.debug("encodeParameters", {xhr, parameters, elt});
            return null;
        }
    })
})()

1 reply

Telroshan Oct 7, 2024
Collaborator

Hey, feel free to publish it as a repository of your own and list it in the community extensions!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

an `hx-swap` option to target attributes rather than content #2946

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 4 comments 1 reply

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

Select a reply

an hx-swap option to target attributes rather than content #2946

j-n-f Oct 6, 2024

Replies: 4 comments · 1 reply

j-n-f Oct 7, 2024 Author

j-n-f Oct 7, 2024 Author

j-n-f Oct 7, 2024 Author

j-n-f Oct 7, 2024 Author

Telroshan Oct 7, 2024 Collaborator

an `hx-swap` option to target attributes rather than content #2946

j-n-f
Oct 6, 2024

Replies: 4 comments 1 reply

j-n-f
Oct 7, 2024
Author

j-n-f
Oct 7, 2024
Author

j-n-f
Oct 7, 2024
Author

j-n-f
Oct 7, 2024
Author

Telroshan Oct 7, 2024
Collaborator