/ 
Mojolicious-Plugin-Cloudinary-0.0401
/ Mojolicious::Plugin::Cloudinary

NAME

Mojolicious::Plugin::Cloudinary - Talk with cloudinary.com

VERSION

0.0401

DESCRIPTION

This module lets you interface to http://cloudinary.com. Its primary target is to be a Mojolicious plugin, but it can also be used as a generic module - just skip calling "register".

Option expansion

As from 0.04 all methods support the short and long option, meaning the examples below work the same:

$self->url_for('billclinton.jpg' => { w => 50 });
$self->url_for('billclinton.jpg' => { width => 50 });

SYNOPSIS

With mojolicious

package MyWebApp;
use Mojo::Base 'Mojolicious';

sub startup {
    my $self = shift;
    $self->plugin('Mojolicious::Plugin::Cloudinary', {
        cloud_name => $str,
        api_key => $str,
        api_secret => $str,
    });
}

package MyWebApp::SomeController;

sub upload {
    my $self = shift;

    $self->render_later;
    $self->cloudinary_upload({
        file => $self->param('upload_param'),
        on_success => sub {
            my $res = shift;
            $self->render_json($res);
        },
        on_error => sub {
            my $res = shift || { error => 'Unknown' };
            $self->render_json($res);
        },
    });
}

Standalone

my $delay = Mojo::IOLoop->delay;
my $cloudinary = Mojolicious::Plugin::Cloudinary->new(
                     cloud_name => '...',
                     api_key => '...',
                     api_secret => '...',
                 );

$delay->begin;
$cloudinary->upload({
    file => { file => $path_to_file },
    on_success => sub {
        # ...
        $delay->end;
    },
    on_error => sub {
        # ...
        $delay->end;
    },
});

# let's you do multiple upload() in parallel
# just call $delay->begin once pr upload()
# and $delay->end in each on_xxx callback
$delay->wait;

url_for() examples

$cloudinary->url_for('billclinton.jpg', { type => 'facebook' });
$cloudinary->url_for('billclinton.jpg', { type => 'twitter_name', h => 70, w => 100 });
$cloudinary->url_for('18913373.jpg', { type => 'twitter_name' });
$cloudinary->url_for('my-uploaded-image.jpg', { h => 50, w => 50 });
$cloudinary->url_for('myrawid', { resource_type => 'raw' });

ATTRIBUTES

cloud_name

Your cloud name from https://cloudinary.com/console

api_key

Your API key from https://cloudinary.com/console

api_secret

Your API secret from https://cloudinary.com/console

private_cdn

Your private CDN url from https://cloudinary.com/console.

js_image

This string will be used as the image src for images constructed by "cloudinary_js_image". The default is "/image/blank.png".

METHODS

upload

$self->upload({
    file => $binary_str|$url, # required
    timestamp => $epoch, # time()
    public_id => $str, # optional
    format => $str, # optional
    resource_type => $str, # image or raw. defaults to "image"
    tags => ['foo', 'bar'], # optional
    on_success => sub {
        my($res) = @_;
        # ...
    },
    on_error => sub {
        my($res, $tx) = @_;
        # ...
    },
});

Will upload a file to http://cloudinary.com using the parameters given "cloud_name", "api_key" and "api_secret". $res in on_success will be the json response from cloudinary:

{
    url => $str,
    secure_url => $str,
    public_id => $str,
    version => $str,
    width => $int, # only for images
    height => $int, # only for images
}

$res for on_error on the other hand can be either undef if there was an issue connecting/communicating with cloudinary or a an error:

{
    error => { message: $str },
}

The file can be:

res in callbacks will be the JSON response from http://cloudinary.com as a hash ref. It may also be undef if something went wrong with the actual HTTP POST.

See also https://cloudinary.com/documentation/upload_images and http://cloudinary.com/documentation/upload_images#raw_uploads.

destroy

$self->destroy({
    public_id => $public_id,
    resource_type => $str, # image or raw. defaults to "image"
    on_success => sub {
        # ...
    },
    on_error => sub {
        my($res, $tx) = @_;
        # ...
    },
});

Will delete an image from cloudinary, identified by $public_id. on_success will be called when the image got deleted, while on_error is called if not: $res can be either undef if there was an issue connecting/communicating with cloudinary or a an error:

{
    error => { message: $str },
}

See also https://cloudinary.com/documentation/upload_images#deleting_images.

url_for

$url_obj = $self->url_for("$public_id.$format", \%args);

This method will return a public URL to the image at http://cloudinary.com. It will use "private_cdn" or the public CDN and "cloud_name" to construct the URL. The return value is a Mojo::URL object.

Example %args:

{
    w => 100, # width of image
    h => 150, # height of image
    resource_type => $str, # image or raw. defaults to "image"
    type => $str, # upload, facebook. defaults to "upload"
    secure => $bool, # use private_cdn or public cdn
}

See also http://cloudinary.com/documentation/upload_images#accessing_uploaded_images and http://cloudinary.com/documentation/image_transformations.

register

Adds the helpers to your controller:

  • cloudinary_upload

  • cloudinary_destroy

    See "upload".

  • cloudinary_url_for

    See "url_for".

  • cloudinary_image

    $str = $c->cloudinary_image($public_id, $url_for_args, $image_args);

    This will use "image" in Mojolicious::Plugin::TagHelpers to create an image tag where "src" is set to a cloudinary image. $url_for_args are passed on to "url_for" and $image_args are passed on to "image" in Mojolicious::Plugin::TagHelpers.

  • cloudinary_js_image

    $str = $c->cloudinary_js_image($public_id, $url_for_args);

    About the same as "cloudinary_image", except it creates an image which can handled by the cloudinary jQuery plugin which you can read more about here: http://cloudinary.com/blog/cloudinary_s_jquery_library_for_embedding_and_transforming_images

    Example usage:

    $c->cloudinary_js_image(1234567890 => {
    width => 115,
    height => 115,
    crop => 'thumb',
    gravity => 'faces',
    radius => '20',
});

    ...will produce:

    <img src="/image/blank.png"
    class="cloudinary-js-image"
    alt="1234567890"
    data-src="1234567890"
    data-width="115"
    data-height="135"
    data-crop="thumb"
    data-gravity="faces"
    data-radius="20">

    Note: The "class" and "alt" attributes are fixed for now.

COPYRIGHT & LICENSE

See Oppstarter

AUTHOR

Jan Henning Thorsen - jan.henning@oppstarter.no