GIFBUILDER is an object, which is used in many situations for creating gif-files. Anywhere the ->GIFBUILDER object is mentioned, these are the properties that apply.
Using TypoScript you can define a "numerical array" of "GIFBUILDER OBJECTS" (like "TEXT", "IMAGE", etc.) and they will be rendered onto an image one by one.
The name "GIFBUILDER" comes from the time where GIF was the only file format supported. PNG and JPG are just as well to create today (configured with $TYPO3_CONF_VARS['GFX']).
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 GifBuilderObj-array. This is done by inserting a tag like this: "[10.w]" or "[10.h]", where "10" is the GifBuilderObj-number in the array and "w"/"h" signifies either width or height of the object.
The special property "lineHeight" (e.g. "[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:
XY: [10.w]+[20.w], max([10.h], [20.h])
Here's a full example (taken from "styles.content (default)"):
styles.header.gfx1 = IMAGE
styles.header.gfx1 { wrap = {$styles.header.gfx1.wrap}file = GIFBUILDER
file { XY = [10.w]+10 ,{$styles.header.gfx1.itemH} backColor = {$styles.header.gfx1.bgCol} reduceColors = {$styles.header.gfx1.reduceColors}10 = TEXT
10 {text.current = 1
text.crop = {$styles.header.gfx1.maxChars} fontSize = {$styles.header.gfx1.fontSize} fontFile = {$styles.header.gfx1.file.fontFile} fontColor = {$styles.header.gfx1.fontColor} offset = {$styles.header.gfx1.fontOffset}}
}
}
As you see, the gif-image has a width defined as the width of the text printed onto it + 10 pixels. The height is fixed by the value of the constant {$styles.header.gfx1.itemH}
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: | Data type: | Description: | Default: |
|---|---|---|---|
[array] | string | 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/arial.ttf" or "t3lib/fonts/arial.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: _GIFBUILDER.charRangeMap { 123 = arial.ttf .... | |
[array].charMapConfig | TEXT / splitRendering.[array] configuration | splitRendering configuration to set. See GIFBUILDER TEXT object for details. Example: _GIFBUILDER.charRangeMap { 123 = arial.ttf 123 { charMapConfig { fontFile = t3lib/fonts/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 "t3lib/fonts/vera.ttf" for all characters that fall below/equal to 65 in Unicode value. | |
[array].fontSizeMultiplicator | double | 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". | |
[array].pixelSpaceFontSizeRef | double | 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: _GIFBUILDER.charRangeMap { 123 = arial.ttf 123 { charMapConfig { fontFile = t3lib/fonts/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]
Whenever you see a reference to anything named an "object" in this section it's a reference to a "GifBuilderObj" and not the "cObjects" from the previous section. Confusion could happen, because both "IMAGE" and "TEXT" is an object in both areas.
Property: | Data type: | Description: | Default: |
|---|---|---|---|
1,2,3,4... | GifBuilderObj + .if (->if) | .if (->if) is a property of all gifbuilder-objects. If the property is present and NOT set, the object is NOT rendered! This corresponds to the functionality of ".if" of the stdWrap-function. | |
XY | x,y +calc /stdWrap | Size of the gif-file. For the usage of "calc" see the according note on that at the beginning of the section "GIFBUILDER". | 100,20 |
format | "gif" / "jpg" | Output type. "jpg"/"jpeg" = jpg-image | gif |
reduceColors | posint (1-255) /stdWrap | Reduce the number of colors (if gif-file) | |
transparentBackground | boolean /stdWrap | Set this flag to render the background transparent. TYPO3 makes the color found at position 0,0 of the image (upper left corner) transparent. If you render text, you should leave the niceText option OFF as the result will probably be more precise without the niceText antialiasing hack. | |
transparentColor | HTMLColor /stdWrap | Specify a color that should be transparent Example-values: #ffffcc red 255,255,127 Option: transparentColor.closest = 1 This will allow for the closest color to be matched instead. You may need this if you image is not guaranteed "clean". NOTE: You may experience that this doesn't work if you use the reduceColors-option or render text with niceText-option. | |
quality | posint (10-100) | JPG-quality (if ".format" = jpg/jpeg) | |
backColor | GraphicColor /stdWrap | Background color for the gif. | white |
offset | x,y +calc /stdWrap | Offset all objects on the gif. | 0,0 |
workArea | x,y,w,h + calc /stdWrap | Define the workarea on the giffile. All the GifBuilderObj's will see this as the dimensions of the gif-file regarding alignment, overlaying of images an so on. Only TEXT-objects exceeding the boundaries of the workarea will be printed outside this area. | |
maxWidth | pixels /stdWrap | Maximal width of the gif-file. | |
maxHeight | pixels /stdWrap | Maximal height of the gif-file. |
[tsref:->GIFBUILDER]
Property: | Data type: | Description: | Default: |
|---|---|---|---|
text | ->stdWrap | This is text text-string on the gif-file. The item is rendered only if this string is not empty. The cObj->data-array is loaded with the page-record, if for example the GIFBUILDER-object is used by GMENU or IMGMENU. | |
breakWidth | integer /stdWrap | Defines the maximum width for an object, overlapping elements will force an automatic line break. | |
breakSpace | float | Defines a value that is multiplied by the line height of the current element. | 1.0 |
textMaxLength | int | The maximum length of the text. This is just a natural break that prevents incidental rendering of very long texts! | 100 |
maxWidth | pixels /stdWrap | Sets the maximum width in pixels, the text must be. Reduces the fontSize if the text does not fit within this width. Does not support setting alternative fontSizes in splitRendering options. (By René Fritz <r.fritz@colorcube.de>) | |
doNotStripHTML | boolean | If set, HTML-tags in the string inserted are NOT removed. Any other way HTML-code is removed by default! | 0 |
fontSize | posint | Font size | 12 |
fontColor | GraphicColor /stdWrap | Font color | black |
fontFile | resource | Font face (truetype font you can upload!) | Nimbus (Arial-clone) |
angle | degree | Rotation degrees of the text. Note: Angle is not available if spacing/wordSpacing is set. | 0 Range: -90 til 90 |
align | align | Alignment of the text | left |
offset | x,y +calc /stdWrap | Offset of the text | 0,0 |
antiAlias | boolean | FreeType antialiasing. Notice, the default mode is "on"! Note: This option is not available if .niceText is enabled. | 1 |
iterations | posint | How many times the text should be "printed" onto it self. This will add the effect of bold text. Note: This option is not available if .niceText is enabled. | 1 |
spacing | posint | Pixel-distance between letters. This may render ugly! | 0 |
wordSpacing | posint | Pixel-distance between words. | = ".spacing"*2 |
hide | boolean | If this is true, the text is NOT printed. This feature may be used if you need a shadow-object to base a shadow on the text, but do not want the text to print. | 0 |
hideButCreateMap | boolean | If this option is set, the text will not be rendered. Shadows and emboss will, though, so don't apply these!! But this feature is also meant only to enable a text to generate the imageMap coordinates without rendering itself. | |
emboss | GifBuilderObj->EMBOSS | ||
shadow | GifBuilderObj->SHADOW | ||
outline | GifBuilderObj->OUTLINE | ||
imgMap | ->IMGMAP ->stdWrap properties for "altText" and "titleText" in this case | ||
niceText | boolean | This is a very popular feature that helps to render small letters much nicer than the freetype library can normally do. But it also loads the system very much! The principle of this function is to create a black/white giffile in twice or more times the size of the actual gif-file and then print the text onto this in a scaled dimension. Afterwards ImageMagick (IM) scales down the mask and masks the font color down on the original gif-file through the temporary mask. The fact that the font is actually rendered in the double size and scaled down adds a more homogenous shape to the letters. Some fonts are more critical than others though. If you do not need the quality, then don't use the function. Some properties: .before = IM-params before scale .after = IM-params after scale .sharpen = sharpen-value for the mask (after scaling), integer 0-99 (this enables you to make the text crisper if it's too blurred!) .scaleFactor = scaling-factor, int 2-5 | |
splitRendering.compX splitRendering.compY splitRendering.[array] | Split the rendering of a string into separate processes with individual configurations. By this method a certain range of characters can be rendered with another font face or size. This is very useful if you want to use separate fonts for strings where you have latin characters combined with e.g. Japanese and there is a separate font file for each. You can also render keywords in another font/size/color. Properties: splitRendering.compX = Additional pixelspace between parts, x direction splitRendering.compY = Additional pixelspace between parts, y direction splitRendering.[array] = keyword [charRange, highlightWord] splitRendering.[array] { fontFile = Alternative font file for this rendering fontSize = Alternative font size for this rendering color = Alternative color for this rendering, works ONLY without "niceText" xSpaceBefore = x-Space before this part xSpaceAfter = x-Space after this part ySpaceBefore = y-Space before this part ySpaceAfter = y-Space after this part } Keyword: charRange splitRendering.[array].value = Commaseparated list of character ranges (eg. "100-200") given as Unicode character numbers. The list accepts optional starting and ending points, eg. " - 200" or " 200 -" and single values, eg. "65, 66, 67" Keyword: highlightWord splitRendering.[array].value = Word to highlight, makes a case sensitive search for this. Limitations:
Example: 10.splitRendering.compX = 2 10.splitRendering.compY = -2 10.splitRendering.10 = charRange 10.splitRendering.10 { value = 200-380 , 65, 66 fontSize = 50 fontFile = t3lib/fonts/nimbus.ttf xSpaceBefore = 30 } 10.splitRendering.20 = highlightWord 10.splitRendering.20 { value = TheWord color = red } |
[tsref:->GIFBUILDER.(GBObj).TEXT]
Property: | Data type: | Description: | Default: |
|---|---|---|---|
textObjNum | pos-int | Must point to the TEXT-object if these shadow-properties are not properties to a TEXT-object directly ("stand-alone-shadow"). Then the shadow needs to know which TEXT-object it should be a shadow of! If - on the other hand - the shadow is a property to a text-object, this property is not needed. | |
offset | x,y | Shadow offset | |
color | GraphicColor | Shadow color | |
blur | posint (1-99) | Blurring of the shadow. Above 40 only values of 40,50,60,70,80,90 mean something. Note: Unfortunately the blurring capabilities of ImageMagick are not very mature in version 4.2.9. This is addressed in the later version 5.2.0 where a gaussian blur-function is added. BUT as we cannot use the latest ImageMagick development yet, this is not utilized so far. | |
opacity | posint (1-100) | Opacity (transparency^-1) 100% opacity = 0% transparency). Only active with a value for blur. | |
intensity | posint(0-100) | How "massive" the shadow is. This value can - if it has a high value combined with a blurred shadow - create a kind of soft-edged outline. |
[tsref:->GIFBUILDER.(GBObj).SHADOW]
Emboss is actually two shadows offset in opposite directions and with different colors as to create an effect of light cast onto an embossed text.
Property: | Data type: | Description: | Default: |
|---|---|---|---|
textObjNum | pos-int | Must point to the TEXT-object if these shadow-properties are not properties to a TEXT-object directly ("stand-alone-shadow"). Then the shadow needs to know which TEXT-object it should be a shadow of! If - on the other hand - the shadow is a property to a text-object, this property is not needed. | |
offset | x,y | Offset of the emboss | |
highColor | GraphicColor | Upper border-color | |
lowColor | GraphicColor | lower border-color | |
blur | posint (1-99) | Blurring of the shadow. Above 40 only values of 40,50,60,70,80,90 means something. | |
opacity | posint (1-100) | Opacity (transparency^-1) 100% opacity = 0% transparency). Only active with a value for blur. | |
intensity | posint(0-100) | How "massive" the emboss is. This value can - if it has a high value combined with a blurred shadow - create a kind of soft-edged outline. |
[tsref:->GIFBUILDER.(GBObj).EMBOSS]
This outline normally renders quite ugly as it's done by printing 4 or 8 texts underneath the text in question. Try to use a shadow with a high intensity. That works better!
Property: | Data type: | Description: | Default: |
|---|---|---|---|
textObjNum | pos-int | Must point to the TEXT-object if these shadow-properties are not properties to a TEXT-object directly ("stand-alone-shadow"). Then the shadow needs to know which TEXT-object it should be a shadow of! If - on the other hand - the shadow is a property to a text-object, this property is not needed. | |
thickness | x,y | Thickness in each direction, range 1-2 | |
color | GraphicColor | Outline color |
[tsref:->GIFBUILDER.(GBObj).OUTLINE]
Property: | Data type: | Description: | Default: |
|---|---|---|---|
dimensions | x,y,w,h +calc /stdWrap | Dimensions of a filled box. x,y is the offset. w,h are the dimensions. Dimensions of 1 will result in 1-pixel wide lines! | |
color | GraphicColor | fill-color | black |
opacity | pos-int (1-100) | Opacity (i.e. inverse of transparency, e.g. 100% opacity = 0% transparency) | 100 |
align | VHalign | Pair of values, which defines the horizontal and vertical alignment. Values: Horizontal alignment: r/c/l standing for right, center, left Vertical alignment: t/c/b standing for top, center, bottom Example: Horizontally centered, vertically at the bottom: align = c, b | l, t |
[tsref:->GIFBUILDER.(GBObj).BOX]
Property: | Data type: | Description: | Default: |
|---|---|---|---|
dimensions | x,y,w,h +calc /stdWrap | Dimensions of a filled ellipse. x,y is the offset. w,h are the dimensions. Dimensions of 1 will result in 1-pixel wide lines! | |
color | GraphicColor | fill-color Example: file = GIFBUILDER file { XY = 200,200 format = jpg quality = 100 10 = ELLIPSE 10.dimensions = 100,100,50,50 10.color = red } | black |
Property: | Data type: | Description: | Default: |
|---|---|---|---|
file | imgResource | The imagefile | |
offset | x,y +calc /stdWrap | Offset of the image | 0,0 |
tile | x,y | tile x,y times. Maximum times is 20 each direction. If you need more, use a larger image. | |
align | VHalign | See in the "Data types reference" at the beginning of this document or in the table "BOX". | |
mask | imgResource | Optional mask-image for the imagefile. |
[tsref:->GIFBUILDER.(GBObj).IMAGE]
lib.image = IMAGE
lib.image {file = GIFBUILDER
file {XY = 1024,768
format = jpg
10 = IMAGE
10.file = fileadmin/image.jpg
20 = EFFECT
20.value = gamma=1.3 | flip | rotate=180
}
}
Property: | Data type: | Description: | Default: |
|---|---|---|---|
gamma | 0.5 - 3.0 | Sets the gamma value. | 1.0 |
blur | 1-99 | Blurs the edges inside the image. | 0 |
sharpen | 1-99 | Sharpens the edges inside the image. | 0 |
solarize | 0-99 | Color reduction. | |
swirl | 0-100 | The image is swirled or spun from its center. | 0 |
wave | amplitude, length | All horizontal edges are transformed by a wave with the given amplitude and length. Maximum value for amplitude and length is 100. Example: 20 = EFFECT 20.value = wave=1,20 | |
charcoal | 0-100 | Makes the image look as if it had been drawn with charcoal and defines the intensity of that effect. | |
gray | - | The image is converted to gray tones. Example: This gives the image a slight wave and renders it in gray. 20 = EFFECT 20.value = wave=1,20 | gray | |
edge | 0-99 | Creates rounded edges. | |
emboss | - | Creates a relief effect: Creates highlights or shadows that replace light and dark boundaries in the image. | |
flip | - | Vertical flipping. | |
flop | - | Horizontal flipping. | |
rotate | 0-360 | Number of degrees for a clockwise rotation. Image dimensions will grow if needed, so that nothing is cut off from the original image. | 0 |
colors | 2-255 | Defines the number of different colors to use in the image. | |
shear | -90 - 90 | Horizontal shearing. | |
invert | - | Invert the colors. |
[tsref:->GIFBUILDER.(GBObj).EFFECT]
Sets another workarea.
Property: | Data type: | Description: | Default: |
|---|---|---|---|
set | x,y,w,h + calc /stdWrap | Sets the dimensions of the workarea. x,y is the offset. w,h are the dimensions. For the usage of "calc" see the according note at the beginning of the section "GIFBUILDER". | |
clear | (isset) | Sets the current to the default. Checked for using isset(). |
[tsref:->GIFBUILDER.(GBObj).WORKAREA]
Note: This object resets workArea to the new dimensions of the image!
Property: | Data type: | Description: | Default: |
|---|---|---|---|
backColor | GraphicColor | See "Data types reference". | The original backColor |
align | VHalign | Horizontal and vertical alignment of the crop frame. See "Data types reference". | l, t |
crop | x,y,w,h + calc /stdWrap | x,y is the offset of the crop-frame from the position specified by "align". w,h are the dimensions of the frame. For the usage of "calc" see the according note at the beginning of the section "GIFBUILDER". |
[tsref:->GIFBUILDER.(GBObj).CROP]
Note: This object resets workArea to the new dimensions of the image!
Property: | Data type: | Description: | Default: |
|---|---|---|---|
width | pixels + calc /stdWrap | Width of the scaled image. | |
height | pixels + calc /stdWrap | Height of the scaled image. | |
params | ImageMagickParams | Parameters to be used for the processing. |
[tsref:->GIFBUILDER.(GBObj).SCALE]
This lets you adjust the tonal range like in the "levels"-dialog of Photoshop. You can set the input- and output-levels and that way remap the tonal range of the image. If you need to adjust the gamma value, have a look at the EFFECT-object.
20 = ADJUST
20.value = inputLevels = 13, 230
Property: | Data type: | Description: | Default: |
|---|---|---|---|
inputLevels | low, high | With this option you can remap the tone of the image to make shadows darker, highlights lighter and increase contrast. Possible values for "low" and "high" are integers between 0 and 255, where "high" must be higher than "low". The value "low" will then be remapped to a tone of 0, the value "high" will be remapped to 255. Example: This example will cause the tonal range of the resulting image to begin at 50 of the original (which is set as 0 for the new image) and to end at 190 of the original (which is set as 255 for the new image). 20 = ADJUST 20.value = inputLevels = 50, 190 | |
outputLevels | low, high | With this option you can remap the tone of the image to make shadows lighter, highlights darker and decrease contrast. Possible values for "low" and "high" are integers between 0 and 255, where "high" must be higher than "low". The beginning of the tonal range, which is 0, will then be remapped to the value "low", the end, which is 255, will be remapped to the value "high". Example: This example will cause the resulting image to have a tonal range, where there is no pixel with a tone below 50 and no pixel with a tone above 190 in the image. 20 = ADJUST 20.value = outputLevels = 50, 190 | |
autoLevels | - | Sets the levels automatically. |
[tsref:->GIFBUILDER.(GBObj).ADJUST]
This is used by the GifBuilderObj "TEXT" to create an image-map for the gif-file. This is especially used with the IMGMENU menuobject.
Property: | Data type: | Description: | Default: |
|---|---|---|---|
url | url | url to link | For IMGMENU menu objects provided automatically |
target | target | target for link | For IMGMENU menu objects provided automatically |
noBlur | Boolean | Normally graphical links are "blurred" if the browser is MSIE. This removes the ugly box around a link. If this property is set, the link is NOT blurred with "onFocus". | For IMGMENU menu objects provided automatically |
explode | x,y | This "explodes" or "implodes" the image-map. Useful to let the hot area cover a little more than just the letters of the text. | |
altText | string | Value of the alt-attribute. (Used from TEXT Gifbuilding objects, this has stdWrap properties. Otherwise not) | |
titleText | string | Value of the title attribute. (Used from TEXT Gifbuilding objects, this has stdWrap properties. Otherwise not) |
[tsref:->IMGMAP]
