Andrew Maltsev > XAO-ImageCache-1 > XAO::ImageCache

Download:
XAO-ImageCache-1.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 1   Source  

NAME ^

XAO::ImageCache - Images caching by URLs stored in XAO::FS database

SYNOPSIS ^

    use XAO::ImageCache;

    # Making new instance of Image Cache object
    my $image_Cache = XAO::ImageCache->new(
        list           => $odb->fetch("/Products"),
        cache_path     => "/var/httpd/shop/product/images/",
        cache_url      => "/products/images/",
        source_url_key => "source_img",
    ) || die "Can't make Image cache!";

    # Init new empty Cache
    $image_cache->init() || die "Can't init new cache!";
    
    # Start images checking and downloading to cache
    $image_cache->check();

DESCRIPTION ^

When we store images links on own database we have no real images on own site. Some time it may be a problem cause images may have no right dimension or may be deleted from source site.

XAO::ImageCache made for cache locally images his URL stored in XAO Founsation Server. Also, images may be resized automaticaly.

This module provide easy methodes to scan XAO Foundation Server data lists, extract images source URLs from data objects, downloading images to local cache, resize local copy of image to feet in to given dimensions and store new local URL of image back to data object.

METHODS ^

new($%)

The constructor returns a new XAO::ImageCache object. You can use it to make new images cache or check images of already existent cache.

 my $image_cache = XAO::ImageCache->new(
     cache_path     => "cache",        # set cache directory to './cache/'
     source_path    => "cache/source", # set source directory to './cache/source/'
     local_path     => "images/copy",  # (optional) try to resolve local urls
     cache_url      => "images/",      # set cached images (relative) path to 'images/'
     list           => $odb->fetch("/Products"),
     source_url_key => 'source_image_url',
     dest_url_key   => 'dest_image_url',
     filename_key   => 'product_id',
     size           => {
         width  => 320,
         height => 200,
         save_aspect_ratio => 1,
     thumbnails     => {
         path     => '/var/httpd/shop/product/images/tbn',
         url      => '/products/images/tbn/'
         geometry => "25%",
         url_key  => 'thumbnail_url',
     },
     autocreate     => 1,
     useragent      => {
         agent   => 'My Lovely Browser/v13.01',
         timeout => 30,
     },  
 ) || die "Image cache creation failure!";

Number of configuration parameters should be passed to XAO::ImageCache to tune functionality.

autocreate
cache_path
cache_url
dest_url_key
list
log_file
reload
source_url_key
size
thumbnails
useragent

Follow to CONFIGURATION PARAMETERS section to see what each parameter do.

If any of required parameter is not present error will returned.

init($)

Cache structure initialization.

Executed automaticaly if autocreate parameter present.

Create image cache directory if non existent and thumbnail cache directory if non existent and defined as initialization parameter.

check($)

Goes through given XAO FS data list, downloads images from source url to cache and puts cache url into destination url key and thumbnail url key (where applicable).

XAO::ImageCache->download() will be executed for downloading each image.

download($$)

Downloads image into cache directory.

If thumbnails contains cache_path parameter, thumbnail is either downloaded into thumbnail cache directory or created from downloaded image.

Source image URL should be passed as parameter. Source thumbnail URL is an optional parameter:

    $img_cache->download($image_source_url, $thumbnail_source_url);

Downloaded image is resized if size parameter present. Thumbnail is resized as specified by thumbnails geometry parameter.

When reload configuration parameter is not set to True value, image will be downloaded into cache only if image is not already cached or if cached image has a later modification date than source image.

resize($$)

Scaling image to given size.

thumbnail($$$)

Creates thumbnail image from given source image.

Source image path and destination (thumbnail) path should be passed as parameters:

   $img_cache->thumbnail($source_path, $thumbnail_path);

Refer to thumbnail configuration parameter for additional information.

remove_cache($)

Removing ALL cache directory from disk.

Be carefully to use this methode!!!

Cache structure will be removed from disk completely! Set reload parameter to True value to download images to cache without any conditions.

cache_log($$)

Log activities to file.

Name of a log file may be set using log_file key of hash of configuration parameters or it will be a .cache_log in cache directory if log_file not defined.

Parameter should be an error or notice message.

get_filename($)

File name generation for cached images.

Source image URL should be passed. Returned file name is an MD5 digest of the source URL converted to Base64 string with all non alpha numeric characters are converted to _.

Example.

    Location: 
    http://localhost/icons/medbutton.jpeg
    
    provide file name:
    4aFNA1utpmCNG2wEIF69mg.jpeg
treat_filename($)

Makes sure only file name friendly characters are present: all non alpha numeric characters are converted to _.

CONFIGURATION PARAMETERS ^

The set of configuration parameters contain required and optional parameters.

Required parameters should be defined. Execution will be stoped if required parameter not present.

Optional parameters just configure aditional functionality and may not present.

Required parameters

cache_path

- Path string where the cache should be placed.

May be absolute or relative from current execution directory path.

For example. Set it to ./cache if you whant to place cache in cache subdirectory of your script working directory.

cache_url

- complet URL (or relative location) to cached images.

Place here your URL reflection of cache directory in condition with your HTTP server configuration.

For example. Set it to http://my.host.com/images/ if your HTTP server configured for provide access to your cache directory by hostname my.host.com and location images/. Cached images names will be added to image URL automaticaly.

list

- reference to XAO::DO::FS::List object containing the data objects with Image source URL

Meaning, your data look like a XAO Foundation Server list of objects with references to images. This parameter should contain reference to to XAO::DO::FS::List object. This reference may be result of XAO::Objects->fetch() methode.

XAO::ImageCache will process each record of this list.

source_url_key

- data key containing the URL of source image.

Contain the name of key of data object containing the source image reference.

Optional parameters

dest_url_key

- data key for storing URL of image in cache.

Optional parameter cause image name in cache will be a MD5 Base64 digest of source image path where = character removed, \ and + translated to _ and - simultaniosely.

To get cached image name

size

- Prefered image size may set as geometry equal to geometry parameter of Image::Magick module to pass it dirrectly to Image::Magick Scale function.

Other way to set the image size is set a width and height keys to preffered values.

If one of image dimension is not defined then corresponding parameter of original image will be used.

This way, image will be resized with same aspect ratio (same proportions) to the original image if save_aspect_ratio parameter present.

Image width and height will be resized exactly to given size if save_aspect_ratio parameter not present.

Parameter geometry has higher priority and other parameters has no effects if geometry peresent.

For example.

    # Size 320x200 as geometry settings
    %params = (size => {geometry => "320x200!"} );

    # Size 320x200 as dimensions settings
    %params = (size => {width => 320, height => 200} );

    # Feet size into 320x200 with saving image proportions
    %params = (        
        size => {
                width                   => 320,
                height                   => 200,
                save_aspect_ratio => 1,
                } );
autocreate

- create or check cache content automaticaly.

If non zero value present, cache directory will be created and images checking will be runned. Otherwithe you should run init() and check() methodes manualy.

Existent cache directory will not be removed. You may do it manualy using remove_cache() methode.

log_file

- log file name may be defined.

reload

- each image should be reloaded to cache and processed without dependance of source image modification time. Any conditions ignored.

thumbnail

- thumbnails creator configuration

Some thubnails configuration parameters may be set for automatic thumbnails creation. This parameter should contain the reference to hash with thumbnails configuration parameters.

Only path parameter is required. Other parameters are optional.

path

path where thumbnail images should be placed.

url

URL for access to thumbnails directory. Same way as cache_url.

url_key

Data object key name where thumbnail URL should be stored.

geometry

Geometry string to set thumbnail images size in Image Magick geometry format. May be set as dimension ("320x200!") or as persent of actual size of cached image ("25%").

Default value is "50%" the half of actual image size.

useragent

- configuration parameters hash for LWP::UserAgent

agent

Default value XAO-ImageCache/#.##

env_proxy

Default value 1

keep_alive

Default value 1

timeout

Default value 30

For more information please follow to LWP::UserAgent

SEE ALSO ^

Specifics of List API can be found in

XAO::DO::FS::List.

For additional information please see

XAO::DO::FS::Glue,

XAO::DO::FS::Global,

XAO::DO::FS::Glue::MySQL_DBI,

Refer to Image::Magick documentation for additional information about setting of image scaling parameters.

Refer to LWP::UserAgent documentation for additional information about user agent parameters.

BUGS ^

Please, inform me about found bugs.

AUTHORS ^

The XAO::ImageCache package maintained by Konstantin Safronov <skv@xao.com>. Specification by Andrew Maltsew <am@xao.com>

syntax highlighting: