task/CDD-1379-page-previews

Enable page previews to the configured frontend URL

Author: jeanpierrefouche-ukhsa

changelog/2026-02-27/CDD-1379.page-previews.md

@@ -0,0 +1,91 @@
+# CDD-1379 - Page Previews
+
+**Date:** 2026-02-27
+
+**Ticket:** https://ukhsa.atlassian.net/browse/CDD-1379?search_id=055fe61d-bee9-48d9-80bc-ffb0f1c26b76&referrer=quick-find
+
+**Authors:** Jean-Pierre Fouche
+
+**Impact:** Affects all pages - broad testing required
+
+**Testing:** Comprehensive unit tests supplied.  UAT needed.
+
+
+## Summary
+
+Allow editors of headless composite pages to click a **Preview** button that immediately redirects them to the external frontend application, rather than opening the built-in Wagtail iframe preview.  Preview URLs include a short-lived signed token so the frontend can safely fetch draft content from the CMS.
+
+## Workflow
+
+- Editors see a custom "Preview" button in the CMS if the page type allows previews.
+- When clicked, the CMS generates a short-lived, signed token and redirects the editor’s browser to the frontend preview URL with this token.
+- The frontend uses the token to securely fetch the latest draft content from the CMS via a special API endpoint.
+- The API validates the token (including expiry and page ID) before returning draft content.
+- Preview enablement is controlled by a flag on each page type.
+- The system avoids Wagtail’s built-in iframe preview, using external redirects and API calls for a secure, modern preview experience.
+- Security is enforced by short token lifetimes, HMAC signing, and requiring tokens in Authorization headers for API access.
+
+## Architecture
+
+### Component Flow Diagram
+
+```mermaid
+sequenceDiagram
+    participant Browser as Editor Browser
+    participant CMS as Wagtail Admin (CMS)
+    participant API as Django CMS API
+    participant FE as Next.js Frontend
+
+    Browser->>CMS: Load page editor
+    CMS-->>Browser: Render Preview button (href=/admin/preview-to-frontend/{page_id}/)
+    Note right of Browser: Preview button visible
+    Browser->>CMS: Click Preview
+    Browser->>API: GET /admin/preview-to-frontend/{page_id}
+    API-->>API: Build signed token + frontend preview URL
+    API-->>Browser: 302 Location: /preview?slug=...&t=...
+    Browser->>FE: Follow 302 to frontend preview URL
+    FE->>API: GET /api/drafts/{id} (Authorization: Bearer <token>)
+    API-->>FE: draft JSON
+    FE-->>Browser: Rendered preview page
+```
+
+### Security
+
+- **Token TTL**: 120-second expiry limits exposure window
+- **HMAC signing**: Tokens cryptographically signed, cannot be forged
+- **Salt isolation**: Preview tokens use dedicated salt, separate from session tokens
+- **Bearer vs querystring**: Token transmitted in Authorization header to API (reduces logging exposure), though initially passed via querystring in redirect (acceptable for short-lived tokens)
+- **Prevention of replay attacks**: Each token includes `iat` timestamp and specific `page_id`, limiting reuse scope
+
+## Environment Variables
+
+Set these up in an environment file (such as env.local)
+(These are defined with default values in default.py and local.py)
+
+```bash
+PAGE_PREVIEWS_ENABLED = False # Allows the server to disable or enable page previews
+PAGE_PREVIEWS_FRONTEND_BASE_URL = 'http://localhost:3000' # The base URL for the front-end application.  Allows the CMS to send the browser to the frontend on the click of a button.
+PAGE_PREVIEWS_FRONTEND_URL_TEMPLATE = "http://localhost:3000/preview?slug={slug}&t={token}" # The format of the URL redirect that will be sent to the Front End
+PAGE_PREVIEWS_TOKEN_TTL_SECONDS = 86400 #  The front end receives a presigned url.  This setting defines the token expiry window.  It is recommended to keep this as low as possible, and can possibly be set to as low as 60 seconds, the time it takes for the front end to render the page.  Default is 120 seconds.
+PAGE_PREVIEWS_TOKEN_SALT = 'preview-token' # Salt string - adds an extra layer of security into the generation of the token.
+```
+
+## Files Changed
+
+| File Name | Purpose of Change | Process (Inputs, Process, Outputs, Example) |
+|-----------|------------------|---------------------------------------------|
+| cms/common/models.py | Added preview support and improved related link logic for common pages, enabling editors to preview unpublished changes and manage related links more flexibly. | **Input:** Page instance.<br>**Process:** Adds preview fields and related link handling.<br>**Output:** CommonPage with preview and links.<br>**Example:** Input: CommonPage; Output: Previewable CommonPage. |
+| cms/composite/models.py | Enhanced composite pages with preview, pagination, and related link support, allowing editors to preview drafts and control page navigation. | **Input:** CompositePage instance.<br>**Process:** Adds preview, pagination, and related link fields.<br>**Output:** CompositePage with preview and pagination.<br>**Example:** Input: CompositePage; Output: Previewable CompositePage. |
+| cms/dashboard/models.py | Centralized preview enablement and shared logic for all dashboard pages, standardizing how preview is toggled and managed across page types. | **Input:** Dashboard page instance.<br>**Process:** Adds preview flags and shared logic.<br>**Output:** Dashboard pages with preview toggle.<br>**Example:** Input: UKHSAPage; Output: Preview-enabled UKHSAPage. |
+| cms/dashboard/serializers.py | Extended serializers to support draft and published page data for the API, ensuring frontend receives correct structure for previews. | **Input:** Page instance.<br>**Process:** Serializes fields for frontend preview.<br>**Output:** JSON page data.<br>**Example:** Input: Draft page; Output: `{ "id": 123, "title": "COVID-19" }` |
+| cms/dashboard/templates/wagtailadmin/pages/action_menu/frontend_preview.html | New template for the Preview button in Wagtail admin, providing a clear call-to-action for editors to preview content externally. | **Input:** Button context (label, url, etc).<br>**Process:** Renders button HTML.<br>**Output:** Preview button in admin.<br>**Example:** Input: label="Preview", url="/admin/preview/1"; Output: Button HTML. |
+| cms/dashboard/views.py | Added secure redirect logic to generate signed preview tokens and forward editors to the frontend preview, enforcing permissions and token expiry. | **Input:** GET `/admin/preview-to-frontend/{page_id}/`.<br>**Process:** Checks permissions, signs token, builds URL.<br>**Output:** 302 redirect to frontend.<br>**Example:** Input: Page ID 123; Output: Redirect to preview URL. |
+| cms/dashboard/viewsets.py | Implemented API endpoint to serve draft content to the frontend, validating signed tokens and supporting secure preview of unpublished changes. | **Input:** GET `/api/drafts/{id}` with Bearer token.<br>**Process:** Validates token, fetches draft.<br>**Output:** JSON draft page.<br>**Example:** Input: Bearer token for page 123; Output: Draft JSON. |
+| cms/dashboard/wagtail_hooks.py | Registered preview button, admin URLs, and menu actions in Wagtail, integrating the preview workflow into the CMS UI and admin menus. | **Input:** Page edit context.<br>**Process:** Adds preview button/action, registers redirect endpoint.<br>**Output:** Preview button and redirect URL.<br>**Example:** Input: Editor clicks Preview; Output: Redirect to frontend. |
+| cms/home/models/landing_page.py | Enabled preview and related link support for landing pages, so editors can review unpublished changes and manage links. | **Input:** LandingPage instance.<br>**Process:** Adds preview and related link fields.<br>**Output:** LandingPage with preview.<br>**Example:** Input: LandingPage; Output: Previewable LandingPage. |
+| cms/topic/models.py | Enabled preview and related link support for topic pages, improving editorial workflow for draft content and navigation. | **Input:** TopicPage instance.<br>**Process:** Adds preview and related link fields.<br>**Output:** TopicPage with preview.<br>**Example:** Input: TopicPage; Output: Previewable TopicPage. |
+| config.py | Added and documented preview/token settings and environment variables, ensuring correct configuration for secure preview flows. | **Input:** Env variables.<br>**Process:** Loads/sets preview config.<br>**Output:** Config values for preview/token.<br>**Example:** Input: PAGE_PREVIEWS_ENABLED; Output: True/False. |
+| metrics/api/settings/default.py | Set default preview/token and API settings, providing baseline security and feature toggles for preview functionality. | **Input:** Default settings.<br>**Process:** Sets preview/token defaults.<br>**Output:** Default config for preview/token.<br>**Example:** Input: PAGE_PREVIEWS_TOKEN_TTL_SECONDS; Output: 120. |
+| metrics/api/settings/local.py | Overrode preview/token settings for local development, making it easier to test preview features in dev environments. | **Input:** Local settings.<br>**Process:** Overrides preview config.<br>**Output:** Local config for preview/token.<br>**Example:** Input: PAGE_PREVIEWS_ENABLED; Output: True. |
+| scripts/_quality.sh | Bug fix - return replaces exit, thus keeping the current shell open. |
+

