wagtail/docs/advanced_topics/amp.rst

How to build a site with AMP support
====================================

This recipe document describes a method for creating an
`AMP <https://amp.dev/>`_ version of a Wagtail site and hosting it separately
to the rest of the site on a URL prefix. It also describes how to make Wagtail
render images with the ``<amp-img>`` tag when a user is visiting a page on the
AMP version of the site.

Overview
--------

In the next section, we will add a new URL entry that points at Wagtail's
internal ``serve()`` view which will have the effect of rendering the whole
site again under the ``/amp`` prefix.

Then, we will add some utilities that will allow us to track whether the
current request is in the ``/amp`` prefixed version of the site without needing
a request object.

After that, we will add a template context processor to allow us to check from
within templates which version of the site is being rendered.

Then, finally, we will modify the behaviour of the ``{% image %}`` tag to make it
render ``<amp-img>`` tags when rendering the AMP version of the site.

Creating the second page tree
-----------------------------

We can render the whole site at a different prefix by duplicating the Wagtail
URL in the project ``urls.py`` file and giving it a prefix. This must be before
the default URL from Wagtail, or it will try to find ``/amp`` as a page:

.. code-block:: python

    # <project>/urls.py

    urlpatterns += [
        # Add this line just before the default ``include(wagtail_urls)`` line
        path('amp/', include(wagtail_urls)),

        path('', include(wagtail_urls)),
    ]

If you now open ``http://localhost:8000/amp/`` in your browser, you should see
the homepage.

Making pages aware of "AMP mode"
--------------------------------

All the pages will now render under the ``/amp`` prefix, but right now there
isn't any difference between the AMP version and the normal version.

To make changes, we need to add a way to detect which URL was used to render
the page. To do this, we will have to wrap Wagtail's ``serve()`` view and
set a thread-local to indicate to all downstream code that AMP mode is active.

