NAME

    Krang::Media - Media and media metadata storage and access methods

SYNOPSIS

    # create new media object
    my $media = pkg('Media')->new( title => 'test media', 
                                   caption => 'test caption',
                                   copyright => 'AP 1999', 
                                   media_type_id => $media_type_id, 
                                   category_id => $category_id );
    # Find permissions for this media (for this user)
    $media->may_see();
    $media->may_edit();
    # add actual media file to media object
    $media->upload_file( filehandle => $filehandle, filename => 'media.jpg' );
    # get MIME type of uploaded file
    $mime_type = $media->mime_type();
    # get path to thumbnail - if image (thumbnail will be created if
    # does not exist)
    $thumbnail_path = $media->thumbnail_path();
    # assign 2 contributors to media object, specifying thier contributor type
    $media->contribs({contrib_id => 1, contrib_type_id => 3},
                     {contrib_id => 44, contrib_type_id => 4});
    # get contrib objects attached to this media
    @contribs = $media->contribs();
    # change assignment to include just the first contributor
    $media->contribs($contribs[0]);
    # get media element 
    my $element = $media->element();
    $element_id = $media->element_id; # undef until after save()
    # save the object to the database
    $media->save();
    # mark as checked out by you (your user_id)
    $media->checkout();
    # update caption for this media object
    $media->caption('new caption');
    # again, save the object to the database (upping version)
    $media->save();
    # get current version number, in this example 2
    $version = $media->version();
    # revert to version 1 (creating version 3, identical to 1)
    $media->revert(1);
    # preview media object
    $media->preview
    # publish media object
    $media->publish
    # get id for this object
    my $media_id = $media->media_id();
    # return object by id
    ($media_obj) = pkg('Media')->find( media_id => $media_id );

DESCRIPTION

This class handles the storage and retrieval of media objects on the filesystem, as well as media object metadata in the database. Contributors (Krang::Contrib objects) can also be attached to stories.

Media Versioning

Versioning in this system functions perhaps in a non-traditional way. A quick walk-thru of a media edit and revert may help understanding. We'll assume the existing media object starts with version = 1.

First, the media object is marked as 'checked out' by the current user. After this call, only someone logged in with the same user_id can edit this media object:

  $media->checkout();

Now that the media object cannot be edited by anyone else, let's make a change to the title of this media object:

  $media->title('new title');

Finally, we save the media object:

  $media->save();

After save(), the in-memory object $media will be saved into the 'media' table as version = 2, and also saved in media_version for later use.

To begin the explaination of 'revert', the most important thing to understand is that revert() simply takes a copy of an older version and uses it to make a new version.

To revert to the contents of version 1, we call the revert() method:

  $media->revert(1)

So now what do we have? We now have version 1, 2 and 3 in the versioning table, and 3 is a copy of 1.

Thus, revert() does not give you access to the actual original version, but instead gives you a copy of it.

The reason for doing things this way is so you can always get back to a previous version no matter how many times you've saved and reverted. This is also how CVS works.

INTERFACE

METHODS