diff --git a/docs/core_components/images/index.rst b/docs/core_components/images/index.rst index fcae2d837..6e9fde238 100644 --- a/docs/core_components/images/index.rst +++ b/docs/core_components/images/index.rst @@ -1,6 +1,172 @@ Images ====== + +.. _image_tag: + +Using images in templates +========================= + +.. versionchanged:: 0.4 + The 'image_tags' tags library was renamed to 'wagtailimages_tags' + +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:: django + + {% load wagtailimages_tags %} + ... + + {% image self.photo width-400 %} + + + {% 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:: django + + {% image self.photo max-1000x500 %} + + Fit **within** the given dimensions. + + The longest edge will be reduced to the equivalent dimension size defined. e.g 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:: 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 it's height and width changed to 500, i.e matching the width required, but greater than the height. + + ``width`` + (takes one dimension) + + .. code-block:: django + + {% image self.photo width-640 %} + + Reduces the width of the image to the dimension specified. + + ``height`` + (takes one dimension) + + .. code-block:: django + + {% image self.photo height-480 %} + + Resize the height of the image to the dimension specified.. + + ``fill`` + (takes two dimensions) + + .. code-block:: 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. + + **The crop always aligns on the centre of the image.** + + ``original`` + (takes no dimensions) + + .. code-block:: 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 their native dimensions. + + +.. _image_tag_alt: + +More control over the ``img`` tag +--------------------------------- + +Wagtail provides two shorcuts to give greater control over the ``img`` element: + +**1. Adding attributes to the {% image %} tag** + +.. versionadded:: 0.4 + +Extra attributes can be specified with the syntax ``attribute="value"``: + +.. code-block:: 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:: django + + {% image self.photo width-400 as tmp_photo %} + + {{ tmp_photo.alt }} + + +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 +----------------------- + +.. versionadded:: 0.4 + +You can also use the ``attrs`` property as a shorthand to output the attributes ``src``, ``width``, ``height`` and ``alt`` in one go: + +.. code-block:: django + + + + + +Advanced topics +=============== + .. toctree:: :maxdepth: 2 diff --git a/docs/core_components/pages/writing_templates.rst b/docs/core_components/pages/writing_templates.rst index 3d1380115..7a879c92e 100644 --- a/docs/core_components/pages/writing_templates.rst +++ b/docs/core_components/pages/writing_templates.rst @@ -86,13 +86,9 @@ Template tags & filters In addition to Django's standard tags and filters, Wagtail provides some of its own, which can be ``load``-ed `as you would any other `_ -.. _image_tag: - Images (tag) ~~~~~~~~~~~~ -.. versionchanged:: 0.4 - The 'image_tags' tags library was renamed to 'wagtailimages_tags' 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`. @@ -112,139 +108,8 @@ For example: {% 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:: django - - {% image self.photo max-1000x500 %} - - Fit **within** the given dimensions. - - The longest edge will be reduced to the equivalent dimension size defined. e.g 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:: 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 it's height and width changed to 500, i.e matching the width required, but greater than the height. - - ``width`` - (takes one dimension) - - .. code-block:: django - - {% image self.photo width-640 %} - - Reduces the width of the image to the dimension specified. - - ``height`` - (takes one dimension) - - .. code-block:: django - - {% image self.photo height-480 %} - - Resize the height of the image to the dimension specified.. - - ``fill`` - (takes two dimensions) - - .. code-block:: 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. - - **The crop always aligns on the centre of the image.** - - ``original`` - (takes no dimensions) - - .. code-block:: 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 their native dimensions. - - -.. _image_tag_alt: - -More control over the ``img`` tag ---------------------------------- - -Wagtail provides two shorcuts to give greater control over the ``img`` element: - -**1. Adding attributes to the {% image %} tag** - -.. versionadded:: 0.4 - -Extra attributes can be specified with the syntax ``attribute="value"``: - -.. code-block:: 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:: django - - {% image self.photo width-400 as tmp_photo %} - - {{ tmp_photo.alt }} - - -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 ------------------------ - -.. versionadded:: 0.4 - -You can also use the ``attrs`` property as a shorthand to output the attributes ``src``, ``width``, ``height`` and ``alt`` in one go: - -.. code-block:: django - - +See :ref:`image_tag` for full documentation. .. _rich-text-filter: