From 5ce0ec4e06fc71a6737487a1478e0e5e99b5f20e Mon Sep 17 00:00:00 2001
From: Bogumil Schube <bogumil@schube.info>
Date: Mon, 4 Dec 2023 13:59:23 +0100
Subject: [PATCH 1/3] Add replace_url()

---
 docs/http.rst           | 30 ++++++++++++++++++++++++++++++
 src/django_htmx/http.py |  5 +++++
 tests/test_http.py      | 19 +++++++++++++++++++
 3 files changed, 54 insertions(+)

diff --git a/docs/http.rst b/docs/http.rst
index 44bc471..2be2d01 100644
--- a/docs/http.rst
+++ b/docs/http.rst
@@ -186,6 +186,36 @@ 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 into 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 leaf(request, leaf_id):
+          ...
+          if leaf is None:
+              # Directly render branch view
+              response = branch(request, branch=leaf.branch)
+              return replace_url(response, f"/branch/{leaf.branch.id}")
+          ...
+
 .. autofunction:: reswap
 
    Set the |HX-Reswap header|__ of ``response`` and return it.
diff --git a/src/django_htmx/http.py b/src/django_htmx/http.py
index 8a0fa49..03ab671 100644
--- a/src/django_htmx/http.py
+++ b/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
diff --git a/tests/test_http.py b/tests/test_http.py
index 267de2e..8c587cb 100644
--- a/tests/test_http.py
+++ b/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()

From be10db110d6e4f2788b2d04ac571756b316f2cb2 Mon Sep 17 00:00:00 2001
From: Adam Johnson <me@adamj.eu>
Date: Thu, 1 Aug 2024 15:06:49 +0100
Subject: [PATCH 2/3] tweak docs

---
 docs/http.rst | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/docs/http.rst b/docs/http.rst
index 2be2d01..0d4af83 100644
--- a/docs/http.rst
+++ b/docs/http.rst
@@ -189,12 +189,11 @@ Response modifying functions
 .. autofunction:: replace_url
 
    Set the |HX-Replace-Url header|__ of ``response`` and return it.
-   This header causes htmx to replace the current URL into the browser location history.
+   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.
 
@@ -208,13 +207,12 @@ Response modifying functions
       from django_htmx.http import replace_url
 
 
-      def leaf(request, leaf_id):
-          ...
-          if leaf is None:
-              # Directly render branch view
-              response = branch(request, branch=leaf.branch)
-              return replace_url(response, f"/branch/{leaf.branch.id}")
+      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
 

From b3bb7ee3c2c42d7156affde73ad6b7954ea51fb4 Mon Sep 17 00:00:00 2001
From: Adam Johnson <me@adamj.eu>
Date: Thu, 1 Aug 2024 15:09:49 +0100
Subject: [PATCH 3/3] changelog note

---
 docs/changelog.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/changelog.rst b/docs/changelog.rst
index 6b23a77..284810c 100644
--- a/docs/changelog.rst
+++ b/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>`__.