The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-ZofCMS-PluginBundle-Naughty-1.001002
River stage zero No dependents
++
/ App::ZofCMS::Plugin::ImageResize

NAME

App::ZofCMS::Plugin::ImageResize - Plugin to resize images

SYNOPSIS

    plugins => [
        qw/ImageResize/
    ],

    plug_image_resize => {
        images => [
            qw/3300 3300 frog.png/
        ],
        # below are all the default values
        inplace     => 1,
        only_down   => 1,
        cell        => 'd',
        key         => 'plug_image_resize',
        path        => 'thumbs',
    },

DESCRIPTION

The module is a plugin for App::ZofCMS that provides simple image resize capabilities. This documentation assumes you've read App::ZofCMS, App::ZofCMS::Config and App::ZofCMS::Template.

FIRST-LEVEL ZofCMS TEMPLATE AND MAIN CONFIG FILE KEYS

plugins

    plugins => [
        qw/ImageResize/
    ],

Mandatory. You need to add the plugin to list of plugins to execute.

plug_image_resize

    plug_image_resize => {
        images => [
            qw/3300 3300 frog.png/
        ],
        # optional options below; all are the default values
        inplace     => 1,
        only_down   => 1,
        cell        => 'd',
        key         => 'plug_image_resize',
        path        => 'thumbs',
    },

    plug_image_resize => sub {
        my ( $t, $q, $config ) = @_;
        return {
            images => [
                qw/3300 3300 frog.png/
            ],
        }
    },

Mandatory. Takes a hashref or a subref as a value. If subref is specified, its return value will be assigned to plug_image_resize as if it was already there. If sub returns an undef, then plugin will stop further processing. The @_ of the subref will contain (in that order): ZofCMS Template hashref, query parameters hashref and App::ZofCMS::Config object. The plug_image_resize first-level key can be set in either (or both) ZofCMS Template and Main Config File files. If set in both, the values of keys that are set in ZofCMS Template take precedence. Possible keys/values are as follows:

images

        images => [
            qw/3300 3300 frog.png/
        ],

        images => {
            image1 => {
                x           => 110,
                y           => 110,
                image       => 'frog.png',
                inplace     => 1,
                only_down   => 1,
                path        => 'thumbs',
            },
            image2 => [ qw/3300 3300 frog.png/ ],
        },

        images => [
            [ qw/1000 1000 frog.png/ ],
            [ qw/110 100 frog.png 0 1/ ],
            {
                x           => 110,
                y           => 110,
                image       => 'frog.png',
                inplace     => 1,
                only_down   => 1,
                path        => 'thumbs',
            },
        ],

        images => sub {
            my ( $t, $q, $config ) = @_;
            return [ qw/100 100 frog.png/ ];
        },

Mandatory. The images key is the only optional key. Its value can be either an arrayref, an arrayref of arrayrefs/hashrefs, subref or a hashref.

If the value is a subref, the @_ will contain (in the following order): ZofCMS Template hashref, query parameters hashref, App::ZofCMS::Config object. The return value of the sub will be assigned to images key; if it's undef then plugin will not execute further.

When value is a hashref, it tells the plugin to resize several images and keys will represent the names of the keys in the result (see OUTPUT section below) and values are the image resize options. When value is an arrayref of scalar values, it tells the plugin to resize only one image and that resize options are in a "shortform" (see below). When the value is an arrayref of arrayrefs/hashrefs it means there are several images to resize and each element of the arrayref is an image to be resized and its resize options are set by each of those inner arrayrefs/hashrefs.

When resize options are given as an arrayref they correspond to the hashref-form keys in the following order:

    x  y  image  inplace  only_down  path

In other words, the following resize options are equivalent:

    [ qw/100 200 frog.png 0 1 thumbs/ ],

    {
        x           => 110,
        y           => 110,
        image       => 'frog.png',
        inplace     => 1,
        only_down   => 1,
        path        => 'thumbs',
    },

The x, y and image keys are mandatory. The rest of the keys are optional and their defaults are whatever is set to the same-named keys in the plugin's configuration (see below). The x and y keys specify the dimensions to which the image should be resized (see also the only_down option described below). The image key contains the path to the image, relative to index.pl file.

inplace

    inplace => 1,

Optional. Takes either true or false values. When set to a true value, the plugin will resize the images inplace (i.e. the resized version will be written over the original). When set to a false value, the plugin will first copy the image into directory specified by path key and then resize it. Defaults to: 1

only_down

    only_down => 1,

Optional. Takes either true or false values. When set to a true value, the plugin will only resize images if either of their dimensions is larger than what is set in x or y parameters. When set to a false value, the plugin will scale small images up to meet the x/y criteria. Note: the plugin will always keep aspect ratio of the images. Defaults to: 1

cell

    cell => 'd',

Optional. Specifies the name of the first-level key of ZofCMS Template hashref into which to put the results. Must point to either a non-existent key or a hashref. Defaults to: d

key

    key => 'plug_image_resize',

Optional. Specifies the name of the second-level key (i.e. the name of the key inside cell hashref) where to put the results. Defaults to: plug_image_resize

path

    path => 'thumbs',

Optional. Specifies the name of the directory, relative to index.pl, into which to copy the resized images when inline resize option is set to a false value. Defaults to: thumbs.

ERRORS ON RESIZE

If an error occurred during a resize, instead of a hashref you'll have an undef and the reason for error will be set to $t->{t}{plug_image_resize_error} where $t is the ZofCMS Template hashref.

OUTPUT

The plugin will place the output into key hashref key inside cell first-level key (see parameters above). The type of value of the key will depend on how the images parameter was set (see dumps below for examples). In either case, each of the resized images will result in a hashref inside the results. The x and y keys will contain image's new size. The image key will contain the path to the image relative to index.pl file. If the image was not resized then the no_resize key will be present and its value will be 1. The inplace, path and only_down keys will be set to the values that were set to be used in resize options.

    # `images` is set to a hashref with a key named `image1`
    'd' => {
        'plug_image_resize' => {
            'image1' => {
                'inplace' => '0',
                'y' => 2062,
                'path' => 'thumbs',
                'only_down' => '0',
                'x' => 3300,
                'image' => 'thumbs/frog.png'
        }
    }

    # `images` is set to one arrayref (i.e. no inner arrayrefs)
    'd' => {
        'plug_image_resize' => {
            'inplace' => '0',
            'y' => 2062,
            'path' => 'thumbs',
            'only_down' => '0',
            'x' => 3300,
            'image' => 'thumbs/frog.png'
        }
    },

    # `images` is set to one arrayref of arrayrefs
    'd' => {
        'plug_image_resize' => [
            {
                'inplace' => '0',
                'y' => 2062,
                'path' => 'thumbs',
                'only_down' => '0',
                'x' => 3300,
                'image' => 'thumbs/frog.png'
            }
        ],
    },

REPOSITORY

Fork this module on GitHub: https://github.com/zoffixznet/App-ZofCMS-PluginBundle-Naughty

BUGS

To report bugs or request features, please use https://github.com/zoffixznet/App-ZofCMS-PluginBundle-Naughty/issues

If you can't access GitHub, you can email your request to bug-App-ZofCMS-PluginBundle-Naughty at rt.cpan.org

AUTHOR

Zoffix Znet <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/)

LICENSE

You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.