NAME
CSS::SpriteBuilder - CSS sprite builder.
SYNOPSIS
use CSS::SpriteBuilder
my $builder = CSS::SpriteBuilder->new( [%args] );
$builder->build(
sprites => [{
file => 'sample_sprite_%d.png',
images => [
{ file => 'small/Add.png', [ %options ] },
],
[ %options ],
}],
);
$build->write_css('sprite.css');
Or
$builder->build(config => 'config.xml');
$build->write_css('sprite.css');DESCRIPTION
This module generate CSS sprites with one of these modules: Image::Magick or GD.
It has many useful settings and can be used for sites with complex structure.
METHODS
new(<%args>)
my $builder = CSS::SpriteBuilder->new(<%args>);
Create instance.
Valid arguments are:
source_dir [ = undef ]
Specify custom location for source images.
output_dir [ = undef ]
Specify custom location for generated images.
image_quality 0..100 [ = 90 ]
Specify image quality for generated images (for JPEG only).
max_image_size [ = 65536 ]
Specify max size of images that will be used to generate a sprite.
max_image_width [ = 2000 ]
Specify max width of images that will be used to generate a sprite.
max_image_height [ = 2000 ]
Specify max height of images that will be used to generate a sprite.
max_sprite_width [ = 2000 ]
Specify max width of sprite. When sprite has no free space, than creates a new sprite with addition of a suffix to the sprite name. Opera 9.0 and below have a bug which affects CSS background offsets less than -2042px. All values less than this are treated as -2042px exactly.
max_sprite_height [ = 2000 ]
Specify max height of sprite.
margin [ = 0 ]
Add margin to each image.
transparent_color [ = undef ]
Set transparent color for image, for example: 'white', 'black', ....
is_background [ = 0 ]
If is_background flag is '0' will be generated CSS rule such as: 'width:XXXpx;height:YYYpx;'.
layout [ = 'packed' ]
Specify layout algorithm (horizontal, vertical or packed).
css_selector_prefix [ = '.spr-' ]
Specify CSS selector prefix. For example, for an image "img/icon/arrow.gif" will be generated selector such as ".spr-img-icon-arrow".
css_url_prefix [ = '' ]
Specify prefix for CSS url. For example: background-image: url('css_url_prefixsample_sprite.png')
is_add_timestamp [ = 1 ]
If parameter set to '1' than timestamp will be added for CSS url. For example: background-image: url('sample_sprite.png?12345678')
build(<%args>)
Build sprites.
$builder->build(<%args>);This method returning structure like:
{
'sample_sprite_1.png' => [
{
'y' => 0,
'width' => 32,
'selector' => '.spr-small-add',
'is_background' => 0,
'x' => 0,
'height' => 32,
'image' => 'small/Add.png',
'repeat' => 'no'
},
...
],
...
}Valid arguments are:
sprites
Specify sprite list.
$builder->build( sprites => [ { file => 'horizontal_%d.png', layout => 'horizontal', max_sprite_width => 1000, ... images => [ { file => 'small/*.png', is_repeat => 1, ... }, { file => 'small/*.gif' }, { file => 'small/a.jpg', is_background => 1 }, ], }, { file => 'sprite_%d.png', max_sprite_width => 1000, css_selector_prefix => '#spr-', ... images => [ { file => 'small/Add.png', is_repeat => 1, ... }, ], }, ], );config
Specify XML config filename (it requires XML::LibXML module).
$builder->build(config => 'config.xml');Example of config.xml:
<root> <global_opts> <max_image_size>20000</max_image_size> <layout>packed</layout> <css_selector_prefix>.spr-</css_selector_prefix> <css_url_prefix>/sprite/</css_url_prefix> </global_opts> <sprites> <sprite file="sprite_%d.png"> <image file="small/Add.png"/> <image file="small/Box.png"/> <image file="medium/CD.png"/> </sprite> <sprite file="sprite_x_%d.png" layout="vertical"> <image file="small/Brick.png" is_repeat="1"/> <image file="small/Bin_Empty.png"/> <image file="medium/Close.png"/> </sprite> <sprite file="sprite_y_%d.png" layout="horizontal"> <image file="small/Pattern.png" is_repeat="1"/> <image file="small/Address_Book.png"/> <image file="medium/Chat.png"/> </sprite> </sprites> </root>
write_css([<filename|fh>])
Write CSS to file. When filename parameter is not specified than this method returning a string.
$builder->write_css('sprite.css');write_xml([<filename|fh>])
Write CSS sprites info structure into XML format (it requires XML::LibXML module). When filename parameter is not specified than this method returning a string.
$builder->write_xml('sprite.xml');Example of sprite.xml:
<root>
<sprite src="sample_sprite.png">
<image y="0" width="32" selector=".spr-small-add" is_background="0" x="0" height="32" repeat="no" image="small/Add.png"/>
</sprite>
</root>write_html([<filename|fh>])
Write HTML sample page. When filename parameter is not specified than this method returning a string.
get_sprites_info()
This method returning structure like:
{
'sample_sprite.png' => [
{
'y' => 0,
'width' => 32,
'selector' => '.spr-small-add',
'is_background' => 0,
'x' => 0,
'height' => 32,
'image' => 'small/Add.png',
'repeat' => 'no'
},
...
],
...
}AUTHOR
Yuriy Ustushenko, <yoreek@yahoo.com>
COPYRIGHT AND LICENSE
Copyright (C) 2013 Yuriy Ustushenko
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.