From 12fc3e6601dcdc35764f9104b3f93289f90095bb Mon Sep 17 00:00:00 2001 From: Dave Cranwell Date: Thu, 17 Sep 2015 16:41:00 +0100 Subject: [PATCH] Fixes #1600. Adds documentation and caveats about image formats system within rich text --- .../customisation/page_editing_interface.rst | 9 ++++++- docs/topics/images/using_in_templates.rst | 27 +++++++++++++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/docs/advanced_topics/customisation/page_editing_interface.rst b/docs/advanced_topics/customisation/page_editing_interface.rst index 9e4161ce0e..17e22a7b96 100644 --- a/docs/advanced_topics/customisation/page_editing_interface.rst +++ b/docs/advanced_topics/customisation/page_editing_interface.rst @@ -35,6 +35,8 @@ As standard, Wagtail organises panels into three tabs: 'Content', 'Promote' and ]) +.. _rich-text: + Rich Text (HTML) ~~~~~~~~~~~~~~~~ @@ -74,6 +76,8 @@ To inject JavaScript into the Wagtail page editor, see the :ref:`insert_editor_j For information on developing custom ``hallo.js`` plugins, see the project's page: https://github.com/bergie/hallo +.. _rich_text_image_formats: + Image Formats in the Rich Text Editor ------------------------------------- @@ -98,7 +102,10 @@ To begin, import the the ``Format`` class, ``register_image_format`` function, a The label used in the chooser form when inserting the image into the :class:`~wagtail.wagtailcore.fields.RichTextField`. ``classnames`` - The string to assign to the ``class`` attribute of the generated ```` tag. + The string to assign to the ``class`` attribute of the generated ```` tag. + + .. note:: + Any class names you provide must have CSS rules matching them written separately, as part of the front end CSS code. Specifying a ``classnames`` value of ``left`` will only ensure that class is output in the generated markup, it won't cause the image to align itself left. ``filter_spec`` The string specification to create the image rendition. For more, see the :ref:`image_tag`. diff --git a/docs/topics/images/using_in_templates.rst b/docs/topics/images/using_in_templates.rst index 7e1f80a3a0..4aa8e30a80 100644 --- a/docs/topics/images/using_in_templates.rst +++ b/docs/topics/images/using_in_templates.rst @@ -170,3 +170,30 @@ You can also use the ``attrs`` property as a shorthand to output the attributes .. code-block:: django + + +Images embedded in rich text +---------------------------- + +The information above relates to images defined via image-specific fields in your model, but images can also be embedded arbitrarily in Rich Text fields by the editor (see :ref:`rich-text`). + +Images embedded in Rich Text fields can't be controlled by the template developer as easily. There are no image objects to work with, so the ``{% image %}`` template tag can't be used. Instead editors can choose from one of a number of image "Formats" at the point of inserting images into their text. + +Wagtail comes with three pre-defined image formats, but more can be defined in Python by the developer. These formats are: + +.. glossary:: + + ``Full width`` + Creates an image tag using the filter ``width-800`` and given the CSS class ``full-width`` + + ``Left-aligned`` + Creates an image tag with the filter ``width-500`` and given the CSS class ``left`` + + ``Right-aligned`` + Creates an image tag with the filter ``width-500`` and given the CSS class ``right`` + +.. Note:: + + The CSS classes added to images do **not** come with any accompanying stylesheets, or inline styles. e.g the ``left`` class will do nothing, by default. The developer is expected to add these classes to their front end CSS files, to define what exactly ``left``, ``right`` or ``full-width`` means *to them*. + +For more information about image formats, including creating your own, see :ref:`rich_text_image_formats`