.. note:: Why a thread-local?

    (feel free to skip this part if you're not interested)

    Modifying the ``request`` object would be the most common way to do this.
    However, the image tag rendering is performed in a part of Wagtail that
    does not have access to the request.

    Thread-locals are global variables that can have a different value for each
    running thread. As each thread only handles one request at a time, we can
    use it as a way to pass around data that is specific to that request
    without having to pass the request object everywhere.

    Django uses thread-locals internally to track the currently active language
    for the request.

    Please be aware though: In Django 3.x and above, you will need to use an
    ``asgiref.Local`` instead.
    This is because Django 3.x handles multiple requests in a single thread
    so thread-locals will no longer be unique to a single request.

Now let's create that thread-local and some utility functions to interact with it,
save this module as ``amp_utils.py`` in an app in your project:

.. code-block:: python

    # <app>/amp_utils.py

    from contextlib import contextmanager
    from threading import local

    # FIXME: For Django 3.0 support, replace this with asgiref.Local
    _amp_mode_active = local()

    @contextmanager
    def activate_amp_mode():
        """
        A context manager used to activate AMP mode
        """
        _amp_mode_active.value = True
        try:
            yield
        finally:
            del _amp_mode_active.value

    def amp_mode_active():
        """
        Returns True if AMP mode is currently active
        """
        return hasattr(_amp_mode_active, 'value')

This module defines two functions:

 - ``activate_amp_mode`` is a context manager which can be invoked using Python's
   ``with`` syntax. In the body of the ``with`` statement, AMP mode would be active.

 - ``amp_mode_active`` is a function that returns ``True`` when AMP mode is active.

Next, we need to define a view that wraps Wagtail's builtin ``serve`` view and
invokes the ``activate_amp_mode`` context manager:

.. code-block:: python

    # <app>/amp_views.py

    from django.template.response import SimpleTemplateResponse
    from wagtail.core.views import serve as wagtail_serve

    from .amp_utils import activate_amp_mode

    def serve(request, path):
        with activate_amp_mode():
            response = wagtail_serve(request, path)

            # Render template responses now while AMP mode is still active
            if isinstance(response, SimpleTemplateResponse):
                response.render()

            return response

Then we need to create a ``amp_urls.py`` file in the same app:

.. code-block:: python

    # <app>/amp_urls.py

    from django.urls import re_path
    from wagtail.core.urls import serve_pattern

    from . import amp_views

    urlpatterns = [
        re_path(serve_pattern, amp_views.serve, name='wagtail_amp_serve')
    ]

Finally, we need to update the project's main ``urls.py`` to use this new URLs
file for the ``/amp`` prefix:

.. code-block:: python

    # <project>/urls.py

    from myapp import amp_urls as wagtail_amp_urls

    urlpatterns += [
        # Change this line to point at your amp_urls instead of Wagtail's urls
        path('amp/', include(wagtail_amp_urls)),

        re_path(r'', include(wagtail_urls)),
    ]

After this, there shouldn't be any noticeable difference to the AMP version of
the site.

Write a template context processor so that AMP state can be checked in templates
--------------------------------------------------------------------------------

This is optional, but worth doing so we can confirm that everything is working
so far.

Add a ``amp_context_processors.py`` file into your app that contains the
following:

.. code-block:: python

    # <app>/amp_context_processors.py

    from .amp_utils import amp_mode_active

    def amp(request):
        return {
            'amp_mode_active': amp_mode_active(),
        }

Now add the path to this context processor to the
``['OPTIONS']['context_processors']`` key of the ``TEMPLATES`` setting:

.. code-block:: python

    # Either <project>/settings.py or <project>/settings/base.py

    TEMPLATES = [
        {
            ...

            'OPTIONS': {
                'context_processors': [
                    ...
                    # Add this after other context processors
                    'myapp.amp_context_processors.amp',
                ],
            },
        },
    ]

You should now be able to use the ``amp_mode_active`` variable in templates.
For example:

.. code-block:: html+Django

    {% if amp_mode_active %}
        AMP MODE IS ACTIVE!
    {% endif %}

Using a different page template when AMP mode is active
-------------------------------------------------------

You're probably not going to want to use the same templates on the AMP site as
you do on the regular web site. Let's add some logic in to make Wagtail use a
separate template whenever a page is served with AMP enabled.

We can use a mixin, which allows us to re-use the logic on different page types.
Add the following to the bottom of the amp_utils.py file that you created earlier:

.. code-block:: python

    # <app>/amp_utils.py

    import os.path

    ...

    class PageAMPTemplateMixin:

        @property
        def amp_template(self):
            # Get the default template name and insert `_amp` before the extension
            name, ext = os.path.splitext(self.template)
            return name + '_amp' + ext

        def get_template(self, request):
            if amp_mode_active():
                return self.amp_template

            return super().get_template(request)

Now add this mixin to any page model, for example:

.. code-block:: python

    # <app>/models.py

    from .amp_utils import PageAMPTemplateMixin

    class MyPageModel(PageAMPTemplateMixin, Page):
        ...

When AMP mode is active, the template at ``app_label/mypagemodel_amp.html``
will be used instead of the default one.

If you have a different naming convention, you can override the
``amp_template`` attribute on the model. For example:

.. code-block:: python

    # <app>/models.py

    from .amp_utils import PageAMPTemplateMixin

    class MyPageModel(PageAMPTemplateMixin, Page):
        amp_template = 'my_custom_amp_template.html'

Overriding the ``{% image %}`` tag to output ``<amp-img>`` tags
---------------------------------------------------------------

Finally, let's change Wagtail's ``{% image %}`` tag, so it renders an ``<amp-img>``
tags when rendering pages with AMP enabled. We'll make the change on the
`Rendition` model itself so it applies to both images rendered with the
``{% image %}`` tag and images rendered in rich text fields as well.

Doing this with a :ref:`Custom image model <custom_image_model>` is easier, as
you can override the ``img_tag``  method on your custom ``Rendition`` model to
return a different tag.

For example:

.. code-block:: python

    from django.forms.utils import flatatt
    from django.utils.safestring import mark_safe

    from wagtail.images.models import AbstractRendition

    ...

    class CustomRendition(AbstractRendition):
        def img_tag(self, extra_attributes):
            attrs = self.attrs_dict.copy()
            attrs.update(extra_attributes)

            if amp_mode_active():
                return mark_safe('<amp-img{}>'.format(flatatt(attrs)))
            else:
                return mark_safe('<img{}>'.format(flatatt(attrs)))

        ...

Without a custom image model, you will have to monkey-patch the builtin
``Rendition`` model.
Add this anywhere in your project where it would be imported on start:

.. code-block:: python

    from django.forms.utils import flatatt
    from django.utils.safestring import mark_safe

    from wagtail.images.models import Rendition

    def img_tag(rendition, extra_attributes={}):
        """
        Replacement implementation for Rendition.img_tag

        When AMP mode is on, this returns an <amp-img> tag instead of an <img> tag
        """
        attrs = rendition.attrs_dict.copy()
        attrs.update(extra_attributes)

        if amp_mode_active():
            return mark_safe('<amp-img{}>'.format(flatatt(attrs)))
        else:
            return mark_safe('<img{}>'.format(flatatt(attrs)))

    Rendition.img_tag = img_tag