NAME

App::ZofCMS::Plugin::ImageGallery - CRUD-like plugin for managing images.

SYNOPSIS

In your Main Config File or ZofCMS Template file:

plugins => [ qw/ImageGallery/ ],

plug_image_gallery => {
    dsn        => "DBI:mysql:database=test;host=localhost",
    user       => 'test',
    pass       => 'test',
    no_form    => 0,
    allow_edit => 1,
},

In your HTML::Template template:

<tmpl_var name='plug_image_gallery_form'>
<tmpl_var name='plug_image_gallery_list'>

Viola, now you can upload photos with descriptions, delete them and edit descriptions. \o/

DESCRIPTION

The module is a plugin for App::ZofCMS that allows one to add a CRUD-like functionality for managing photos. The plugin automatically makes thumbnails and can also resize the actual photos if you tell it to. So far, only .jpg, .png and .gif images are supported; however, plugin does not check Content-Type of the uploaded image.

The image file name and description are stored in a SQL database.

This documentation assumes you've read App::ZofCMS, App::ZofCMS::Config and App::ZofCMS::Template

USED SQL TABLE FORMAT

When create_table option is turned on (see below) the plugin will create the following table where table_name is derived from table argument in plug_image_gallery (see below).

CREATE TABLE table_name (
    photo        TEXT,
    width        SMALLINT,
    height       SMALLINT,
    thumb_width  SMALLINT,
    thumb_height SMALLINT,
    description  TEXT,
    time         VARCHAR(10),
    id           TEXT
);

MAIN CONFIG FILE AND ZofCMS TEMPLATE FIRST-LEVEL KEYS

`plugins`

plugins => [ qw/ImageGallery/, ],

You obviously need to include the plugin in the list of plugins to execute.

`plug_image_gallery`

plug_image_gallery => {
    dsn             => "DBI:mysql:database=test;host=localhost",
    # everything below is optional
    user            => '',
    pass            => '',
    opt             => { RaiseError => 1, AutoCommit => 1 },
    table           => 'photos',
    photo_dir       => 'photos/',
    filename        => '[:rand:]',
    thumb_dir       => 'photos/thumbs/',
    create_table    => 0,
    t_name          => 'plug_image_gallery',
    no_form         => 1,
    no_list         => 0,
    no_thumb_desc   => 0,
    allow_edit      => 0,
    thumb_size      => { 200, 200 },
    # photo_size      => [ 600, 600 ],
    has_view        => 1,
    want_lightbox   => 0,
    lightbox_rel    => 'lightbox',
    lightbox_desc   => 1,
}

plug_image_gallery => sub {
    my ( $t, $q, $config ) = @_;
    return {
        dsn             => "DBI:mysql:database=test;host=localhost",
    };
}

The plugin takes its configuration from plug_image_gallery first-level key that takes a hashref or a subref as a value and can be specified in either (or both) Main Config File and ZofCMS Template file. If the same key in that hashref is specified in both, Main Config File and ZofCMS Tempate file, then the value given to it in ZofCMS Template will take precedence. If subref is specified, its return value will be assigned to plug_image_gallery 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 Tempalate hashref, query parameters hashref and App::ZofCMS::Config object.

The plugin will NOT run if plug_image_gallery is not set or if both no_form and no_list arguments (see below) are set to true values.

The possible plug_image_gallery hashref's keys/values are as follows:

`dsn`

dsn => "DBI:mysql:database=test;host=localhost",

Mandatory. Takes a scalar as a value which must contain a valid "$data_source" as explained in DBI's connect_cached() method (which plugin currently uses).

`user`

user => '',

Optional. Takes a string as a value that specifies the user name to use when authorizing with the database. Defaults to: empty string

`pass`

pass => '',

Optional. Takes a string as a value that specifies the password to use when authorizing with the database. Defaults to: empty string

`opt`

opt => { RaiseError => 1, AutoCommit => 1 },

Optional. Takes a hashref as a value, this hashref contains additional DBI parameters to pass to connect_cached() DBI's method. Defaults to: { RaiseError => 1, AutoCommit => 1 }

`table`

table => 'photos',

Optional. Takes a string as a value, specifies the name of the SQL table in which to store information about photos. Defaults to: photos

`create_table`

create_table => 0,

Optional. When set to a true value, the plugin will automatically create needed SQL table, you can create it manually if you wish, see its format in USED SQL TABLE FORMAT section above. Generally you'd set this to a true value only once, at the start, and then you'd remove it because there is no "IF EXISTS" checks. Defaults to: 0

`t_name`

t_name => 'plug_image_gallery',

Optional. Takes a string as a value. This string will be used as a "base name" for two keys that plugin generates in {t} special key. The keys are plug_image_gallery_list and plug_image_gallery_form (providing t_name is set to default) and are explained below in HTML::Template VARIABLES section below. Defaults to: plug_image_gallery

`photo_dir`

photo_dir => 'photos/',

