Add replace_url() (#396)

---------

Co-authored-by: Adam Johnson <me@adamj.eu>

docs/changelog.rst

@@ -2,6 +2,10 @@
 Changelog
 =========
 
+* Add :func:`django_htmx.http.replace_url()` for setting the ``HX-Replace-URL`` header.
+
+  Thanks to Bogumil Schube in `PR #396 <https://github.com/adamchainz/django-htmx/pull/396>`__.
+
 * Add ``select`` parameter to ``HttpResponseLocation``.
 
   Thanks to Nikola Anović in `PR #462 <https://github.com/adamchainz/django-htmx/pull/462>`__.

docs/http.rst

@@ -186,6 +186,34 @@ Response modifying functions
               return push_url(response, f"/branch/{leaf.branch.id}")
           ...
 
+.. autofunction:: replace_url
+
+   Set the |HX-Replace-Url header|__ of ``response`` and return it.
+   This header causes htmx to replace the current URL in the browser location history.
+
+   .. |HX-Replace-Url header| replace:: ``HX-Replace-Url`` header
+   __ https://htmx.org/headers/hx-replace-url/
+
+   :param response:
+      The response to modify and return.
+
+   :param url:
+      The (relative) URL to replace, or ``False`` to prevent the location history from being updated.
+
+   For example:
+
+   .. code-block:: python
+
+      from django_htmx.http import replace_url
+
+
+      def dashboard(request):
+          ...
+          response = render(request, "dashboard.html", ...)
+          # Pretend the user was always on the dashboard, rather than wherever
+          # they were on before.
+          return replace_url(response, "/dashboard/")
+
 .. autofunction:: reswap
 
    Set the |HX-Reswap header|__ of ``response`` and return it.

src/django_htmx/http.py

@@ -96,6 +96,11 @@ def push_url(response: _HttpResponse, url: str | Literal[False]) -> _HttpRespons
     return response
 
 
+def replace_url(response: _HttpResponse, url: str | Literal[False]) -> _HttpResponse:
+    response["HX-Replace-Url"] = "false" if url is False else url
+    return response
+
+
 def reswap(response: _HttpResponse, method: str) -> _HttpResponse:
     response["HX-Reswap"] = method
     return response

tests/test_http.py

@@ -14,6 +14,7 @@
 from django_htmx.http import HttpResponseLocation
 from django_htmx.http import HttpResponseStopPolling
 from django_htmx.http import push_url
+from django_htmx.http import replace_url
 from django_htmx.http import reswap
 from django_htmx.http import retarget
 from django_htmx.http import trigger_client_event
@@ -107,6 +108,24 @@ def test_success_false(self):
         assert response["HX-Push-Url"] == "false"
 
 
+class ReplaceUrlTests(SimpleTestCase):
+    def test_success(self):
+        response = HttpResponse()
+
+        response2 = replace_url(response, "/index.html")
+
+        assert response2 is response
+        assert response["HX-Replace-Url"] == "/index.html"
+
+    def test_success_false(self):
+        response = HttpResponse()
+
+        response2 = replace_url(response, False)
+
+        assert response2 is response
+        assert response["HX-Replace-Url"] == "false"
+
+
 class ReswapTests(SimpleTestCase):
     def test_success(self):
         response = HttpResponse()