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 `__. + * Add ``select`` parameter to ``HttpResponseLocation``. Thanks to Nikola Anović in `PR #462 `__. diff --git a/docs/http.rst b/docs/http.rst index 44bc471..0d4af83 100644 --- a/docs/http.rst +++ b/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. 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()