Optional. Takes a string that specifies the directory (relative to index.pl) where the plugin will store photos. Note: plugin does not automatically create this directory. Defaults to: photos/

`thumb_dir`

thumb_dir => 'photos/thumbs/',

Optional. Takes a string that specifies the directory (relative to index.pl) where the plugin will store thumbnails. Note: plugin does not automatically create this directory. Note 2: this directory must NOT be the same as photo_dir. Defaults to: photos/thumbs/

`filename`

filename => '[:rand:]',

Optional. Specifies the name for the image file (and its thumbnail) without the extension for when new image is uploaded. You'd obviously want to manipulate this value with some other plugin (e.g. App::ZofCMS::Plugin::Sub) to make sure it's not the same as existing images. Special value of [:rand:] (value includes the brackets) will make the plugin generate random filenames (along with check of whether the generated name already exists). Defaults to: [:rand:]

`thumb_size`

thumb_size => { 200, 200 }, # resize only if larger
thumb_size => [ 200, 200 ], # always resize

Optional. Takes either an arrayref with two elements or a hashref with one key/value pair. The plugin will generate thumbnails automatically. The thumb_size specifies the dimensions of the thumbnails. The proportions are always kept when resizing. When thumb_size is set to an arrayref, the plugin will resize the image even if its smaller than the specified size (i.e. a 50x50 image's thumb will be scaled to 200x200 when thumb_size is set to [200, 200] ). The first element of the arrayref denotes the x (width) dimension and the second element denotes the y (height) dimension. When the value for thumb_size is a hashref then the key denotes the width and the value denotes the height; the image will be resized only if one of its dimensions (width or height) is larger than the specified values. In other words, when thumb_size is set to { 200, 200 }, a 50x50 image's thumbnail will be left at 50x50 while a 500x500 image's thumbnail will be scaled to 200x200. Defaults to: { 200, 200 }

`photo_size`

photo_size => { 600, 600 },
photo_size => [ 600, 600 ],

Optional. When specified takes either an arrayref or a hashref as a value. Everything is the same (regarding values) as the values for thumb_size argument described above except that resizing is done on the original image. If photo_size is not specified, no resizing will be performed. Note: the thumbnail will be generated first, thus it's possible to have thumbnails that are larger than the original image even when hashrefs are used for both photo_size and thumb_size. By default is not specified

`no_form`

no_form => 1,

Optional. Takes either true or false values. When set to a false value, the plugin will generate as well as process an HTML form that is to be used for uploading new images or editing descriptions on existing ones. Note: even if you are making your own HTML form, the plugin will not process editing or deleting of items when no_form is set to a true value. Defaults to: 1

`no_list`

no_list => 0,

Optional. Takes either true or false values. When set to a false value, the plugin will pull the data from the database and generate an HTML list with image thumbnails and their descriptions (unless no_thumb_desc argument described below is set to a true value). Defaults to: 0

`no_thumb_desc`

no_thumb_desc => 0,

Optional. Takes either true or false values. Makes sense only when no_list is set to a false value. When no_thumb_desc is set to a true value, the plugin will not put descriptions in the generated list of thumbnails. The description will be visible only when the user clicks on the image to view it in large size (providing has_view option that is described below is set to a true value). Defaults to: 0

`has_view`

has_view => 1,

Optional. Takes either true or false values. Makes sense only when no_list is set to a false value. When set to a true value, plugin will generate links for each thumbnail in the list; when user will click that link, he or she will be presented with an original image and a link to go back to the list of thumbs. When set to a false value no link will be generated. Defaults to: 1

`allow_edit`

allow_edit => 0,

Optional. Takes either true or false values. When set to a true value, both no_list and no_form must be set to false values. When set to a true value, the plugin will generate Edit and Delete buttons under each thumbnail in the list. Clicking "Delete" will delete the image, thumbnail and entry in the database. Clicking "Edit" will fetch the description into the "description" field in the form, allowing the user to edit it. Defaults to: 0

`want_lightbox`

want_lightbox => 0,

Optional. The list of thumbs generated by the plugin can be generated for use with "Lightbox" JavaScript crapolio. Takes true or false values. When set to a true value, the thumb list will be formatted for use with "Lightbox". Note: has_view must be set to a true value as well. Defaults to: 0

`lightbox_rel`

lightbox_rel => 'lightbox',

Optional. Used only when want_lightbox is set to a true value. Takes a string as a value, this string will be used for rel="" attribute on links. Defaults to: lightbox

`lightbox_desc`

lightbox_desc => 1,

Optional. Takes either true or false values. When set to a true value, the plugin will stick image descriptions into title="" attribute that makes them visible in the Lightbox. Defaults to: 1

HTML::Template VARIABLES

The plugin generates two keys in {t} ZofCMS Template special key, thus making them available for use in your HTML::Template templates. Assuming t_name is left at its default value the following are the names of those two keys:

`plug_image_gallery_form`

<tmpl_var name='plug_image_gallery_form'>

This variable will contain HTML form generated by the plugin, the form also includes display of errors.

`plug_image_gallery_list`

<tmpl_var name='plug_image_gallery_list'>

This variable will contain the list of photos generated by the plugin.

GENERATED HTML CODE

form

<form action="" method="POST" id="plug_image_gallery_form" enctype="multipart/form-data">
<div>
    <input type="hidden" name="page" value="photos">
    <input type="hidden" name="dir" value="/admin/">
    <ul>
        <li>
            <label for="plug_image_gallery_file">Image: </label
            ><input type="file" name="plug_image_gallery_file" id="plug_image_gallery_file">
        </li>
        <li>
            <label for="plug_image_gallery_description">Description: </label
            ><textarea name="plug_image_gallery_description" id="plug_image_gallery_description" cols="60" rows="5"></textarea>
        </li>
    </ul>
    <input type="submit" name="plug_image_gallery_submit" value="Upload">
</div>
</form>

form when "Edit" was clicked

<form action="" method="POST" id="plug_image_gallery_form" enctype="multipart/form-data">
<div>
    <input type="hidden" name="page" value="photos">
    <input type="hidden" name="dir" value="/admin/">
    <input type="hidden" name="plug_image_gallery_id" value="07537915760568812292592510718228816144752">
    <ul>
        <li>
            <label for="plug_image_gallery_description">Description: </label
            ><textarea name="plug_image_gallery_description" id="plug_image_gallery_description" cols="60" rows="5">Teh Descripshun!</textarea>
        </li>
    </ul>
    <input type="submit" name="plug_image_gallery_submit" value="Update">
</div>
</form>

form when upload or update was successful

<p>Your image has been successfully uploaded.</p>
<p><a href="/index.pl?page=photos&amp;amp;dir=/admin/">Upload another image</a></p>

list (when both `allow_edit` and `has_view` is set to true values)

<ul class="plug_image_gallery_list">
    <li>
        <a href="/index.pl?page=photos&amp;dir=/admin/&amp;plug_image_gallery_photo_id=037142535745273312292651650508033404216754"><img src="/photos/thumbs/0029243203419358812292651650444418525180907.jpg" width="191" height="200" alt=""></a>
            <form action="" method="POST">
            <div>
                <input type="hidden" name="plug_image_gallery_id" value="037142535745273312292651650508033404216754">
                <input type="hidden" name="page" value="photos">
                <input type="hidden" name="dir" value="/admin/">
                <input type="submit" name="plug_image_gallery_action" value="Edit">
                <input type="submit" name="plug_image_gallery_action" value="Delete">
            </div>
            </form>
    </li>
    <li class="alt">
        <a href="/index.pl?page=photos&amp;dir=/admin/&amp;plug_image_gallery_photo_id=07537915760568812292592510718228816144752"><img src="/photos/thumbs/058156553244134912292592510947564500241668.png" width="200" height="125" alt=""></a>
        <p>Teh Descripshun!</p>
            <form action="" method="POST">
            <div>
                <input type="hidden" name="plug_image_gallery_id" value="07537915760568812292592510718228816144752">
                <input type="hidden" name="page" value="photos">
                <input type="hidden" name="dir" value="/admin/">
                <input type="submit" name="plug_image_gallery_action" value="Edit">
                <input type="submit" name="plug_image_gallery_action" value="Delete">
            </div>
            </form>
    </li>
</ul>

original image view

<a class="plug_image_gallery_return_to_image_list" href="/index.pl?page=photos&amp;dir=/admin/">Return to image list.</a>
<div id="plug_image_gallery_photo"><img src="/photos/0029243203419358812292651650444418525180907.jpg" width="575" height="600" alt="">
    <p class="plug_image_gallery_description">Uber hawt chick</p>
</div>

AUTHOR

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

BUGS

Please report any bugs or feature requests to bug-app-zofcms-plugin-imagegallery at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-ZofCMS-Plugin-ImageGallery. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc App::ZofCMS::Plugin::ImageGallery

You can also look for information at:

RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-ZofCMS-Plugin-ImageGallery
AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/App-ZofCMS-Plugin-ImageGallery
CPAN Ratings

http://cpanratings.perl.org/d/App-ZofCMS-Plugin-ImageGallery
Search CPAN

http://search.cpan.org/dist/App-ZofCMS-Plugin-ImageGallery

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install App::ZofCMS::Plugin::ImageGallery, copy and paste the appropriate command in to your terminal.

cpanm

cpanm App::ZofCMS::Plugin::ImageGallery

CPAN shell

perl -MCPAN -e shell
install App::ZofCMS::Plugin::ImageGallery

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

USED SQL TABLE FORMAT

MAIN CONFIG FILE AND ZofCMS TEMPLATE FIRST-LEVEL KEYS

plugins

plug_image_gallery

dsn

user

pass

opt

table

create_table

t_name

photo_dir

thumb_dir

filename

thumb_size

photo_size

no_form

no_list

no_thumb_desc

has_view

allow_edit

want_lightbox

lightbox_rel

lightbox_desc