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.

cpanm CSS::SpriteBuilder

perl -MCPAN -e shell
install CSS::SpriteBuilder