cms/common/models.py

@@ -53,11 +53,6 @@ class CommonPage(UKHSAPage):
 
     objects = CommonPageManager()
 
-    @classmethod
-    def is_previewable(cls) -> bool:
-        """Returns False. Since this is a headless CMS the preview panel is not supported"""
-        return False
-
 
 class CommonPageRelatedLink(UKHSAPageRelatedLink):
     page = ParentalKey(

cms/composite/models.py

@@ -86,11 +86,6 @@ class CompositePage(UKHSAPage):
 
     objects = CompositePageManager()
 
-    @classmethod
-    def is_previewable(cls) -> bool:
-        """Returns False. Since this is a headless CMS the preview panel is not supported"""
-        return False
-
     @property
     def last_updated_at(self) -> datetime.datetime:
         """Takes the most recent update of this page and any of its children

cms/dashboard/models.py

@@ -1,5 +1,6 @@
 import datetime
 from decimal import Decimal
+from typing import override
 
 from django.core.exceptions import ValidationError
 from django.core.validators import MaxValueValidator, MinValueValidator
@@ -43,6 +44,8 @@ class UKHSAPage(Page):
 
     """
 
+    custom_preview_enabled: bool = True
+
     body = RichTextField(features=AVAILABLE_RICH_TEXT_FEATURES)
     seo_change_frequency = models.IntegerField(
         verbose_name="SEO change frequency",
@@ -98,6 +101,11 @@ class UKHSAPage(Page):
     class Meta:
         abstract = True
 
+    @override
+    def is_previewable(self) -> bool:
+        """Disable built-in Wagtail preview for all headless dashboard pages."""
+        return False
+
     def _raise_error_if_slug_not_unique(self) -> None:
         """Compares the provided slug against all pages to confirm the slug's `uniqueness`
             this is against all pages and not just siblings, which is the default behavior of wagtail.

cms/dashboard/serializers.py

@@ -1,41 +1,7 @@
-from collections import OrderedDict
-
-from rest_framework import serializers
 from wagtail.api.v2.views import PageSerializer
-from wagtail.models import Page
 
 from cms.dashboard.fields import ListablePageParentField
 
-PAGE_HAS_NO_DRAFTS = (
-    "Page has no unpublished changes. Use the `api/pages/` for live pages instead."
-)
-
-
-class CMSDraftPagesSerializer(PageSerializer):
-    class Meta:
-        model = Page
-        fields = "__all__"
-
-    def to_representation(self, instance: Page) -> OrderedDict:
-        """Provides a representation of the serialized instance
-
-        Notes:
-            This provides some additional logic to ensure
-            the `instance` being serialized has unpublished changes.
-            If not, then the serializer is invalidated
-
-        Args:
-            instance: The `Page` model being serialized
-
-        Returns:
-            A dict representation of the serialized instance
-
-        """
-        if not instance.has_unpublished_changes:
-            raise serializers.ValidationError({"error_message": PAGE_HAS_NO_DRAFTS})
-
-        return super().to_representation(instance=instance)
-
 
 class ListablePageSerializer(PageSerializer):
     parent = ListablePageParentField(read_only=True)

cms/dashboard/templates/wagtailadmin/pages/action_menu/frontend_preview.html

@@ -0,0 +1,6 @@
+{% load wagtailadmin_tags %}
+{% if url %}
+    <a class="button{% if classname %} {{ classname }}{% endif %}" href="{{ url }}" target="_blank" rel="noopener noreferrer">{% if icon_name %}{% icon name=icon_name %}{% endif %}{{ label }}</a>
+{% else %}
+    <button type="submit" name="{{ name }}" value="{{ label }}" class="button{% if classname %} {{ classname }}{% endif %}">{% if icon_name %}{% icon name=icon_name %}{% endif %}{{ label }}</button>
+{% endif %}

cms/dashboard/views.py

@@ -1,6 +1,135 @@
+from datetime import timedelta
+from urllib.parse import urlencode, urlsplit, urlunsplit
+
+from django.conf import settings
+from django.core.exceptions import PermissionDenied
 from django.core.handlers.wsgi import WSGIRequest
+from django.core.signing import dumps
 from django.http import JsonResponse
+from django.shortcuts import get_object_or_404, redirect
+from django.utils import timezone
+from django.views import View
 from wagtail.admin.views.chooser import BrowseView
+from wagtail.models import Page
+
+# Token salt for preview tokens; configurable via Django settings to avoid
+# hard-coded strings in code.
+PAGE_PREVIEWS_TOKEN_SALT = getattr(
+    settings, "PAGE_PREVIEWS_TOKEN_SALT", "preview-token"
+)
+
+
+class PreviewToFrontendRedirectView(View):
+    """Generate a signed preview token and redirect to the frontend.
+
+    This view is intentionally simple: it performs a permission check on the
+    requested page, builds a small payload, signs it using Django's signing
+    utilities and then redirects the browser to the frontend with the token as
+    a query parameter. The frontend is responsible for validating the token
+    and fetching any draft content.
+
+    Attributes:
+        PREVIEW_TOKEN_TTL_SECONDS: Token lifetime in seconds (configurable via
+            PAGE_PREVIEWS_TOKEN_TTL_SECONDS setting, defaults to 120)
+    """
+
+    # token lifetime in seconds (configurable via settings)
+    PREVIEW_TOKEN_TTL_SECONDS = getattr(
+        settings,
+        "PAGE_PREVIEWS_TOKEN_TTL_SECONDS",
+        120,
+    )
+
+    @staticmethod
+    def _canonicalise_preview_url(
+        *, raw_url: str, slug: str, token: str, page_id: int
+    ) -> str:
+        """Return preview URL with canonical query params.
+
+        The query string is always normalised to `slug`, `t`, and `page_id` so stale or
+        legacy template parameters (e.g. `draft=true`, `slug_name`) are not propagated to the frontend.
+        """
+        parts = urlsplit(raw_url)
+        query = urlencode({"slug": slug, "t": token, "page_id": page_id})
+        return urlunsplit(
+            (parts.scheme, parts.netloc, parts.path, query, parts.fragment)
+        )
+
+    @staticmethod
+    def build_route_slug(*, page: Page) -> str:
+        """Return route-style slug path matching frontend route shape.
+
+        For nested pages this returns paths like `parent/child` (matching
+        `html_url` path semantics) rather than a leaf-only slug.
+        """
+        route_path = ""
+        try:
+            _, _, page_path = page.get_url_parts(request=None)
+            route_path = (page_path or "").strip("/")
+        except (AttributeError, TypeError, ValueError):
+            route_path = ""
+
+        return route_path or str(page.slug)
+
+    def get(self, request, pk):
+        """Handle GET request to generate preview token and redirect to frontend.
+
+        Args:
+            request: The HTTP request object
+            pk: Primary key of the Page to preview
+
+        Returns:
+            HttpResponseRedirect: Redirect to frontend preview URL with signed token
+
+        Raises:
+            Http404: If page with given pk does not exist
+            PermissionDenied: If user lacks edit permission for the page
+        """
+        page = get_object_or_404(Page, pk=pk).specific
+
+        perms = page.permissions_for_user(request.user)
+        if not perms.can_edit():
+            raise PermissionDenied
+
+        now = timezone.now()
+        payload = {
+            "page_id": page.pk,
+            "editor_id": request.user.pk if request.user.is_authenticated else None,
+            "iat": int(now.timestamp()),
+            "exp": int(
+                (now + timedelta(seconds=self.PREVIEW_TOKEN_TTL_SECONDS)).timestamp()
+            ),
+        }
+
+        token = dumps(payload, salt=PAGE_PREVIEWS_TOKEN_SALT)
+
+        # Build the frontend URL using a configurable template. The template
+        # should include placeholders for `{slug}` and `{token}`.
+        # A default
+        # value is provided to preserve previous behaviour.
+        # See docs/environment_variables.md for PAGE_PREVIEWS_FRONTEND_URL_TEMPLATE format.
+        template = getattr(
+            settings,
+            "PAGE_PREVIEWS_FRONTEND_URL_TEMPLATE",
+            "http://localhost:3000/preview?slug={slug}&t={token}",
+        )
+
+        route_slug = self.build_route_slug(page=page)
+
+        frontend_url = template.format(
+            page_id=page.pk,
+            slug_name=page.slug,
+            slug=route_slug,
+            token=token,
+        )
+        frontend_url = self._canonicalise_preview_url(
+            raw_url=frontend_url,
+            slug=route_slug,
+            token=token,
+            page_id=page.pk,
+        )
+
+        return redirect(frontend_url)
 
 
 class LinkBrowseView(BrowseView):