.. _index:
***************************************************************
:mod:`plone.scale` -- Image scaling logic
***************************************************************
:Author: Simplon / Wichert Akkerman
:Version: |version|
.. module:: plone.scale
:synopsis: Plone image scaling framework
:mod:`plone.scale` contains basic image scaling logic for use in Zope
environments. It supports Zope 2, grok and other systems build on using the
Zope ToolKit (ZTK).
Several design goals were used when writing this package:
- image scaling to any width, height, width&height should be supported
using both up-scaling and down-scaling. Scaling parameters should never
be fixed in code. This allows designers to use any image scale they want
without having to modify python code.
- the result of scaling will be an image along with its new size, not a
HTML or XHTML tag. We already have excellent tools to generate tags in
the form of Zope Pagetemplates, Genshi and other template languages that
are much better suited for this purpose.
In addition several implementation goals were defined:
- image scaling must happen on demand instead of up-front. This reduces
initial save time and prevents unnecessary scalings from being generated.
- image scaling parameters should not be part of the generated URL. Since
the number of parameters can change and new parameters may be added in
the future this would create overly complex URLs and URL parsing.
- no HTML rewriting (such as done by `repoze.bitblt`_) should be required.
Rewriting has proven to have too many negative side effects such as
not handling unclean markup correctly, lossing DOCTYPEs or switching between
HTML and XHTML, all of which can have very undesirable effects. In addition
it will have a performance penalty.
- it should be possibly to develop an external storage system which stores
scaled images externally and returns a URL which bypasses the application
server. This should be configurable via just a filesystem path & base
URL.
- minimum number of external dependencies, allowing this package to be
used in many environments.
- testable without requiring zope.testing. Running ``setup.py test`` should
be sufficient.
- URLs for scaled images should have an extension which reflects their
MIME type. This is facilitates cache (and other front-end services)
configuration.
.. _repoze.bitblt: http://pypi.python.org/pypi/repoze.bitblt
Usage
=====
The most common way to use :mod:`plone.scale` is from a HTML template.
In TAL syntax a typical usage looks like this::
This generates a thumbnail of an image field called *logo* with a maximum size
of 64x64 pixels. The dimensions of the resulting image (which might not be
exactly 64x64) are set as attributes on the ``img`` tag to speed up browser
rendering.
If you prefer Genshi syntax and have the :class:`IImageScaleStorage` interface
in scope the syntax looks like this::
Contents
==============
.. toctree::
:maxdepth: 2
narr/scale
narr/storage
changes
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`