Attention

TYPO3 v11 has reached end-of-life as of October 31th 2024 and is no longer being maintained. Use the version switcher on the top left of this page to select documentation for a supported version of TYPO3.

Need more time before upgrading? You can purchase Extended Long Term Support (ELTS) for TYPO3 v10 here: TYPO3 ELTS.

Note on (+calc)

Whenever the +calc function is added to a value in the data type of the properties underneath, you can use the dimensions of TEXT and IMAGE objects from the GIFBUILDER object array. This is done by inserting a tag like this: [10.w] or [10.h], where 10 is the GIFBUILDER object number in the array and w/h signifies either width or height of the object.

The special property lineHeight (for example, [10.lineHeight]) uses the height a single line of text would take.

On using the special function max(), the maximum of multiple values can be determined. Example:

EXT:site_package/Configuration/TypoScript/setup.typoscript

XY = [10.w]+[20.w], max([10.h], [20.h])

Here is a full example:

EXT:site_package/Configuration/TypoScript/setup.typoscript

lib.example = IMAGE
lib.example {
  file = GIFBUILDER
  file {
  XY = [10.w]+20, [10.h]+20
  backColor = #ff8700
  format = png

  10 = TEXT
  10 {
    text = TYPO3 GIFBUILDER Example
    fontSize = 20
    fontColor = #ffffff
    offset = 10,25
  }
}

As you see, the image has a width/height defined as the width/height of the text printed onto it + 20 pixels.

The generated image looks like:

TYPO3 GIFBUILDER Example — The rendered image from the example above

_GIFBUILDER top level object

You can configure some global settings for GIFBUILDER by a top-level object named "_GIFBUILDER". One of the available properties of the global GIFBUILDER configuration is "charRangeMap".

.charRangeMap

By this property you can globally configure mapping of font files for certain character ranges. For instance you might need GIFBUILDER to produce gif files with a certain font for latin characters while you need to use another true type font for Japanese glyphs. So what you need is to specify the usage of another font file when characters fall into another range of Unicode values.

In the GIFBUILDER object this is possible with the "splitRendering" option but if you have hundreds of GIFBUILDER objects around your site it is not very efficient to add 5-10 lines of configuration for each time you render text. Therefore this global setting allows you to match the basename of the main font face with an alternative font.

Property

[array]

Data type

string

Description

Basename of font file to match for this configuration. Notice that only the filename of the font file is used - the path is stripped off. This is done to make matching easier and avoid problems when font files might move to other locations in extensions etc.

So if you use the font file "EXT:myext/fonts/vera.ttf" or "typo3/sysext/install/Resources/Private/Font/vera.ttf" both of them will match with this configuration.

The key:

The value of the array key will be the key used when forcing the configuration into "splitRendering" configuration of the individual GIFBUILDER objects. In the example below the key is "123".

Notice: If the key is already found in the local GIFBUILDER configuration the content of that key is respected and not overridden. Thus you can make local configurations which override the global setting.

Example: :

EXT:site_package/Configuration/TypoScript/setup.typoscript

_GIFBUILDER.charRangeMap {
  123 = vera.ttf
....

Property

[array].charMapConfig

Data type

TEXT / splitRendering.[array] configuration

Description

splitRendering configuration to set. See GIFBUILDER TEXT object for details.

Example: :

EXT:site_package/Configuration/TypoScript/setup.typoscript

_GIFBUILDER.charRangeMap {
  123 = arial.ttf
  123 {
    charMapConfig {
      fontFile = typo3/sysext/install/Resources/Private/Font/vera.ttf
      value = -65
      fontSize = 45
    }
    fontSizeMultiplicator = 2.3
  }
}

This example configuration shows that GIFBUILDER TEXT objects with font faces matching "arial.ttf" will have a splitConfiguration that uses "typo3/sysext/install/Resources/Private/Font/vera.ttf" for all characters that fall below/equal to 65 in Unicode value.

Property: [array].fontSizeMultiplicator
Data type: double
Description: If set, this will take the font size of the TEXT GIFBUILDER object and multiply with this amount (xx.xx) and override the "fontSize" property inside "charMapConfig".

Property

[array].pixelSpaceFontSizeRef

Data type

double

Description

If set, this will multiply the four [x/y]Space[Before/After] properties of split rendering with the relationship between the fontsize and this value.

In other words: Since pixel space may vary depending on the font size used you can simply specify by this value at what fontsize the pixel space settings are optimized and for other fontsizes this will automatically be adjusted according to this font size.

Example: :

EXT:site_package/Configuration/TypoScript/setup.typoscript

_GIFBUILDER.charRangeMap {
  123 = arial.ttf
  123 {
    charMapConfig {
      fontFile = typo3/sysext/install/Resources/Private/Font/vera.ttf
      value = 48-57
      color = green
      xSpaceBefore = 3
      xSpaceAfter = 3
    }
    pixelSpaceFontSizeRef = 24
  }
}

In this example xSpaceBefore and xSpaceAfter will be "3" when the font size is 24. If this configuration is used on a GIFBUILDER TEXT object where the font size is only 16, the spacing values will be corrected by "16/24", effectively reducing the pixelspace to "2" in that case.

[tsref:_GIFBUILDER.charRangeMap]