Documentation¶

• Documentation
  • Installation
  • Configuration tutorial
    • Create my first sprite
    • Use my first sprite
    • Fill my sprite
    • Use my sprite dynamically
  • Configuration
  • The whole website sprite
    • Creating the sprite
    • Replacing all tt_content images with sprites

Installation¶

Just install the extension and include the static setup to your template.

Configuration tutorial¶

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:

  page.5 < lib.sprite_generator
  page.5.userFunc {
      name = whatever
      directories.10 = fileadmin/templates/images/sprite/
  }

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.

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:

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

We need to define two classes:

1. The class of the sprite, which contains the image
2. 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:

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

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

Fill my sprite¶

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

1. directories (array): An array of directories which contain images. The images will not be loaded recursive.
2. files (array): The same like directories, but you have to enter files. Files will be checked if they exist.
3. 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.

Use my sprite dynamically¶

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

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-|
}

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

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

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.

The whole website sprite¶

Creating the sprite¶

# get all page uids (comma separated)
lib.page_uids = CONTENT
lib.page_uids {
    table = pages
    select {
        pidInList = 24
        recursive = 9
    }
    renderObj = COA
    renderObj {
        10 = TEXT
        10 {
            field = uid
            stdWrap.wrap = |,
        }
    }
}

# get all images as comma separated paths (should rename this lib)
lib.contents = CONTENT
lib.contents {
    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 = |,
        }
    }
}

Replacing all tt_content images with sprites¶

page.1331568638 < lib.sprite_generator
page.1331568638.userFunc {
    name = overall
    files < lib.contents
    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
                        }
                    }
                }
            }
        }
    }
}