NAME
CSS::SpriteMaker - Combine several images into a single CSS sprite
VERSION
Version 0.03
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({
rc_filename_to_classname => sub { my $filename = shift; ... },
source_dir => '/tmp/test/images', # optional
target_file => '/tmp/test/mysprite.png' # optional
remove_source_padding => 1, # optional
verbose => 1, # optional
});Default values are set to:
The parameter rc_filename_to_classname is a code reference to a function that allow to customize the way class names are generated. This function should take one parameter as input and return a class name
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,
},
...more
]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 (excluding the prepended ".").
_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. A Layout actually runs over the specified items on instantiation.
Parameters in %options (see code) that allow us to obtain a $Layout object are:
- layout: a CSS::SpriteMaker::Layout object already; - layout: can also be a hashref like { name => 'LayoutName', options => { 'Layout-Specific option' => 'value', ... } } - 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.