Add How-To instructions for landing-page redirects

This uses both the forms and routable_page contrib modules to redirect
without using a separate landing page.

CHANGELOG.txt

@@ -34,6 +34,7 @@ Changelog
  * Add section about CSV exports to security documentation (Matt Westcott)
  * Add initial support for Django 4.0 deprecations (Matt Westcott, Jochen Wersdörfer)
  * Move translations in `nl_NL` to `nl` (Loïc Teixeira, Coen van der Kamp)
+ * Add documentation for now to redirect to a separate page on Form builder submissions using ``RoutablePageMixin`` (Nick Smith)
  * Fix: Delete button is now correct colour on snippets and modeladmin listings (Brandon Murch)
  * Fix: Ensure that StreamBlock / ListBlock-level validation errors are counted towards error counts (Matt Westcott)
  * Fix: InlinePanel add button is now keyboard navigatable (Jesse Menn)

docs/advanced_topics/formbuilder_routablepage_redirect.md

@@ -0,0 +1,55 @@
+# How to use a redirect with Form builder to prevent double submission
+
+It is common for form submission HTTP responses to be a `302 Found` temporary redirection to a new page.
+By default `wagtail.contrib.forms.models.FormPage` success responses don't do this, meaning there is a risk that users will refresh the success page and re-submit their information.
+
+Instead of rendering the `render_landing_page` content in the POST response, we will redirect to a `route` of the `FormPage` instance at a child URL path.
+The content will still be managed within the same form page's admin.
+This approach uses the additonal contrib module `wagtail.contrib.routable_page`.
+
+An alternative approach is to redirect to an entirely different page, which does not require the `routable_page` module.
+See [Custom landing page redirect](../reference/contrib/forms/customisation.html#custom-landing-page-redirect).
+
+Make sure `"wagtail.contrib.routable_page"` is added to `INSTALLED_APPS`, see [Installation](../reference/contrib/routablepage.html#installation) documentation.
+
+```python
+from django.shortcuts import redirect
+
+from wagtail.contrib.forms.models import AbstractEmailForm
+from wagtail.contrib.routable_page.models import RoutablePageMixin, route
+
+
+class FormPage(RoutablePageMixin, AbstractEmailForm):
+
+    # fields, content_panels, …
+
+    @route(r"^$")
+    def index_route(self, request, *args, **kwargs):
+        """Serve the form, and validate it on POST"""
+        return super(AbstractEmailForm, self).serve(request, *args, **kwargs)
+
+    def render_landing_page(self, request, form_submission, *args, **kwargs):
+        """Redirect instead to self.thank_you route"""
+        url = self.reverse_subpage("thank_you")
+        # If a form_submission instance is available, append the ID to URL.
+        if form_submission:
+            url += "?id=%s" % form_submission.id
+        return redirect(self.url + url, permanent=False)
+
+    @route(r"^thank-you/$")
+    def thank_you(self, request):
+        """Return the superclass's landing page, after redirect."""
+        form_submission = None
+        try:
+            submission_id = int(request.GET["id"])
+        except (KeyError, TypeError):
+            pass
+        else:
+            submission_class = self.get_submission_class()
+            try:
+                form_submission = submission_class.objects.get(id=submission_id)
+            except submission_class.DoesNotExist:
+                pass
+
+        return super().render_landing_page(request, form_submission)
+```

docs/advanced_topics/index.rst

@@ -21,3 +21,4 @@ Advanced topics
     accessibility_considerations
     boundblocks_and_values
     multi_site_multi_instance_multi_tenancy
+    formbuilder_routablepage_redirect

docs/releases/2.15.rst

@@ -45,6 +45,7 @@ Other features
  * Add section about CSV exports to security documentation (Matt Westcott)
  * Add initial support for Django 4.0 deprecations (Matt Westcott, Jochen Wersdörfer)
  * Translations in ``nl_NL`` are moved to the ``nl`` po files. ``nl_NL`` translation files are deleted. Projects that use ``LANGUAGE_CODE = 'nl-nl'`` will automatically fallback to ``nl``. (Loïc Teixeira, Coen van der Kamp)
+ * Add documentation for now to redirect to a separate page on Form builder submissions using ``RoutablePageMixin`` (Nick Smith)
 
 Bug fixes
 ~~~~~~~~~