response-targets extension with documentation, exposed 3 functions in…

… internal API (bigskysoftware#1436)

* findThisElement, getClosestAttributeValue, querySelectorExt exposed in internal API

* Added response-targets extension.

* Extra check for empty element in response-targets.js

* Added test/ext/response-targets.js

* Linked response-targets.md

* Added htmx.config.{responseTargetPrefersExisting, responseTargetPrefersRetargetHeader} configuration options

* Typo fixed (not impacting logic)

src/ext/response-targets.js

@@ -0,0 +1,110 @@
+(function(){
+
+    /** @type {import("../htmx").HtmxInternalApi} */
+    var api;
+
+    const targetAttrPrefix = 'hx-target-';
+    const targetAttrMinLen = targetAttrPrefix.length - 1;
+
+    /**
+     * @param {HTMLElement} elt
+     * @param {number} respCode
+     * @returns {HTMLElement | null}
+     */
+    function getRespCodeTarget(elt, respCode) {
+        if (!elt || !respCode) return null;
+
+        var targetAttr = targetAttrPrefix + respCode;
+        var targetStr  = api.getClosestAttributeValue(elt, targetAttr);
+
+        if (targetStr) {
+            if (targetStr === "this") {
+                return api.findThisElement(elt, targetAttr);
+            } else {
+                return api.querySelectorExt(elt, targetStr);
+            }
+        } else {
+            for (let l = targetAttr.length - 1; l > targetAttrMinLen; l--) {
+                targetAttr = targetAttr.substring(0, l) + '*';
+                targetStr  = api.getClosestAttributeValue(elt, targetAttr);
+                if (targetStr) break;
+            }
+        }
+
+        if (targetStr) {
+            if (targetStr === "this") {
+                return api.findThisElement(elt, targetAttr);
+            } else {
+                return api.querySelectorExt(elt, targetStr);
+            }
+        } else {
+            return null;
+        }
+    }
+
+    /** @param {Event} evt */
+    function handleErrorFlag(evt) {
+        if (evt.detail.isError) {
+            if (htmx.config.responseTargetUnsetsError) {
+                evt.detail.isError = false;
+            }
+        } else if (htmx.config.responseTargetSetsError) {
+            evt.detail.isError = true;
+        }
+    }
+
+    htmx.defineExtension('response-targets', {
+
+        /** @param {import("../htmx").HtmxInternalApi} apiRef */
+        init: function (apiRef) {
+            api = apiRef;
+
+            if (htmx.config.responseTargetUnsetsError === undefined) {
+                htmx.config.responseTargetUnsetsError = true;
+            }
+            if (htmx.config.responseTargetSetsError === undefined) {
+                htmx.config.responseTargetSetsError = false;
+            }
+            if (htmx.config.responseTargetPrefersExisting === undefined) {
+                htmx.config.responseTargetPrefersExisting = false;
+            }
+            if (htmx.config.responseTargetPrefersRetargetHeader === undefined) {
+                htmx.config.responseTargetPrefersRetargetHeader = true;
+            }
+        },
+
+        /**
+         * @param {string} name
+         * @param {Event} evt
+         */
+        onEvent: function (name, evt) {
+            if (name === "htmx:beforeSwap"    &&
+                evt.detail.xhr                &&
+                evt.detail.xhr.status !== 200) {
+                if (evt.detail.target) {
+                    if (htmx.config.responseTargetPrefersExisting) {
+                        evt.detail.shoudSwap = true;
+                        handleErrorFlag(evt);
+                        return true;
+                    }
+                    if (htmx.config.responseTargetPrefersRetargetHeader &&
+                        evt.detail.xhr.getAllResponseHeaders().match(/HX-Retarget:/i)) {
+                        evt.detail.shouldSwap = true;
+                        handleErrorFlag(evt);
+                        return true;
+                    }
+                }
+                if (!evt.detail.requestConfig) {
+                    return true;
+                }
+                var target = getRespCodeTarget(evt.detail.requestConfig.elt, evt.detail.xhr.status);
+                if (target) {
+                    handleErrorFlag(evt);
+                    evt.detail.shouldSwap = true;
+                    evt.detail.target = target;
+                }
+                return true;
+            }
+        }
+    });
+})();

src/htmx.js

@@ -90,9 +90,11 @@ return (function () {
             addTriggerHandler: addTriggerHandler,
             bodyContains: bodyContains,
             canAccessLocalStorage: canAccessLocalStorage,
+            findThisElement: findThisElement,
             filterValues: filterValues,
             hasAttribute: hasAttribute,
             getAttributeValue: getAttributeValue,
+            getClosestAttributeValue: getClosestAttributeValue,
             getClosestMatch: getClosestMatch,
             getExpressionVars: getExpressionVars,
             getHeaders: getHeaders,
@@ -105,6 +107,7 @@ return (function () {
             mergeObjects: mergeObjects,
             makeSettleInfo: makeSettleInfo,
             oobSwap: oobSwap,
+            querySelectorExt: querySelectorExt,
             selectAndSwap: selectAndSwap,
             settleImmediately: settleImmediately,
             shouldCancel: shouldCancel,

test/ext/response-targets.js

@@ -0,0 +1,224 @@
+describe("response-targets extension", function() {
+    beforeEach(function() {
+        this.server = sinon.fakeServer.create();
+        clearWorkArea();
+    });
+    afterEach(function()  {
+        this.server.restore();
+        clearWorkArea();
+    });
+
+    it('targets an adjacent element properly', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        var btn = make('<button hx-ext="response-targets" hx-target-404="#d1" hx-get="/test">Click Me!</button>')
+        var div1 = make('<div id="d1"></div>')
+        btn.click();
+        this.server.respond();
+        div1.innerHTML.should.equal("Not found!");
+    });
+
+    it('targets an adjacent element properly with wildcard', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        var btn = make('<button hx-ext="response-targets" hx-target-4*="#d1" hx-get="/test">Click Me!</button>')
+        var div1 = make('<div id="d1"></div>')
+        btn.click();
+        this.server.respond();
+        div1.innerHTML.should.equal("Not found!");
+    });
+
+    it('targets a parent element properly', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        var div1 = make('<div hx-ext="response-targets" id="d1"><button id="b1" hx-target-404="#d1" hx-get="/test">Click Me!</button></div>')
+        var btn = byId("b1")
+        btn.click();
+        this.server.respond();
+        div1.innerHTML.should.equal("Not found!");
+    });
+
+    it('targets a parent element properly with wildcard', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        var div1 = make('<div hx-ext="response-targets" id="d1"><button id="b1" hx-target-*="#d1" hx-get="/test">Click Me!</button></div>')
+        var btn = byId("b1")
+        btn.click();
+        this.server.respond();
+        div1.innerHTML.should.equal("Not found!");
+    });
+
+    it('targets a `this` element properly', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        var div1 = make('<div hx-ext="response-targets" hx-target-404="this"><button id="b1" hx-get="/test">Click Me!</button></div>')
+        var btn = byId("b1")
+        btn.click();
+        this.server.respond();
+        div1.innerHTML.should.equal("Not found!");
+    });
+
+    it('targets a `closest` element properly', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        var div1 = make('<div hx-ext="response-targets"><p><i><button id="b1" hx-target-404="closest div" hx-get="/test">Click Me!</button></i></p></div>')
+        var btn = byId("b1")
+        btn.click();
+        this.server.respond();
+        div1.innerHTML.should.equal("Not found!");
+    });
+
+    it('targets a `closest` element properly w/ hyperscript syntax', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        var div1 = make('<div hx-ext="response-targets"><p><i><button id="b1" hx-target-404="closest <div/>" hx-get="/test">Click Me!</button></i></p></div>')
+        var btn = byId("b1")
+        btn.click();
+        this.server.respond();
+        div1.innerHTML.should.equal("Not found!");
+    });
+
+    it('targets a `find` element properly', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        var div1 = make('<div hx-ext="response-targets" hx-target-404="find span" hx-get="/test">Click Me! <div><span id="s1"></span><span id="s2"></span></div></div>')
+        div1.click();
+        this.server.respond();
+        var span1 = byId("s1")
+        var span2 = byId("s2")
+        span1.innerHTML.should.equal("Not found!");
+        span2.innerHTML.should.equal("");
+    });
+
+    it('targets a `find` element properly w/ hyperscript syntax', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        var div1 = make('<div hx-ext="response-targets" hx-target-404="find <span/>" hx-get="/test">Click Me! <div><span id="s1"></span><span id="s2"></span></div></div>')
+        div1.click();
+        this.server.respond();
+        var span1 = byId("s1")
+        var span2 = byId("s2")
+        span1.innerHTML.should.equal("Not found!");
+        span2.innerHTML.should.equal("");
+    });
+
+    it('targets an inner element properly', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        var btn = make('<button hx-ext="response-targets" hx-target-404="#d1" hx-get="/test">Click Me!<div id="d1"></div></button>')
+        var div1 = byId("d1")
+        btn.click();
+        this.server.respond();
+        div1.innerHTML.should.equal("Not found!");
+    });
+
+    it('targets an inner element properly w/ hyperscript syntax', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        var btn = make('<button hx-ext="response-targets" hx-target-404="<#d1/>" hx-get="/test">Click Me!<div id="d1"></div></button>')
+        var div1 = byId("d1")
+        btn.click();
+        this.server.respond();
+        div1.innerHTML.should.equal("Not found!");
+    });
+
+    it('handles bad target gracefully', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        var btn = make('<button hx-ext="response-targets" hx-target-404="bad" hx-get="/test">Click Me!</button>')
+        btn.click();
+        this.server.respond();
+        btn.innerHTML.should.equal("Click Me!");
+    });
+
+
+    it('targets an adjacent element properly w/ data-* prefix', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        var btn = make('<button hx-ext="response-targets" data-hx-target-404="#d1" data-hx-get="/test">Click Me!</button>')
+        var div1 = make('<div id="d1"></div>')
+        btn.click();
+        this.server.respond();
+        div1.innerHTML.should.equal("Not found!");
+    });
+
+    it('targets a `next` element properly', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        make('<div hx-ext="response-targets">' +
+            '  <div id="d3"></div>' +
+            '  <button id="b1" hx-target-404="next div" hx-get="/test">Click Me!</button>' +
+            '  <div id="d1"></div>' +
+            '  <div id="d2"></div>' +
+            '</div>')
+        var btn = byId("b1")
+        var div1 = byId("d1")
+        var div2 = byId("d2")
+        var div3 = byId("d3")
+        btn.click();
+        this.server.respond();
+        div1.innerHTML.should.equal("Not found!");
+        div2.innerHTML.should.equal("");
+        div3.innerHTML.should.equal("");
+    });
+
+    it('targets a `next` element properly w/ hyperscript syntax', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        make('<div hx-ext="response-targets">' +
+            '  <div id="d3"></div>' +
+            '  <button id="b1" hx-target-404="next <div/>" hx-get="/test">Click Me!</button>' +
+            '  <div id="d1"></div>' +
+            '  <div id="d2"></div>' +
+            '</div>')
+        var btn = byId("b1")
+        var div1 = byId("d1")
+        var div2 = byId("d2")
+        var div3 = byId("d3")
+        btn.click();
+        this.server.respond();
+        div1.innerHTML.should.equal("Not found!");
+        div2.innerHTML.should.equal("");
+        div3.innerHTML.should.equal("");
+    });
+
+    it('targets a `previous` element properly', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        make('<div hx-ext="response-targets">' +
+            '  <div id="d3"></div>' +
+            '  <button id="b1" hx-target-404="previous div" hx-get="/test">Click Me!</button>' +
+            '  <div id="d1"></div>' +
+            '  <div id="d2"></div>' +
+            '</div>')
+        var btn = byId("b1")
+        var div1 = byId("d1")
+        var div2 = byId("d2")
+        var div3 = byId("d3")
+        btn.click();
+        this.server.respond();
+        div1.innerHTML.should.equal("");
+        div2.innerHTML.should.equal("");
+        div3.innerHTML.should.equal("Not found!");
+    });
+
+    it('targets a `previous` element properly w/ hyperscript syntax', function()
+    {
+        this.server.respondWith("GET", "/test", [404, {}, "Not found!"]);
+        make('<div hx-ext="response-targets">' +
+            '  <div id="d3"></div>' +
+            '  <button id="b1" hx-target-404="previous <div/>" hx-get="/test">Click Me!</button>' +
+            '  <div id="d1"></div>' +
+            '  <div id="d2"></div>' +
+            '</div>')
+        var btn = byId("b1")
+        var div1 = byId("d1")
+        var div2 = byId("d2")
+        var div3 = byId("d3")
+        btn.click();
+        this.server.respond();
+        div1.innerHTML.should.equal("");
+        div2.innerHTML.should.equal("");
+        div3.innerHTML.should.equal("Not found!");
+    });
+});

