mirror of
https://github.com/wagtail/wagtail.git
synced 2024-11-30 01:46:24 +01:00
bc6b5a8a6c
All `.. code::` instances have been changed to use `.. code-block::`, and have been properly formatted. The syntax names have been normalised, so all django templates use the `html+django` syntax, shell commands use `sh`, and plain text uses `text`.
200 lines
8.2 KiB
ReStructuredText
200 lines
8.2 KiB
ReStructuredText
.. _image_tag:
|
|
|
|
Using images in templates
|
|
=========================
|
|
|
|
The ``image`` tag inserts an XHTML-compatible ``img`` element into the page, setting its ``src``, ``width``, ``height`` and ``alt``. See also :ref:`image_tag_alt`.
|
|
|
|
The syntax for the tag is thus::
|
|
|
|
{% image [image] [resize-rule] %}
|
|
|
|
For example:
|
|
|
|
.. code-block:: html+django
|
|
|
|
{% load wagtailimages_tags %}
|
|
...
|
|
|
|
{% image self.photo width-400 %}
|
|
|
|
<!-- or a square thumbnail: -->
|
|
{% image self.photo fill-80x80 %}
|
|
|
|
In the above syntax example ``[image]`` is the Django object refering to the image. If your page model defined a field called "photo" then ``[image]`` would probably be ``self.photo``. The ``[resize-rule]`` defines how the image is to be resized when inserted into the page; various resizing methods are supported, to cater for different usage cases (e.g. lead images that span the whole width of the page, or thumbnails to be cropped to a fixed size).
|
|
|
|
Note that a space separates ``[image]`` and ``[resize-rule]``, but the resize rule must not contain spaces.
|
|
|
|
|
|
The available resizing methods are:
|
|
|
|
|
|
.. glossary::
|
|
|
|
``max``
|
|
(takes two dimensions)
|
|
|
|
.. code-block:: html+django
|
|
|
|
{% image self.photo max-1000x500 %}
|
|
|
|
Fit **within** the given dimensions.
|
|
|
|
The longest edge will be reduced to the equivalent dimension size defined. For example, a portrait image of width 1000, height 2000, treated with the ``max`` dimensions ``1000x500`` (landscape) would result in the image shrunk so the *height* was 500 pixels and the width 250.
|
|
|
|
``min``
|
|
(takes two dimensions)
|
|
|
|
.. code-block:: html+django
|
|
|
|
{% image self.photo min-500x200 %}
|
|
|
|
**Cover** the given dimensions.
|
|
|
|
This may result in an image slightly **larger** than the dimensions you specify. e.g A square image of width 2000, height 2000, treated with the ``min`` dimensions ``500x200`` (landscape) would have its height and width changed to 500, i.e matching the width required, but greater than the height.
|
|
|
|
``width``
|
|
(takes one dimension)
|
|
|
|
.. code-block:: html+django
|
|
|
|
{% image self.photo width-640 %}
|
|
|
|
Reduces the width of the image to the dimension specified.
|
|
|
|
``height``
|
|
(takes one dimension)
|
|
|
|
.. code-block:: html+django
|
|
|
|
{% image self.photo height-480 %}
|
|
|
|
Resize the height of the image to the dimension specified..
|
|
|
|
``fill``
|
|
(takes two dimensions and an optional ``-c`` parameter)
|
|
|
|
.. code-block:: html+django
|
|
|
|
{% image self.photo fill-200x200 %}
|
|
|
|
Resize and **crop** to fill the **exact** dimensions.
|
|
|
|
This can be particularly useful for websites requiring square thumbnails of arbitrary images. For example, a landscape image of width 2000, height 1000, treated with ``fill`` dimensions ``200x200`` would have its height reduced to 200, then its width (ordinarily 400) cropped to 200.
|
|
|
|
This filter will crop to the image's focal point if it has been set. If not, it will crop to the centre of the image.
|
|
|
|
**On images that won't upscale**
|
|
|
|
It's possible to request an image with ``fill`` dimensions that the image can't support without upscaling. e.g an image 400x200 requested with ``fill-400x400``. In this situation the *ratio of the requested fill* will be matched, but the dimension will not. So with that example 400x200 image, the resulting image will be 200x200.
|
|
|
|
**Cropping closer to the focal point**
|
|
|
|
By default, Wagtail will only crop to change the aspect ratio of the image.
|
|
|
|
In some cases (thumbnails, for example) it may be nice to crop closer to the focal point so the subject of the image is easier to see.
|
|
|
|
You can do this by appending ``-c<percentage>`` at the end of the method. For example, if you would like the image to be cropped as closely as possible to its focal point, add ``-c100`` to the end of the method.
|
|
|
|
.. code-block:: html+django
|
|
|
|
{% image self.photo fill-200x200-c100 %}
|
|
|
|
This will crop the image as much as it can, but will never crop into the focal point.
|
|
|
|
If you find that ``-c100`` is too close, you can try ``-c75`` or ``-c50`` (any whole number from 0 to 100 is accepted).
|
|
|
|
``original``
|
|
(takes no dimensions)
|
|
|
|
.. code-block:: html+django
|
|
|
|
{% image self.photo original %}
|
|
|
|
Leaves the image at its original size - no resizing is performed.
|
|
|
|
|
|
|
|
.. Note::
|
|
Wagtail does not allow deforming or stretching images. Image dimension ratios will always be kept. Wagtail also *does not support upscaling*. Small images forced to appear at larger sizes will "max out" at their native dimensions.
|
|
|
|
|
|
.. _image_tag_alt:
|
|
|
|
More control over the ``img`` tag
|
|
---------------------------------
|
|
|
|
Wagtail provides two shortcuts to give greater control over the ``img`` element:
|
|
|
|
**1. Adding attributes to the {% image %} tag**
|
|
|
|
Extra attributes can be specified with the syntax ``attribute="value"``:
|
|
|
|
.. code-block:: html+django
|
|
|
|
{% image self.photo width-400 class="foo" id="bar" %}
|
|
|
|
No validation is performed on attributes added in this way so it's possible to add `src`, `width`, `height` and `alt` of your own that might conflict with those generated by the tag itself.
|
|
|
|
|
|
**2. Generating the image "as foo" to access individual properties**
|
|
|
|
Wagtail can assign the image data to another variable using Django's ``as`` syntax:
|
|
|
|
.. code-block:: html+django
|
|
|
|
{% image self.photo width-400 as tmp_photo %}
|
|
|
|
<img src="{{ tmp_photo.url }}" width="{{ tmp_photo.width }}"
|
|
height="{{ tmp_photo.height }}" alt="{{ self.photo.title }}" class="my-custom-class" />
|
|
|
|
|
|
This syntax exposes the underlying image "Rendition" (``tmp_photo``) to the developer. A "Rendition" contains just the information specific to the way you've requested to format the image i.e dimensions and source URL.
|
|
|
|
If your site defines a custom image model using ``AbstractImage``, then any additional fields you add to an image e.g a copyright holder, are **not** part of the image *rendition*, they're part of the image *model*.
|
|
|
|
Therefore in the above example, if you'd added the field ``foo`` to your AbstractImage you'd access it using ``{{ self.photo.foo }}`` not ``{{ tmp_photo.foo }}``.
|
|
|
|
(Due to the links in the database between renditions and their parent image, you could also access it as ``{{ tmp_photo.image.foo }}`` but this is clearly confusing.)
|
|
|
|
|
|
.. Note::
|
|
The image property used for the ``src`` attribute is actually ``image.url``, not ``image.src``.
|
|
|
|
|
|
The ``attrs`` shortcut
|
|
-----------------------
|
|
|
|
You can also use the ``attrs`` property as a shorthand to output the attributes ``src``, ``width``, ``height`` and ``alt`` in one go:
|
|
|
|
.. code-block:: html+django
|
|
|
|
<img {{ tmp_photo.attrs }} class="my-custom-class" />
|
|
|
|
|
|
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`
|