Skip to main content

User-configurable, blob-aware image scaling for Plone.

Project description


This package tries to factor out and re-use the image scaling code from Archetypes into a separate package in order to make it user-configurable and add support for storing the image data into ZODB blobs.


Version 2.x is for Plone 5 only.


The easiest way to use this package is when working with installations based on zc.buildout. Here you can simply add the package to your “eggs” and “zcml” options, run buildout and restart your Plone instance.

Alternatively you can use the following configuration file to extend an existing buildout:

extends = buildout.cfg

eggs +=
zcml +=

After that you should be able to “quick-install” the package via the “Add-on products” section of Plone’s configuration panel (“Site setup”).

New-style image scales introduces new ways of using image scales in your templates. There are several variants you can pick from depending on how much flexibility/convenience you need:

  1. The tag method generates a complete image tag:

    <img tal:define="scales context/@@images"
         tal:replace="structure python: scales.tag('image',
                      width=1200, height=800, direction='down')"

    While the first call requires the storage to load the image data and extract information for scaling, consecutive calls are cheap because the metadata is stored for each call signature.

    The direction keyword-argument can be used to specify the scaling direction. Additional parameters are rendered as element attributes (typically: “title” and “alt”).

  2. For tag generation using predefined scale names this would look like:

    <img tal:define="scales context/@@images"
         tal:replace="structure python: scales.tag('image', scale='mini')"

    This would use the predefined scale size “mini” to determine the desired image dimensions, but still allow to pass in extra parameters.

  3. The following traversal syntax is a short-cut for tag generation for predefined image scales:

    <img tal:replace="structure context/@@images/image/mini" />
  4. The same syntax may be used for the original image:

    <img tal:replace="structure context/@@images/image" />
  5. The scale method returns an image scale object useful for explicit tag generation:

    <img tal:define="scales context/@@images;
                     thumbnail python: scales.scale('image', width=64, height=64);"
         tal:attributes="src thumbnail/url;
                         width thumbnail/width;
                         height thumbnail/height" />

    This would create an up to 64 by 64 pixel scaled down version of the image stored in the “image” field. It also allows for passing in addition parameters support by plone.scale’s scaleImage function, e.g. direction or quality.

    Note that the scale method loads the actual image data into memory on each invocation.

  6. The image scale object also implements a tag method:

    <img tal:define="scales context/@@images;
                     scale python: scale.scale('image', width=1200, height=800)"
         tal:replace="structure scale/tag" />

    However, it’s recommended to use the tag method of the image scales view directly because it avoids loading the image into memory.

Scaled image direction

Three different scaling options are supported with the direction parameter.

  • up scaling scales the smallest dimension up to the required size and crops the other dimension if needed.

  • down scaling starts by scaling the largest dimension to the required size and crops the other dimension if needed.

  • thumbnail scales to the requested dimensions without cropping. The resulting image may have a different size than requested. This option requires both width and height to be specified. keep is accepted as an alternative spelling for this option, but its use is deprecated.

Scaled image quality

The quality of scaled images can be controlled through the “Imaging” control panel.

This will only take effect for images that have not been scaled yet. To re-scale existing images with an updated quality setting, you’l need to go in the ZMI > portal_atct > “Image scales” tab, and click “recreate”. This may take a very long time!


2.1.2 (2021-06-15)

Bug fixes:

  • Fix traversal handling of subobjects with ids that may also be image scales. [rpatterson]

2.1.1 (2019-10-09)

Bug fixes:

  • Fix IOError: cannot write mode RGBA as JPEG on ImageField scale [avoinea]

2.1.0 (2018-10-30)

Bug fixes:

  • Switch to new TestCase using AT after PloneTestcase is now DX. [pbauer]

2.0.7 (2018-02-05)

Bug fixes:

  • Imports are Python3 compatible [ale-rt]

2.0.6 (2016-12-19)

Bug fixes:

  • Add coding headers on python files. [gforcada]

  • Remove vestigial requirement of [davisagli]

2.0.5 (2016-08-17)

Bug fixes:

  • Use zope.interface decorator. [gforcada]

2.0.4 (2016-06-07)


  • Fix tests to not scale gif images, which were converted to jpeg imaged until plone.scale version < 2. Use png images for testing instead, which works for all versions of plone.scale. [thet]

