Name

Bric::Biz::Asset::Business::Media::Image - the media class that represents static images

Date

$Data$

Synopsis

# Creation of new Image objects
$image = Bric::Biz::Asset::Business::Media::Image->new( $init )
$image = Bric::Biz::Asset::Business::Media::Image->lookup( { id => $id })
($images || @images) = Bric::Biz::Asset::Business::Media::Image->list( $param)

# list of ids
($id_list || @ids) = Bric::Biz::Asset::Business::Media::Image->list_ids($param)

Description

The Subclass of Media that pretains to Images

Interface

Constructors

$image = Bric::Biz::Asset::Business::Media::Image->new($init)

This will create a new image object.

Supported Keys:

Throws:

NONE

Side Effects:

NONE

Notes:

NONE

$media = Bric::Biz::Asset::Business::Media::Image->lookup( { id => $id })

This will return the matched looked up object

Throws:

NONE

Side Effects:

NONE

Notes:

NONE

($imgs || @imgs) = Bric::Biz::Asset::Business::Media::Image->list($param)

Returns a list of image objects that match the params passed in

Throws:

NONE

Side Effects:

NONE

Notes:

NONE

Destructors

$self->DESTROY

dummy method to not wast the time of AUTHLOAD

Public Class Methods

(@ids || $ids) = Bric::Biz::Asset::Business::Media::Image->list_ids($param)

Returns a list of ids that match the particular params

Supported Keys:

Throws:

NONE

Side Effects:

NONE

Notes:

NONE

$class_id = Bric::Biz::Asset::Business::Media::Image->get_class_id()

Returns the class id of the Image class

Throws:

NONE

Side Effects:

NONE

Notes:

NONE

my $key_name = Bric::Biz::Asset::Business::Media::Image->key_name()

Returns the key name of this class.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my_meths()

Data Dictionary for introspection of the object

Throws:

NONE

Side Effects:

NONE

Notes:

NONE

Public Instance Methods

my $thumbnail_uri = $image->thumbnail_uri

If the image document has an associated thumbnail image, this method returns its local URI.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my $new_img = $image->find_or_create_alternate(\%params)
my $new_image = $image->find_or_create_alternate({
    file_suffix => '_alt',
    et_key_name => 'thumb',
    user        => $user,
    relate      => 0,
    transformer => sub {
        shift->scale( xpixels => 115 )->crop( top => 76 );
    },
});

Creates an alternate representation of the current image document and returns it. This is useful for creating thumbnails and the like. Note that the user must have CREATE access to the start desk in the first available workflow.

The first thing this method does is see if a likely alternate already exists by looking for a media document in the same site, with the appropriate URI (as formed by the current media document's category, cover date, and file name as modified by the file_prefix and file_suffix parameters), and based on the appropriate element type. If such a media document is found, it is simply returned and no further actions are taken.

If such a media document does not exist, find_or_create_alternate() creates it, moves it into workflow, takes other actions as determined by the parameters, and returns it.

It's important to get the parameters right in order to properly find or create the alternate representation of an image that you need for your site. So read these descriptions carefully!

title_prefix
title_suffix

Strings to add to the beginning and/or end of the media document's title to create a new title for the new media document. They will also be used to modify the image description. The prefex defaults to "Thumbnail for " while the suffix defaults to an empty string.

file_prefix
file_suffix

String to add to the beginning and/end of the media document's file name to create a new document's file name. The prefix defaults to the empty string while the suffix defaults to "_thumb". The resulting file name will be used both to search for an exsting image with this file name and, if there isn't one, to provide the file name for the new image document.

Note that the suffix will be inserted into the file name before the file name extension. For example, foo.png will become foo_thumb.png, not foo.png_thumb.

user

The user who will "create" the new media document. Defaults to the current user. Useful in templates to provide a user who might have more extensive permissions than the current user.

element_type

The media element type on which the alternate will be based. Also used to find an existing media document.

et_key_name

The key name for the element type on which the alternate will be based. Also used to find an existing media document. If both element and et_key_name are passed, et_key_name will be used.

transformer

A code reference that expects a single argument, an Imager object, and returns an Imager object. Use this code reference to transform the media document file into a new file to be used for the alternate. For example, if you wanted to create a new image that's 115 pixels wide and crops the image to get only the top 76 pixels, you can pass something like this:

transformer => sub {
    shift->scale( xpixels => 115 )->crop( top => 76 );
},

Consult the Imager documentation, and especially Imager::Transformations, for its complete API, examples, etc. Note taht the transformer code reference will only be called if the alternate does not already exist.

width
height

The height and width, in pixels, to make the alternate image. Only used if an existing image is not found, and if the transformer parameter has not been passed.

use_thumb

Boolean indicating whether or not to use the thumbnail file to create the alternate document. If true, the transform, width, and height parameters will be ignored and the existing thumbnail file will simply be used. Defaults to false.

relate

Boolean to indicate whether or not to relate the new image, if one is created to the current image. If true, and an alternate is created, it will be added as a related media document to the original media document's top-level element. Defaults to true.

checkin

Boolean to indicate whether or not to check in the newly created alternate image document. Defaults to true.

move_to_pub

Boolean to indicate whether or not to move in the newly created alternate image document to a publish desk. Defaults to true. Note that the user must have READ access to a PUBLISH desk or else an exception will be thrown.

Throws: Exceptions when the user does not have permission to create a media document in a media workflow, or does not have permission to move it to a publish desk, or if the necessary libraries to support the desired transformations are not included in the Imager build.

Side Effects: If no alternate can be found, a new media document will be created, put into workflow, and possibly checked in and moved to the publish desk.

Notes: Isn't the above enough?

my $created_ok = $image->create_thumbnail

Creates a thumbnail image from the supplied image object. Returns 1 on successful completion and undef on failure.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

($imgs || @imgs) = $image->upload_file

Overrides the upload_file() method in the parent class and then makes a call to the create_thumbnail() method.

Throws:

NONE

Side Effects:

NONE

Notes:

NONE

Private

Private Class Methods

NONE

Private Instance Methods

_thumb_location
my $thumb_location = $self->_thumb_location;

Returns the location of a thumnail image file. This method simply modifies the value returned by get_location to generate the name of the image file. Returns undef if the image has no location.

_thumb_file
my $thumb_file = $self->_thumb_file;

Returns the absolute path to the thumnail image file for this image.

Notes

NONE

Author

"Michael Soderstrom" <miraso@pacbell.net>

See Also

perl , Bric, Bric::Biz::Asset, Bric::Biz::Asset::Business, Bric::Biz::Asset::Business::Media