This type encapsulates a single uploaded image along with an optional number of
derived images like thumbnails. Both the main image and the derived thumbnails
will be run through a defined filter chain. The originally uploaded file can be
kept optionally.
The original image will be available under the "original" identifier unless
configured otherwise. The main image used for display is available as "main",
which will be ensured to be web-compatible. (This
distinction is important in case you upload TIFF or other non-web-compatible
images. All derived images will be available under the names defined in the schema
configuration.
An optional "quick" thumbnail mode is available as well where you just specify the
maximum frame of a thumbnail to-be-generated. The auto-generated image will then be
available in the attachment identified as "thumbnail".
The class uses the image filter system for the actual resizing and conversion work,
you need to specify all operations including resize operations in the filtering
chain declaration for the corresponding derived image.
Regarding file type conversions: The original uploaded image will always be run through
an automatic type conversion as the very first step before any further processing is
done. From that point, no further type conversion is done unless the user specifies
another one in the filter chains for a derived type. A manual initial image conversion
is not yet supported by the type.
All derived images will be computed from the initially converted, uploaded image,
which should minimize the losses of the subsequent conversions. This intermediate
image will not be kept an any place. The keep_original option will only save the
unmodified, uploaded file.
The recreate_derived_images call will recreate all derived images from
the original image. If that image is not available, the generated main image is used
instead.
Be aware that the type holds no safety code to guard against duplicate image
identifiers (e.g. defining a "main" image in the derived images list). The results
of such a configuration is undefined.
Available configuration options:
- boolean keep_original controls whether you want to keep the originally uploaded
file available. This option is disabled by default.
- string filter_chain The filter chain used to render the main image. This chain
empty (null) by default.
- Array derived_images A list of derived images to construct from the main image.
This option consists of a list of identifier/filter chain declarations. They will
be constructed in order, each using a fresh copy of the (initially type-converted)
original image. This options may be null (the default) indicating no derived
images. Note, that the system will detect any explicit image type conversions
you're doing in a filter chain, setting the attachments' Mime-Type property
automagically.
- Array auto_thumbnail This array holds the maximum size of the thumbnail to create
with automatic defaults. The array holds a maximum width/height pair as first and
second element of the array, nothing else. The image will be available as
"thumbnail". This image will be constructed after constructing all explicitly
defined derived images. This option may be null (the default) indicating no
thumbnail.
- string output_mode Determines if $datamanager->convert_to_html() should return
image as HTML tag ready to use (default) or array type containing all data about
image and derived formats.
Implementation note:
Due to the fact that Imagemagick is used for most operations, this type is currently
only capable of operating based on actual files, not file handles.
Methods
_add_thumbnail_to_derived_images ()
Small internal helper function.
It adds a derived 'thumbnail' image to the list
used if and only if the auto_thumbnail option is set. Any existing thumbnail
declaration will be silently overwritten!
Returns
boolean
Indicating success.
_auto_convert_to_web_type ()
Automatically convert the uploaded file to a web-compatible type.
Uses
only the first image of multi-page uploads (like PDFs) and populates the
_target_mimetype member accordingly. The original_tmpname file is manipulated
directly.
Uploaded GIF, PNG and JPEG files are left untouched.
In case of any conversions being done, the new extension will be appended
to the uploaded file.
Returns
boolean
Indicating success
_clean_pending_attachments ()
_prepare_recreate ($force)
Preparation operations for recreate_xxx()
_rotate_get_filter ($direction)
Converts given direction to imagefilter chain
_save_derived_image (string $identifier)
This is the actual code which filters and saves a derived image.
Parameters
$identifier
string
The derived image to construct.
Returns
boolean
Indicating success
_save_derived_images ()
This loops over the defined derived images (if any) and constructs
each of them in turn.
Returns
boolean
Indicating success.
_save_main_image ()
Saves the main image to the type, doing transformation work if configured to do so.
Returns
boolean
Indicating success.
_save_original ()
If we are configured to do so, we save the original image.
Returns
boolean
Indicating success
_set_image (string $filename, string $tmpname, string $title, boolean $autodelete, array $force_pending_attachments)
Adds the image to the type.
Loads and processes the $tmpname file on disk.
Parameters
$filename
string
The name of the image attachment to be created.
$tmpname
string
The file to load.
$title
string
The title of the image.
$autodelete
boolean
If this is true (the default), the temporary file will
be deleted after postprocessing and attachment-creation.
$force_pending_attachments
array
use this to override pending_attachments (when run from images type)
Returns
boolean
Indicating success.
apply_filter (string $identifier, string $filter)
Applies a filter to image identifier
Parameters
$identifier
string
the image identifier to apply to
$filter
string
the midcom_helper_imagefilter filter chain to apply
Returns
boolean
indicating success/failure
apply_filter_all (string $filter)
Applies a given filter to all (except original) images in the type
Parameters
$filter
string
the midcom_helper_imagefilter filter chain to apply
Returns
boolean
indicating success/failure
convert_from_storage ($source)
Calls the base type to read all attachments, then extracts the title of the
main attachment, if applicable.
convert_to_html ()
The HTML-Version of the image type can take two forms, depending on
type configuration:
- If an 'thumbnail' image is present, it is shown and encapsulated in an
anchor tag leading to the 'main' image.
- If no 'thumbnail' image is present, the 'main' image is shown
directly, without any anchor.
In case that there is no image uploaded, an empty string is returned.
convert_to_storage ()
Updates the attachment titles.
imagemagick_available ($raise_uimessage)
Parameters
$raise_uimessage
recreate ()
Recreate all images
recreate_derived_images ($force_prepare)
Recreates derived images
Parameters
$force_prepare
recreate_main_image ()
recreates main image if original is available
rotate (string $direction)
Rotates applies a rotational filter to all images in the type
Parameters
$direction
string
direction to rotate to
Returns
boolean
indicating success/failure
set_image (string $filename, string $tmpname, string $title, boolean $autodelete)
Public access wrapper for _set_image
Parameters
$filename
string
The name of the image attachment to be created.
$tmpname
string
The file to load.
$title
string
The title of the image.
$autodelete
boolean
If this is true (the default), the temporary file will
be deleted after postprocessing and attachment-creation.
Returns
boolean
Indicating success.
update_image_from_file (string $identifier)
Overwrites image content from file, recalculates size etc
Parameters
$identifier
string
image identifier to update
Returns
boolean
indicating success/failure
Properties
array $auto_thumbnail
The maximum width/height (in this order) of the thumbnail to be auto-created.
The passed values will be given to the rescale function of the imagefilter.
This means that if you want to scale an image only by width, you still have
to set the height parameter to zero (auto_thumbnail => Array(100,0)).
array $derived_images
The list of derived images to construct.
string $filter_chain
The filter chain to use to create the "main" image.
boolean $keep_original
Set this to true to keep the original file available as "original".
string $output_mode
This option taken from data schema controls the way data is output.
Either (default) preformatted tag or plain array() type containing
object data
string $title
The image title entered by the user.
Stored in each attachment's title field.
string $_filename
The original filename of the uploaded file.
\midcom_helper_imagefilter $_filter
The image-filter instance to use.
string $_identifier
The current image identifier to use when operating on images.
string $_original_mimetype
The original mimetype of the uploaded file.
string $_original_tmpname
The name of the original temporary uploaded file (which will already be converted
to a Web-Aware format).
Array $_pending_attachments
This list is used when updating an existing attachment.
It keeps track
of which attachments have been updated already when replacing an existing
image. All attachments still listed here after a set_image call will
be deleted. This keeps attachment GUIDs stable during updates but also
adds resilience against against changed type configuration.
string $_current_tmpname
The current working file.
string $_instance_mode
Whether this instance is handling single image or multiple images
string $_target_mimetype
The target mimetype used after automatic conversion for all
generated images.
boolean $check_imagemagic
Whether to check for imagemagic by running some commands