diff --git a/docs/advanced_topics/images/image_serve_view.rst b/docs/advanced_topics/images/image_serve_view.rst index d7fd0c6eb..1f8ce3827 100644 --- a/docs/advanced_topics/images/image_serve_view.rst +++ b/docs/advanced_topics/images/image_serve_view.rst @@ -4,9 +4,11 @@ Dynamic image serve view ======================== -Wagtail provides a view for dynamically generating renditions of images. It can -be called by an external system (eg a blog or mobile app) or used internally as -an alternative to Wagtail's ``{% image %}`` tag. +In most cases, developers wanting to generate image renditions in Python should use the ``get_rendition()`` +method. See :ref:`image_renditions`. + +If you need to be able to generate image versions for an *external* system such as a blog or mobile app, +Wagtail provides a view for dynamically generating renditions of images by calling a unique URL. The view takes an image id, filter spec and security signature in the URL. If these parameters are valid, it serves an image file matching that criteria. diff --git a/docs/advanced_topics/images/index.rst b/docs/advanced_topics/images/index.rst index dca928cb1..cade2a015 100644 --- a/docs/advanced_topics/images/index.rst +++ b/docs/advanced_topics/images/index.rst @@ -5,6 +5,7 @@ Images .. toctree:: :maxdepth: 2 + renditions animated_gifs custom_image_model feature_detection diff --git a/docs/advanced_topics/images/renditions.rst b/docs/advanced_topics/images/renditions.rst new file mode 100644 index 000000000..7cbc372e7 --- /dev/null +++ b/docs/advanced_topics/images/renditions.rst @@ -0,0 +1,36 @@ +.. _image_renditions: + +Generating renditions in Python +===================================== + +Rendered versions of original images generated by the Wagtail ``{% image %}`` template tag are called "renditions", +and are stored as new image files in the site's ``[media]/images`` directory on the first invocation. + +Image renditions can also be generated dynamically from Python via the native ``get_rendition()`` method, for example: + + .. code-block:: python + + newimage = myimage.get_rendition('fill-300x150|jpegquality-60') + +If ``myimage`` had a filename of ``foo.jpg``, a new rendition of the image file called +``foo.fill-300x150.jpegquality-60.jpg`` would be generated and saved into the site's ``[media]/images`` directory. +Argument options are identical to the ``{% image %}`` template tag's filter spec, and should be separated with ``|``. + +The generated ``Rendition`` object will have properties specific to that version of the image, such as +``url``, ``width`` and ``height``, so something like this could be used in an API generator, for example: + + .. code-block:: python + + url = myimage.get_rendition('fill-300x186|jpegquality-60').url + +Properties belonging to the original image from which the generated Rendition was created, such as ``title``, can +be accessed through the Rendition's ``image`` property: + + .. code-block:: python + + >>> newimage.image.title + 'Blue Sky' + >>> newimage.image.is_landscape() + True + +See also: :ref:`image_tag` diff --git a/docs/topics/images.rst b/docs/topics/images.rst index 3f1d17664..5b16fe1d0 100644 --- a/docs/topics/images.rst +++ b/docs/topics/images.rst @@ -271,3 +271,9 @@ all images to output in JPEG format): .. code-block:: html+Django {% image page.photo width-400 format-jpeg jpegquality-40 %} + +Generating image renditions in Python +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +All of the image transformations mentioned above can also be used directly in Python code. +See :ref:`image_renditions`.