2.0.3 (2016-02-20)


  • Fix test to not check for the concrete WebDAV content type header. Needed for Zope 4 compatibility. [thet]

2.0.2 (2016-01-08)


  • Added documentation for what the ‘direction’ parameter actually does. [shadowmint]

2.0.1 (2015-11-26)


  • Fixed incompatibilities with and chameleon (closes #16). [rodfersou, maurits]

  • Fixed 404 NotFound error when accessing image scales via webdav. [maurits]

2.0.0 (2015-05-11)

  • Move control panel to Products.CMFPlone [vangheem]

  • Remove unused import. [gforcada]

  • re-adding imaging doctests. [tomgross]

1.1.2 (2014-10-23)

  • portet tests to [tomgross]

1.1.1 (2014-04-13)

  • Disable csrf protection when scale is generated and traversed to. [vangheem]

1.1.0 (2014-02-23)

  • Cache image scales using the plone.stableResource ruleset when they are accessed via UID-based URLs. [davisagli]

  • Move propertysheet imaging_properties and the corresponding utilities to Products.CMFPlone. [pbauer]

  • Generate Progressive JPEG. [kroman0]

1.0.9 (2013-06-13)

  • Make getQuality always return an integer.

1.0.8 (2013-05-23)

1.0.7 (2013-03-05)

  • Avoid hard dependency on ATContentTypes. [davisagli]

1.0.6 (2012-04-15)

  • Avoid loading an image scale object in order to generate a tag. It’s expensive because it loads the image data into memory. The documentation has been updated to reflect that this is the most efficient usage of the API.

1.0.5 - 2011-04-03

  • Fix test now scale=None does not raise exception. [elro]

1.0.4 - 2011-03-22

  • Add a tag method to @@images to simplify tagging of full sized images. [elro]

  • Make scale=None return the original image wrapped as an ImageScaling object. [elro]

1.0.3 - 2011-02-14

  • Avoid breaking on startup if PIL is not present. [davisagli]

1.0.2 - 2011-02-10

  • Add getAvailableSizes and getImageSize to the @@images view. [elro]

1.0.1 - 2011-01-03

  • Protect the control panel with a custom permission, “Plone Site Setup: Imaging”, instead of the generic “Manage portal”. [davisagli]

1.0 - 2010-07-18

  • Use the standard libraries doctest module. [hannosch]

  • Update license to GPL version 2 only. [hannosch]

1.0b11 - 2010-07-01

  • Fix issue with creating scales based on Image objects that are storing their data as chained Pdata objects. [davisagli]

  • Avoid using the deprecated five:implements directive. [hannosch]

1.0b10 - 2010-05-01

1.0b9 - 2010-04-10

  • Add new syntax options for generating image scales based on ideas borrowed from plone.scale, also improving caching and invalidation. [witsch]

  • Provide sizes for plone.namedfile if it’s installed. [davisagli]

  • Restore possibility to define per-field image scale sizes. This refs [huub_bouma, witsch]

1.0b8 - 2010-03-06

1.0b7 - 2009-12-03

  • Swallow resizing exceptions if that flag is set on the image field. [matthewwilkes]

  • Add test to make sure traversal to scales in path expressions still works. [davisagli, witsch]

1.0b6 - 2009-11-18

  • Corrected ill-formed msgid that contained a double quote. [hannosch]

1.0b5 - 2009-11-15

1.0b4 - 2009-10-29

  • Refactor default scale handler to make it more reusable for the blob-enabled version in [witsch]

1.0b3 - 2009-08-26

  • Fix compatibility issue with Plone 4.0. [witsch]

  • Revert deferral of monkey-patching and traversal adapter registration to package installation time. [witsch]

1.0b2 - 2009-07-08

  • Register traversal handler locally to avoid problems without the corresponding monkey patch in place. Please see the second issue in for more info. [witsch]

  • Replaced a getUtility with a queryUtility call in getAllowedSizes. [hannosch]

1.0b1 - 2009-05-14

  • Add fallback for determining available image sizes to avoid breaking sites which haven’t installed the package yet. [witsch]

1.0a2 - 2008-09-22

  • Fix getAvailableSizes to not depend on sizes field-attribute. [witsch]

1.0a1 - 2008-08-12

  • Initial version [witsch]

  • Initial package structure. [zopeskel]

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution (40.5 kB view hashes)

Uploaded source

Built Distribution (38.5 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page