Merge pull request #306 from gasman/feature/issue128

Add 'original' as a resize rule supported by the image tag - fixes #128

CHANGELOG.txt

@@ -2,7 +2,8 @@ Changelog
 =========
 
 0.4 (xx.xx.20xx)
-~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~
+ * Added 'original' as a resizing rule supported by the 'image' tag
 
 0.3.1 (03.06.2014)
 ~~~~~~~~~~~~~~~~~~

docs/building_your_site/frontenddevelopers.rst

@@ -94,7 +94,7 @@ The ``image`` tag inserts an XHTML-compatible ``img`` element into the page, set
 
 The syntax for the tag is thus::
 
-    {% image [image] [method]-[dimension(s)] %}
+    {% image [image] [resize-rule] %}
 
 For example:
 
@@ -108,16 +108,20 @@ For example:
     <!-- or a square thumbnail: -->
     {% image self.photo fill-80x80 %}
 
-In the above syntax ``[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 ``[method]`` defines which resizing algorithm to use and ``[dimension(s)]`` provides height and/or width values (as ``[width|height]`` or ``[width]x[height]``) to refine that algorithm.
+In the above syntax ``[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 ``[method]``, but not ``[method]`` and ``[dimensions]``: a hyphen between ``[method]`` and ``[dimensions]`` is mandatory. Multiple dimensions must be separated by an ``x``.
+Note that a space separates ``[image]`` and ``[resize-rule]``, but the resize rule must not contain spaces.
 
-The available ``method`` s are:
+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.
@@ -125,6 +129,10 @@ The available ``method`` s are:
     ``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.
@@ -132,27 +140,45 @@ The available ``method`` s are:
     ``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.**
 
-.. 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.
+    ``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 make the "original" version of an image explicitly available. To request it, you could rely on the lack of upscaling by requesting an image larger than its maximum dimensions. e.g to insert an image whose dimensions are unknown at its maximum size, try: ``{% image self.image width-10000 %}``. This assumes the image is unlikely to be larger than 10000px wide.
+    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:

wagtail/wagtailimages/backends/base.py

@@ -130,3 +130,8 @@ class BaseImageBackend(object):
         """
         resized_image = self.resize_to_min(image, size)
         return self.crop_to_centre(resized_image, size)
+
+
+    def no_operation(self, image, param):
+        """Return the image unchanged"""
+        return image

wagtail/wagtailimages/models.py

@@ -1,5 +1,6 @@
 import StringIO
 import os.path
+import re
 
 from taggit.managers import TaggableManager
 
@@ -150,6 +151,7 @@ class Filter(models.Model):
         'width': 'resize_to_width',
         'height': 'resize_to_height',
         'fill': 'resize_to_fill',
+        'original': 'no_operation',
     }
 
     def __init__(self, *args, **kwargs):
@@ -157,22 +159,34 @@ class Filter(models.Model):
         self.method = None  # will be populated when needed, by parsing the spec string
 
     def _parse_spec_string(self):
-        # parse the spec string, which is formatted as (method)-(arg),
-        # and save the results to self.method_name and self.method_arg
-        try:
-            (method_name_simple, method_arg_string) = self.spec.split('-')
-            self.method_name = Filter.OPERATION_NAMES[method_name_simple]
+        # parse the spec string and save the results to
+        # self.method_name and self.method_arg. There are various possible
+        # formats to match against:
+        # 'original'
+        # 'width-200'
+        # 'max-320x200'
 
-            if method_name_simple in ('max', 'min', 'fill'):
-                # method_arg_string is in the form 640x480
-                (width, height) = [int(i) for i in method_arg_string.split('x')]
-                self.method_arg = (width, height)
-            else:
-                # method_arg_string is a single number
-                self.method_arg = int(method_arg_string)
+        if self.spec == 'original':
+            self.method_name = Filter.OPERATION_NAMES['original']
+            self.method_arg = None
+            return
 
-        except (ValueError, KeyError):
-            raise ValueError("Invalid image filter spec: %r" % self.spec)
+        match = re.match(r'(width|height)-(\d+)$', self.spec)
+        if match:
+            self.method_name = Filter.OPERATION_NAMES[match.group(1)]
+            self.method_arg = int(match.group(2))
+            return
+
+        match = re.match(r'(max|min|fill)-(\d+)x(\d+)$', self.spec)
+        if match:
+            self.method_name = Filter.OPERATION_NAMES[match.group(1)]
+            width = int(match.group(2))
+            height = int(match.group(3))
+            self.method_arg = (width, height)
+            return
+
+        # Spec is not one of our recognised patterns
+        raise ValueError("Invalid image filter spec: %r" % self.spec)
 
     def process_image(self, input_file, backend_name='default'):
         """

wagtail/wagtailimages/tests.py

@@ -107,6 +107,13 @@ class TestRenditions(TestCase):
         self.assertEqual(rendition.width, 160)
         self.assertEqual(rendition.height, 120)
 
+    def test_resize_to_original(self):
+        rendition = self.image.get_rendition('original')
+
+        # Check size
+        self.assertEqual(rendition.width, 640)
+        self.assertEqual(rendition.height, 480)
+
     def test_cache(self):
         # Get two renditions with the same filter
         first_rendition = self.image.get_rendition('width-400')
@@ -153,6 +160,13 @@ class TestRenditionsWand(TestCase):
         self.assertEqual(rendition.width, 160)
         self.assertEqual(rendition.height, 120)
 
+    def test_resize_to_original(self):
+        rendition = self.image.get_rendition('original')
+
+        # Check size
+        self.assertEqual(rendition.width, 640)
+        self.assertEqual(rendition.height, 480)
+
     def test_cache(self):
         # Get two renditions with the same filter
         first_rendition = self.image.get_rendition('width-400')