Sprite

h1. Documentation

{{>toc}}

h2. Installation

Just install the extension and include the "static setup":http://forge.typo3.org/projects/extension-sprite/repository/entry/trunk/Configuration/TypoScript/setup.txt to your template.

h2. Configuration tutorial

h3. Create my first sprite

It is very easy to setup the first sprite. Just create a folder and put some images in there, then use this snippet:

<pre><code>  page.5 < lib.sprite_generator

  page.5.userFunc {

  	name = whatever

  	directories.10 = fileadmin/templates/images/sprite/

  }</code></pre>

Set a unique name, which will be used as prefix for sprite classes. In this example the spriteclass will look like: tx-sprite-whatever-imagename.

You can define several directories, so it is used like an array (.10, .20, ...).

You need to assign the user-function call to the page node. Then the sprite will be created and the css file will attached to headerData.

h3. Use my first sprite

Now we have a cool sprite, but of course we want to use it in our template. Instead using the IMAGE cObject we use this:

<pre><code>  lib.logo < lib.spriteImage

  lib.logo.params = class="tx-sprite-whatever tx-sprite-whatever-logo" alt="The optional alt tag"

</code></pre>

We need to define two classes:

# The class of the sprite, which contains the image

# The class of the sprite part we want to show. It contains the automatic calculated background positions and the width and height of our image

This example tells us, that there exists an image _logo.png_ in the specified _fileadmin/templates/images/sprite/_ directory. The name of the image (without extension) will be taken as last part of the sprite classname.

The html output will be:

<pre><code class="html"><img src="typo3conf/ext/sprite/Resources/Public/Images/blank.gif" alt="The optional alt tag" class="tx-sprite-whatever tx-sprite-whatever-logo"></code></pre>

The sprite extension provides its own blank.gif (also known as spacer).

h3. Fill my sprite

You've got several possibilities to define which images should be part of the sprite:

# *directories* (array): An array of directories which contain images. The images will not be loaded recursive.

# *files* (array): The same like directories, but you have to enter files. Files will be checked if they exist.

# *files* (string): You can also assign a string to the files property, which should contains the filenames comma separated.

*Super flexibility:*

You can add typoscript instead of fixed paths. This makes it incredible flexible. One of the possibilities is the creation of a website-wide-sprite. That means a sprite which contains all used images (tt_content) on the entire website. Lower in the documentation you'll find a typoscript which creates such a sprite and replaces all tt_content outputs with the sprites. This is not always useful - you have to decide yourself if it is useful to you.

h3. Use my sprite dynamically

There exists a *lib.dynamicSpriteImage* which makes it a bit more dynamic to output sprite images.

<pre><code>10 < lib.dynamicSpriteImage

10.10.class.cObject = RECORDS

10.10.class.cObject {

  source.field = pid

  tables = pages

  conf.pages = TEXT

  conf.pages.field = abstract

  stdWrap.wrap = tx-sprite-whatever tx-sprite-whatever-section-|

}</code></pre>

This will output (if the current page got the section "company"):

<pre><code class="html"><img src="typo3conf/ext/sprite/Resources/Public/Images/blank.gif" alt="" class="tx-sprite-whatever tx-sprite-whatever-section-company"></code></pre>

h2. Configuration

_lib.sprite_generator.userFunc._

|*Attribute*|*Type*|*Default*|*Description*|

|name|string|mysprite|This name takes part of the sprite css classes and the filenames of css and image files. If you insert several sprites, it is necessary to keep them unique.|

|directories|array|_emtpy_|Each image containing in the given directories are used for the sprite. If you define several directories, the image filenames must be unique.|

|files|array/string|_emtpy_|Adds imagefiles to the sprite, can be used addionally to directories. You can define an array, like directories or add the files as comma separated string. Each file must contain the path, related to your htdocs. Example /fileadmin/images/myimage.png|

|linkCssFiles|boolean|1|Adds the css file with sprite classes to headerData. If false, just the files will be created but not linked.|

|useJpg|boolean|0|Normally sprites are existing out of gif and png files. But there are some situations where it is useful to combine jpg images. If this flag is true the output of sprite is jpg. It is strongly recommended that the input images are jpg too.|

|iconSpace|integer|2|Pixels between the single images in spriteimage.|

|includeTimestampInCSS|boolean|false|If true a unixtimestamp are append to spriteimage background definition in css file.|

h2. The whole website sprite

The following two snippets shows how to create a sprite image for all inserted images on all pages of your website. The first shows how to collect the informations and assign them to the sprite extension and the second shows how to replace the default image output with the sprite output (blank.gif image and css classes).

The script has not been optimized yet. It just works.

h3. Creating the sprite

<pre>

# get all page uids (comma separated)

lib.page_uids = CONTENT

lib.page_uids {

	table = pages

	select {

		pidInList = 1

		recursive = 9

	}

	renderObj = COA

	renderObj {

		10 = TEXT

		10 {

			field = uid

			stdWrap.wrap = |,

		}

	}

}

# get all images as comma separated files with full paths

lib.overallSprite = CONTENT

lib.overallSprite {

	table = tt_content

	select {

		pidInList.stdWrap.cObject < lib.page_uids

		recursive = 9

		andWhere = image IS NOT NULL

	}

	renderObj = COA

	renderObj {

		30 < tt_content.image.20

	}

	stdWrap {

		HTMLparser.tags.img.allowedAttribs = src

		split {

			token = >

			cObjNum = 1

			1 = TEXT

			1.current = 1

			1.stdWrap.split {

				token = "

				cObjNum = 1

				returnKey = 1

				1.current = 1

			}

			1.wrap = |,

		}

	}

}

</pre>

h3. Replacing all tt_content images with sprites

<pre>

page.1331568638 < lib.sprite_generator

page.1331568638.userFunc {

	name = overall

	files < lib.overallSprite

	useJpg = 1

}

tt_content.image.20.1 {

	stdWrap {

		HTMLparser.tags.img.allowedAttribs = src

		split {

			token = >

			cObjNum = 1

			1 = TEXT

			1.current = 1

			1.stdWrap.split {

				token = "

				cObjNum = 1 || 2

				2 = TEXT

				2.current = 1

				2.split {

					token = /

					cObjNum = 1 || 2 || 3

					3 = TEXT

					3.current = 1

					3.split {

						token = .

						cObjNum = 1 || 2

						1 = COA

						1 {

							10 = LOAD_REGISTER

							10.spriteclass.cObject = TEXT

							10.spriteclass.cObject.current = 1

							20 < lib.spriteImage

							20.params = class="tx-sprite-overall tx-sprite-overall-{register:spriteclass}"

							20.params.insertData = 1

						}

					}

				}

			}

		}

	}

}

</pre>

h3. Create one sprite for every site (haha, a rime^^)

The script above shows you how to create one sprite for the entire website, but maybe you want to create one sprite for one page, not for all pages.

Then you have to find this part:

<pre>lib.overallSprite {

	table = tt_content

	select {

		pidInList.stdWrap.cObject < lib.page_uids

	}

}</pre>

It assigns all page_uids (@lib.page_uids@). Here you have to add just the current page uid:

<pre>lib.overallSprite {

	table = tt_content

	select {

		pidInList.data = page:uid

	}

}</pre>

*This script is not tested yet, maybe it is okay just leave pidInList empty.*