OpenPSA API Documentation
Back to top  

Datamanager 2 Video type.

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 ran 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.

todo Implement thumbnail interface.
todo Operation on file handles.
package midcom.helper.datamanager2

 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

booleanIndicating 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

booleanIndicating success

_clean_pending_attachments ()

_clean_pending_attachments_video ()

_on_initialize ()

_prepare_recreate ($force)

Preparation operations for recreate_xxx()

Parameters

$force

_rotate_get_filter ($direction)

Converts given direction to imagefilter chain

Parameters

$direction

_save_derived_image (string $identifier)

This is the actual code which filters and saves a derived image.

Parameters

$identifier

stringThe derived image to construct.

Returns

booleanIndicating success

_save_derived_images ()

This loops over the defined derived images (if any) and constructs each of them in turn.

Returns

booleanIndicating success.

_save_derived_videos ()

_save_main_image ()

Saves the main image to the type, doing transformation work if configured to do so.

Returns

booleanIndicating success.

_save_main_video ()

_save_original ()

If we are configured to do so, we save the original image.

Returns

booleanIndicating success

_save_original_video ()

apply_filter (string $identifier, string $filter)

Applies a filter to image identifier

Parameters

$identifier

stringthe image identifier to apply to

$filter

stringthe midcom_helper_imagefilter filter chain to apply

Returns

booleanindicating success/failure

apply_filter_all (string $filter)

Applies a given filter to all (except original) images in the type

Parameters

$filter

stringthe midcom_helper_imagefilter filter chain to apply

Returns

booleanindicating success/failure

convert_from_storage ($source)

Calls the base type to read all attachments, then extracts the title of the main attachment, if applicable.

Parameters

$source

convert_to_html ()

The HTML-Version of the image type can take two forms, depending on type configuration:
  1. If an 'thumbnail' image is present, it is shown and encapsulated in an anchor tag leading to the 'main' image.
  2. 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.

delete_screenshot ()

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

stringdirection to rotate to

Returns

booleanindicating success/failure

set_image (string $filename, string $tmpname, string $title, boolean $autodelete)

Public access wrapper for _set_image

Parameters

$filename

stringThe name of the image attachment to be created.

$tmpname

stringThe file to load.

$title

stringThe title of the image.

$autodelete

booleanIf this is true (the default), the temporary file will be deleted after postprocessing and attachment-creation.

Returns

booleanIndicating success.

set_video ($filename, $tmpname, $title, $autodelete)

Parameters

$filename

$tmpname

$title

$autodelete

update_image_from_file (string $identifier)

Overwrites image content from file, recalculates size etc

Parameters

$identifier

stringimage identifier to update

Returns

booleanindicating success/failure

_set_image (string $filename, string $tmpname, string $title, boolean $autodelete)

Adds the image to the type.

Loads and processes the $tmpname file on disk.

Parameters

$filename

stringThe name of the image attachment to be created.

$tmpname

stringThe file to load.

$title

stringThe title of the image.

$autodelete

booleanIf this is true (the default), the temporary file will be deleted after postprocessing and attachment-creation.

Returns

booleanIndicating success.

_set_video ($filename, $tmpname, $title, $autodelete)

Parameters

$filename

$tmpname

$title

$autodelete

 Properties

 

mixed $_current_tmpname_video

 

mixed $_filename_video

 

mixed $_original_mimetype_video

 

mixed $_original_tmpname_video

 

mixed $_pending_attachments_video

 

mixed $_target_mimetype_video

 

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.
see \midcom_helper_imagefilter
 

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 video title entered by the user.

Stored in each attachments title field.

 

mixed $title_video

 

string $_current_tmpname

The current working file.
 

string $_filename

The original filename of the uploaded file.
 

\midcom_helper_imagefilter $_filter

The image-filter instance to use.
 

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 $_target_mimetype

The target mimetype used after automatic conversion for all generated images.