Skip to content

Latest commit

 

History

History
333 lines (227 loc) · 8.21 KB

index.rst

File metadata and controls

333 lines (227 loc) · 8.21 KB
Raw

Overview

Contents:

.. toctree::
   :maxdepth: 2

Installation

Composer

Add the following entry to your composer.json:

{ "require": { "fermio/sprites": "0.3.*@dev" }}

Checkout detailed package information on Packagist.

Clone from GitHub

Clone Sprites git repository:

git clone git://github.com/fermio/Sprites.git

Download composer.phar file and install dependencies:

wget -nc http://getcomposer.org/composer.phar
php composer.phar install

Run sprites executable from bin directory:

php bin/sprites

Configuration

A simple configuration of a Fermio\Sprites\ProcessorInterface requires a Fermio\Sprites\Configuration instance

<?php

use Fermio\Sprites\Configuration;
use Fermio\Sprites\Processor\DynamicProcessor;
use Imagine\Gd\Imagine;
use Imagine\Image\Color;

$imagine = new Imagine();

$config = new Configuration();
$config->setImagine($imagine);
$config->setColor(new Color('fff', 100));
$config->setImage('web/images/icons.png');
$config->setStylesheet('web/css/icons.css');
$config->getFinder()->name('*.png')->in('web/images/icons');
$config->setSelector(".icon.{{filename}}{background-position:{{x}}px {{y}}px}\n");

$processor = new DynamicProcessor();
$processor->process($config);

// ...

Configuration Options

The following sections describe all the configuration options available on a Fermio\Sprites\Configuration instance.

Imagine (*REQUIRED*)

<?php
$config->setImagine($imagine);
$config->getImagine();

The Imagine\ImagineInterface instance to use.

Options (*RECOMMENDED*)

<?php
$config->setOptions($options);
$config->getOptions();

An array of options for the Imagine\Image\ManipulatorInterface::save() method.

Note

Each Imagine\ImageInterface adapter has its own subset of options.

Finder (*REQUIRED*)

<?php
$config->setFinder($finder);
$config->getFinder();

The Symfony\Component\Finder\Finder instance used to find files for your sprites.

Note

To unleash the full power of this component, read the Finder documentation.

Image (*REQUIRED*)

<?php
$config->setImage($path);
$config->getImage();

The path to the target image sprite.

Note

If the directory does not exist yet, it will automatically be created.

Color (*OPTIONAL*)

<?php
$config->setColor($color);
$config->getColor();

The Imagine\Image\Color instance to use as background color.

Processor (*OPTIONAL*)

<?php
$config->setProcessor($processor);
$config->getProcessor();

The name of the Fermio\Sprites\Processor\ProcessorInterface to use. This configuration value is only needed if you use the Fermio\Sprites\Generator and may be guessed automatically, depending if you set a fixed width or not.

Note

Sprites already supports two different kind of processors:

  • dynamic: Fermio\Sprites\Processor\DynamicProcessor
  • fixed: Fermio\Sprites\Processor\FixedProcessor

Width (*OPTIONAL*)

<?php
$config->setWidth($width);
$config->getWidth();

A fixed width for each image in the sprite. This configuration value is only used in the Fermio\Sprites\Processor\FixedProcessor and speeds up generating the image sprite.

Note

The Fermio\Sprites\Processor\FixedProcessor could optionally resize your images if they exceed the fixed width.

Stylesheet (*REQUIRED*)

<?php
$config->setStylesheet($path);
$config->getStylesheet();

The path to the target stylesheet.

Note

If the directory does not exist yet, it will automatically be created.

Selector (*OPTIONAL*)

<?php
$config->setSelector($selector);
$config->getSelector();

A string parsed for each image, to be used as the CSS in the generated stylesheet.

Note

The default value of the selector is ".{{filename}}{background-position:{{x}}px {{y}}px}\n".

Note

The string is parsed with two available parameters:

  • ``{{x}}``: horizontal position of current pointer (in px)
  • ``{{y}}``: vertical position of current pointer (in px)
  • ``{{filename}}``: an ASCIIfied version of the filename.

Usage

Processor

DynamicProcessor

The DynamicProcessor class is used to generate image sprites from images with a dynamic width and height.

<?php

use Fermio\Sprites\Configuration;
use Fermio\Sprites\Processor\DynamicProcessor;

$config = new Configuration();
// ... configure your configuration

$processor = new DynamicProcessor();
$processor->process($config);

FixedProcessor

The FixedProcessor class works similar to the DynamicProcessor. There are two main differences:

  • the getWidth() configuration value is used to determine the absolute width of the final image sprite, to spare recalculating the absolute width each time a new image is pasted into the sprite.
  • you can optionally enable resizing, resulting in images exceeding the fixed width to be scaled down with a correct aspect ratio to fit the fixed width.

Note

The height of the image sprite is still calculated dynamically, but ideally only once (e.g. if you use famfamfam icons which usually are dimensioned in 16px x 16px, the first image sets the sprites' height to 16px and then the height must not be adjusted again).

<?php

use Fermio\Sprites\Configuration;
use Fermio\Sprites\Processor\FixedProcessor;

$config = new Configuration();
$config->setWidth(16); // fixed width of 16px per image
// ... configure your configuration

$processor = new FixedProcessor(array('resize' => true));
$processor->process($config);

Generator

The Fermio\Sprites\Generator class is used for batch processing multiple Fermio\Sprites\Configuration instances with their corresponding Fermio\Sprites\Processor\ProcessorInterface instances.

<?php

use Fermio\Sprites\Configuration;
use Fermio\Sprites\Generator;
use Fermio\Sprites\Processor\DynamicProcessor;
use Fermio\Sprites\Processor\FixedProcessor;
// ... add your processor classes

$generator = new Generator();

$config = new Configuration();
// ... configure your configuration
$generator->addConfiguration($config);
// ... add your configurations

$dynamic = new DynamicProcessor();
$generator->addProcessor($dynamic);
$fixed = new FixedProcessor();
$generator->addProcessor($fixed);
// ... add your processors

$generator->generate();

Command Line Interface

The Sprites console is a Command Line Interface tool for simplifying the usage and generation of image sprites without the need of you actually writing a single line of PHP code.

sprites generate:dynamic

The generate:dynamic command generates image sprites and CSS stylesheets with dynamic dimensions:

php bin/sprites generate:dynamic --help

sprites generate:fixed

The generate:fixed command generates image sprites and CSS stylesheets with a fixed width dimension:

php bin/sprites generate:fixed --help