From d2080ff892fc538089a72bafebbde1dc286ba7e0 Mon Sep 17 00:00:00 2001 From: Matt Westcott Date: Mon, 20 Jan 2020 16:11:23 +0000 Subject: [PATCH] Update docs to cover responsive HTML being disabled by default --- docs/reference/settings.rst | 11 +++++++++++ docs/releases/2.8.rst | 9 +++++++++ docs/topics/writing_templates.rst | 11 +++++++++-- 3 files changed, 29 insertions(+), 2 deletions(-) diff --git a/docs/reference/settings.rst b/docs/reference/settings.rst index fe2de5073d..4ee6639163 100644 --- a/docs/reference/settings.rst +++ b/docs/reference/settings.rst @@ -75,6 +75,17 @@ Wagtail has a builtin list of the most common providers. The embeds fetching can be fully configured using the ``WAGTAILEMBEDS_FINDERS`` setting. This is fully documented in :ref:`configuring_embed_finders`. +.. code-block:: python + + WAGTAILEMBEDS_RESPONSIVE_HTML = True + +Adds ``class="responsive-object"`` and an inline ``padding-bottom`` style to embeds, +to assist in making them responsive. See :ref:`responsive-embeds` for details. + +.. versionadded:: 2.8 + + The ``WAGTAILEMBEDS_RESPONSIVE_HTML`` setting was added. + Dashboard ========= diff --git a/docs/releases/2.8.rst b/docs/releases/2.8.rst index e2099ebc14..0857e0f46c 100644 --- a/docs/releases/2.8.rst +++ b/docs/releases/2.8.rst @@ -87,6 +87,15 @@ restore the previous behaviour, you can set the ``WAGTAILADMIN_GLOBAL_PAGE_EDIT_LOCK`` setting to ``True``. +Responsive HTML for embeds no longer added by default +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In previous versions of Wagtail, embedded media elements were given +a class name of ``responsive-object`` and an inline ``padding-bottom`` style to assist +in styling them responsively. These are no longer added by default. To restore the previous +behaviour, add ``WAGTAILEMBEDS_RESPONSIVE_HTML = True`` to your project settings. + + API endpoint classes have moved ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/topics/writing_templates.rst b/docs/topics/writing_templates.rst index dbd13b04f1..3eac053bfd 100644 --- a/docs/topics/writing_templates.rst +++ b/docs/topics/writing_templates.rst @@ -119,10 +119,13 @@ Only fields using ``RichTextField`` need this applied in the template. ... {{ page.body|richtext }} + +.. _responsive-embeds: + Responsive Embeds ----------------- -Wagtail includes embeds and images at their full width, which may overflow the bounds of the content container you've defined in your templates. To make images and embeds responsive -- meaning they'll resize to fit their container -- include the following CSS. +By default, Wagtail includes embeds and images at their full width, which may overflow the bounds of the content container you've defined in your templates. To address this, Wagtail provides the ability to make images and embeds responsive -- meaning they'll resize to fit their container. Responsive embeds can be enabled by setting ``WAGTAILEMBEDS_RESPONSIVE_HTML = True`` in your project settings; this adds a CSS class of ``responsive-object`` and an inline ``padding-bottom`` style to the embed, to be used in conjunction with CSS such as the following: .. code-block:: css @@ -145,7 +148,11 @@ Wagtail includes embeds and images at their full width, which may overflow the b height: 100%; } -It's possible to disable responsive embeds entirely by setting ``WAGTAILEMBEDS_RESPONSIVE_HTML = False`` in your settings. Normally, Wagtail wraps your embed links in a ``
`` element. If you decide to disable responsive embeds the ``
`` element around your embed will not be given a CSS class of ``responsive-object`` and there won't be an inline style in the same parent ``
`` element. This means the responsiveness of your embed is entirely up to you. + +.. versionchanged:: 2.8 + + The ``WAGTAILEMBEDS_RESPONSIVE_HTML`` setting was added. Previous versions always added the class and style attributes. + Internal links (tag) ~~~~~~~~~~~~~~~~~~~~