Docs for dynamic image serve view

docs/advanced_topics/images/image_serve_view.rst

@@ -0,0 +1,96 @@
+.. _using_images_outside_wagtail:
+
+========================
+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.
+
+The view takes an image id, filter spec and security key in the URL. If these
+parameters are valid, it serves an image file matching that criteria.
+
+Like the ``{% image %}`` tag, the rendition is generated on the first call and
+subsequent calls are served from a cache.
+
+Setup
+=====
+
+Add an entry for the view into your URLs configuration:
+
+ .. code-block:: python
+
+    from wagtail.wagtailimages.views.serve import ServeView
+
+    urlpatterns = [
+        ...
+
+        url(r'^images/([^/]*)/(\d*)/([^/]*)/[^/]*$', ServeView.as_view(), name='wagtailimages_serve'),
+    ]
+
+Usage
+=====
+
+Image URL generator UI
+----------------------
+
+When the dynamic serve view is enabled, an image URL generator in the admin
+interface becomes available automatically. This can be accessed through the edit
+page of any image by clicking the "URL generator" button on the right hand side.
+
+This interface allows editors to generate URLs to cropped versions of the image.
+
+Generating dynamic image URLs in Python
+---------------------------------------
+
+Dynamic image URLs can also be generated using Python code and served to a
+client over an API or used directly in the template.
+
+One advantage of using dynamic image URLs in the template is that they do not
+block the initial response while rendering like the ``{% image %}`` tag does.
+
+.. code-block:: python
+
+    from django.core.urlresolvers import reverse
+    from wagtail.wagtailimages.utils import generate_signature
+
+    def generate_image_url(image, filter_spec):
+        signature = generate_signature(image.id, filter_spec)
+        url = reverse('wagtailimages_serve', args=(signature, image.id, filter_spec))
+
+        # Append image's original filename to the URL (optional)
+        url += image.file.name[len('original_images/'):]
+
+        return url
+
+And here's an example of this being used in a view:
+
+.. code-block:: python
+
+    def display_image(request, image_id):
+        image = get_object_or_404(Image, id=image_id)
+
+        return render(request, 'display_image.html', {
+            'url': generate_image_url(image, 'fill-100x100')
+        })
+
+Making the view redirect instead of serve
+-----------------------------------------
+
+By default, the view will serve the image file directly. This behaviour can be
+changed to a 301 redirect instead which may be useful if you host your images
+externally.
+
+To enable this, pass ``action='redirect'`` into the ``ServeView.as_view()``
+method in your urls configuration:
+
+.. code-block:: python
+
+   from wagtail.wagtailimages.views.serve import ServeView
+
+   urlpatterns = [
+       ...
+
+       url(r'^images/([^/]*)/(\d*)/([^/]*)/[^/]*$', ServeView.as_view(action='redirect'), name='wagtailimages_serve'),
+   ]

docs/advanced_topics/images/index.rst

@@ -8,4 +8,4 @@ Images
     animated_gifs
     custom_image_model
     feature_detection
-    using_images_outside_wagtail
+    image_serve_view

docs/advanced_topics/images/using_images_outside_wagtail.rst

@@ -1,74 +0,0 @@
-.. _using_images_outside_wagtail:
-
-============================
-Using images outside Wagtail
-============================
-
-Wagtail provides a way for you to generate external URLs for images in your image library which you can use to display your images on external sites.
-
-
-Setup
-=====
-
-Add an entry in your URLs configuration for ``wagtail.wagtailimages.urls``:
-
- .. code-block:: python
-
-    from wagtail.wagtailimages import urls as wagtailimages_urls
-
-
-    urlpatterns = [
-        ...
-
-        url(r'^images/', include(wagtailimages_urls)),
-    ]
-
-
-Generating URLs for images
-==========================
-
-Once the above setup is done, a button should appear under the image preview on the image edit page. Clicking this button will take you to an interface where you can specify the size you want the image to be, and it will generate a URL and a preview of what the image is going to look like.
-
-The filter box lets you choose how you would like the image to be resized:
-
-
-.. glossary::
-    ``Original`` 
-
-        Leaves the image at its original size - no resizing is performed.
-
-    ``Resize to max`` 
-
-        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.
-
-    ``Resize to min`` 
-
-        **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.
-
-    ``Resize to width`` 
-
-        Reduces the width of the image to the dimension specified.
-
-    ``Resize to height`` 
-
-        Resize the height of the image to the dimension specified.. 
-
-    ``Resize to fill`` 
-
-        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. 
-
-
-Using the URLs on your website or blog
-======================================
-
-Once you have generated a URL, you can put it straight into the ``src`` attribute of an ``<img>`` tag:
-
- .. code-block:: html
-
-    <img src="(image url here)">