Package: plone.app.imaging
IntroductionThis package tries to factor out and re-use the image scaling code fromArchetypesinto a separate package in order to make it user-configurable
and add support for storing the image data into ZODBblobs.WarningVersion 2.x is for Plone 5 only.InstallationThe easiest way to use this package is when working with installations
based onzc.buildout.  Here you can simply add the package to your “eggs”
and “zcml” options, run buildout and restart yourPloneinstance.Alternatively you can use the following configuration file to extend an
existing buildout:[buildout]
extends = buildout.cfg

[instance]
eggs += plone.app.imaging
zcml += plone.app.imagingAfter that you should be able to “quick-install” the package via the
“Add-on products” section ofPlone’s configuration panel (“Site setup”).New-style image scalesplone.app.imagingintroduces 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:Thetagmethod 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.Thedirectionkeyword-argument can be used to specify the
scaling direction. Additional parameters are rendered as element
attributes (typically: “title” and “alt”).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.The following traversal syntax is a short-cut for tag generation
for predefined image scales:<img tal:replace="structure context/@@images/image/mini" />The same syntax may be used for the original image:<img tal:replace="structure context/@@images/image" />Thescalemethod 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:condition="thumbnail"
     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 byplone.scale’sscaleImagefunction, e.g.directionorquality.Note that thescalemethod loads the actual image data into
memory on each invocation.The image scale object also implements atagmethod:<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 thetagmethod of the image
scales view directly because it avoids loading the image into memory.Scaled image directionThree different scaling options are supported with thedirectionparameter.upscaling scales the smallest dimension up to the required size
and crops the other dimension if needed.downscaling starts by scaling the largest dimension to the required
size and crops the other dimension if needed.thumbnailscales 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.keepis accepted as
an alternative spelling for this option, but its use is deprecated.Scaled image qualityThe 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!Changelog2.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 plone.app.controlpanel.
[davisagli]2.0.5 (2016-08-17)Bug fixes:Use zope.interface decorator.
[gforcada]2.0.4 (2016-06-07)Fixes:Fix tests to not scalegifimages, which were converted tojpegimaged untilplone.scaleversion < 2.
Usepngimages for testing instead, which works for all versions of plone.scale.
[thet]2.0.3 (2016-02-20)Fixes:Fix test to not check for the concrete WebDAV content type header.
Needed for Zope 4 compatibility.
[thet]2.0.2 (2016-01-08)New:Added documentation for what the ‘direction’ parameter actually
does.  [shadowmint]2.0.1 (2015-11-26)Fixes:Fixed incompatibilities with five.pt 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 plone.app.testing
[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.https://github.com/plone/plone.app.contenttypes/issues/82[pbauer]Generate Progressive JPEG.
[kroman0]1.0.9 (2013-06-13)Make getQuality always return an integer.1.0.8 (2013-05-23)Make the quality of scaled images configurable through the configlet.https://dev.plone.org/ticket/13337[khink]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-03Fix test nowscale=Nonedoes not raise exception.
[elro]1.0.4 - 2011-03-22Add 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-14Avoid breaking on startup if PIL is not present.
[davisagli]1.0.2 - 2011-02-10Add getAvailableSizes and getImageSize to the @@images view.
[elro]1.0.1 - 2011-01-03Protect the control panel with a custom permission,
“Plone Site Setup: Imaging”, instead of the generic “Manage portal”.
[davisagli]1.0 - 2010-07-18Use the standard libraries doctest module.
[hannosch]Update license to GPL version 2 only.
[hannosch]1.0b11 - 2010-07-01Fix 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-01Use plone i18n domain instead of plone.app.imaging domain for the
MessageFactory. This closeshttp://dev.plone.org/plone/ticket/10478[vincentfretin]Fix dependency onplone.scaleto get requirements for the scale storage.
[witsch]Fix logic bug in url traversal code for image scales.
This fixeshttp://plone.org/products/plone.app.imaging/issues/1[ramonski, witsch]Add support for custom scales for “News Item” content.
This refshttp://dev.plone.org/plone/ticket/10250[pelle, witsch]Removed dependency declaration for the unused uuid distribution.
[hannosch]Fix control panel definition so that its icon shows up again.
[witsch]1.0b9 - 2010-04-10Add new syntax options for generating image scales based on ideas
borrowed fromplone.scale, also improving caching and invalidation.
[witsch]Provide sizes forplone.namedfileif it’s installed.
[davisagli]Restore possibility to define per-field image scale sizes.
This refshttp://dev.plone.org/plone/ticket/10159[huub_bouma, witsch]1.0b8 - 2010-03-06Convert test setup to usecollective.testcaselayer.
[witsch]Add monkey-patch forcreateScalesin order to fix recreation of scales.
This refshttp://dev.plone.org/plone/ticket/10186[witsch]1.0b7 - 2009-12-03Swallow 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-18Corrected ill-formed msgid that contained a double quote.
[hannosch]1.0b5 - 2009-11-15Allow white space within image scale definitions.
This fixeshttp://dev.plone.org/plone/ticket/9207[amleczko]1.0b4 - 2009-10-29Refactor default scale handler to make it more reusable for the
blob-enabled version inplone.app.blob[witsch]1.0b3 - 2009-08-26Fix 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-08Register traversal handler locally to avoid problems without the
corresponding monkey patch in place.  Please see the second issue inhttp://plone.org/products/plone.app.blob/issues/19for more info.
[witsch]Replaced a getUtility with a queryUtility call in getAllowedSizes.
[hannosch]1.0b1 - 2009-05-14Add fallback for determining available image sizes to avoid breaking
sites which haven’t installed the package yet.
[witsch]1.0a2 - 2008-09-22FixgetAvailableSizesto not depend onsizesfield-attribute.
[witsch]1.0a1 - 2008-08-12Initial version
[witsch]Initial package structure.
[zopeskel]