test/index.html

@@ -144,6 +144,9 @@ <h2>Mocha Test Suite</h2>
 <script src="../src/ext/ws.js"></script>
 <script src="ext/ws.js"></script>
 
+<script src="../src/ext/response-targets.js"></script>
+<script src="ext/response-targets.js"></script>
+
 <!-- events last so they don't screw up other tests -->
 <script src="core/events.js"></script>
 

www/content/extensions/_index.md

@@ -79,6 +79,7 @@ See the individual extension documentation for more details.
 | [`path-deps`](@/extensions/path-deps.md)                         | an extension for expressing path-based dependencies [similar to intercoolerjs](http://intercoolerjs.org/docs.html#dependencies)
 | [`preload`](@/extensions/preload.md)                             | preloads selected `href` and `hx-get` targets based on rules you control.
 | [`remove-me`](@/extensions/remove-me.md)                         | allows you to remove an element after a given amount of time
+| [`response-targets`](@/extensions/response-targets.md)           | allows to specify different target elements to be swapped when different HTTP response codes are received
 | [`restored`](@/extensions/restored.md)                           | allows you to trigger events when the back button has been pressed
 | [`server-sent-events`](@/extensions/server-sent-events.md)       | uni-directional server push messaging via [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource)
 | [`web-sockets`](@/extensions/web-sockets.md)                     | bi-directional connection to WebSocket servers