CSS::SpriteMaker(3)

NAME
CSS::SpriteMaker - Combine several images into a single CSS sprite

VERSION
Version 0.01

SYNOPSIS
    use CSS::SpriteMaker;

    my $SpriteMaker = CSS::SpriteMaker->new(
        verbose => 1, # optional
        rc_filename_to_classname => sub { my $filename = shift; ... } # optional
    );

    $SpriteMaker->make_sprite(
        source_images  => ['/path/to/imagedir', '/images/img1.png', '/img2.png'];
        target_file => '/tmp/test/mysprite.png',
        layout_name => 'Packed',    # optional
        remove_source_padding => 1, # optional
        format => 'png8',           # optional
    );

    $SpriteMaker->print_css();

    $SpriteMaker->print_html();

    OR

    my $SpriteMaker = CSS::SpriteMaker->new();

    $SpriteMaker->make_sprite(
       source_dir => '/tmp/test/images',
       target_file => '/tmp/test/mysprite.png',
    );

    $SpriteMaker->print_css();

    $SpriteMaker->print_html();

DESCRIPTION
A CSS Sprite is an image obtained by arranging many smaller images on a 2D canvas, according to a certain layout.

Transferring one larger image is generally faster than transferring multiple images separately as it greatly reduces the number of HTTP requests (and overhead) necessary to render the original images on the browser.

PUBLIC METHODS

  new
Create and configure a new CSS::SpriteMaker object.

The object can be initialised as follows:

    my $SpriteMaker = CSS::SpriteMaker->new({
        source_dir => '/tmp/test/images',       # optional
        target_file => '/tmp/test/mysprite.png' # optional
        remove_source_padding => 1, # optional
        verbose => 1,               # optional
    });

    $opts{remove_source_padding} //= 1;
    $opts{verbose}               //= 0;
    $opts{format}                //= 'png';

  make_sprite
Creates the sprite file out of the specifed image files or directories, and according to the given layout name.

my $is_error = $SpriteMaker->make_sprite(
    source_images => ['some/file.png', path/to/some_directory],
    target_file => 'sample_sprite.png',
    layout_name => 'Packed',

    # all imagemagick supported formats
    format => 'png8', # optional, default is png
);

returns true if an error occurred during the procedure.

Available layouts are:

- Packed: try to pack together the images as much as possible to reduce the
  image size.

- DirectoryBased: put images under the same directory on the same horizontal
  line. Within each line, order alphabetically.

  print_css
Creates and prints the css stylesheet for the sprite that was previously produced.

$SpriteMaker->print_css(
   filehandle => $fh, );

OR

$SpriteMaker->print_css(
   filename => 'relative/path/to/style.css', );

NOTE: make_sprite() must be called before this method is called.

  print_html
Creates and prints an html sample page containing informations about each sprite produced.

$SpriteMaker->print_html(
   filehandle => $fh, );

OR

$SpriteMaker->print_html(
   filename => 'relative/path/to/index.html', );

NOTE: make_sprite() must be called before this method is called.

  get_css_info_structure
Returns an arrayref of hashrefs like:

[
    {
        full_path => 'relative/path/to/file.png',
        css_class => 'file',
        width => 16, # pixels
        height => 16,
        x => 173, # offset within the layout
        y => 234,
    },
    ... ]

This structure can be used to build your own html or css stylesheet for example.

NOTE: the x y offsets within the layout, will be always positive numbers.

PRIVATE METHODS

  _generate_css_class_names
Returns a mapping id -> class_name out of the current information structure.

It guarantees unique class_name for each id.

  _image_locations_to_source_info
Identify informations from the location of each input image.

  _locate_image_files
Finds the location of image files within the given directory. Returns an arrayref of hashrefs containing information about the names and pathnames of each image file.

The returned arrayref looks like:

[ # pathnames of the first image to follow
    {
        name => 'image.png',
        pathname => '/complete/path/to/image.png',
        parentdir => '/complete/path/to',
    },
    ... ]

Dies if the given directory is empty or doesn't exist.

  _get_stylesheet_string
Returns the stylesheet in a string.

  _generate_css_class_name
This method generates the name of the CSS class for a certain image file. Takes the image filename as input and produces a css class name (including the .)

  _ensure_filehandle_write
Inspects the input %options hash and returns a filehandle according to the parameters passed in there.

The filehandle is where something (css stylesheet for example) is going to be printed.

  _ensure_sources_info
Makes sure the user of this module has provided a valid input parameter for sources_info and return the sources_info structure accordingly. Dies in case something goes wrong with the user input.

Parameters that allow us to obtain a $rh_sources_info structure are:

- source_images: an arrayref of files or directories, directories will be
  visited recursively and any image file in it becomes the input.

If none of the above parameters have been found in input options, the cache is checked before giving up - i.e., the user has previously provided the layout parameter, and was able to generate a sprite.

  _ensure_layout
Makes sure the user of this module has provided valid layout options and returns a $Layout object accordingly. Dies in case something goes wrong with the user input.

Parameters that allow us to obtain a $Layout object are:

- layout: a CSS::SpriteMaker::Layout object already; - layout_name: the name of a CSS::SpriteMaker::Layout object.

If none of the above parameters have been found in input options, the cache is checked before giving up - i.e., the user has previously provided the layout parameter...

  _get_image_properties
Return an hashref of information about the image at the given pathname.

  _generate_color_histogram
Generate color histogram out of the information structure of all the images.

  _verbose
Print verbose output only if the verbose option was passed as input.

LICENSE AND COPYRIGHT
Copyright 2013 Savio Dimatteo.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.