RTFM: Build a fully dynamic banner with the TSref (Part 4 of 4)

The dynamic image

The final step in making our banner fully dynamic is to have TYPO3 generate the image itself. In TYPO3, this is done using the IMAGE cObject that we used to make the images in the previous parts of this tutorial.

As we saw in that tutorial, the principal property of the IMAGE cObject is the "file" property; we also learned that the file property's data type is "imgResource."

And as we found in the TSref's Datatype reference properties with the imgResource datatype can accept a GIFBUILDER object as input.

To top

The GIFBUILDER object

The GIFBUILDER object is TYPO3's main tool for producing dynamic images. In spite of its name, GIFBUILDER can produce .gif, .jpg and .png images. Since GIFBUILDER is a very complex object, we should again start by planning the desired output—only this time, we should identify the components of the image itself, rather than the HTML markup we expect:

• the image text
• the image's white background
• the grey border around the image

In addition, just to reinforce how the gettext datatype works, we'll make the image text dynamic and base it on the title of this site.

GIFBUILDER basics

Since we know in advance that only the contents of the file property of the IMAGE cObject will change for this version of the banner, we can simply re-use the rest of the code from an earlier example with just a few changes to the object's file property (lines 4-7):

GIFBUILDER is slightly different from other TS objects in that it has set of properties that belong to it directly—generally properties that pertain to the entire generated image—and an entire set of sub-objects that can only be used by GIFBUILDER objects. These sub-objects are used to create text, simple geometric objects and to apply image-processing effects to the whole. We'll start by creating the basic image and the border.

GIFBUILDER properties

If we look over GIFBUILDER's properties on the TSref's Object Names in This Section page, it's not immediately obvious where to start. But given that we're going to build an image completely from scratch, it might be best to look for the properties we'd start with if we were using a conventional image-editing application to do the same job—in other words, we should start by looking for a way to set the image's size and background colour.

If we now return to the list of GIFBUILDER properties in the TSref, we find two properties that may fit our requirements:

• backColor
• XY

"backColor" seems straightforward enough—its datatype is given as "GraphicColor." Consulting the datatype reference again reveals that GIFBUILDER's "backColor" property can accept a 6-digit hexadecimal number of exactly the same sort as HTML and CSS documents. To begin with, we'll choose "#cccccc" as the value for the backColor property.

"XY" is less clear; the description ("Size of the gif-file") makes it quite clear that the property is what we're looking for, but the listed datatype—"x,y +calc"—is not listed in the datatype reference. Fortunately, the TSref's entry for XY shows the default value to be XY. So to begin with, we'll assume that the XY property expects to receive an x-dimension followed by a comma and a y-dimension where both dimensions are in pixels. Given this, we'll set the initial value of XY to 468,60—the size of our banner image.

Now that we have made preliminary decisions about what values to provide the GIFBUILDER object with, let's add them to our working code and check the output:

TS output

It works! Of course the resulting image is not particularly interesting—it's simply a grey rectangle—but it is precisely the output we were expecting at this stage. And now that we have successfully created the image, let's move on to the next step—the use of one of GIFBUILDER's special objects.

A border with 'BOX'

So far, we have managed only to create a basic image in a solid colour. Before we move on to the final and most interesting step where we use GIFBUILDER to create the image's text, we'll finish creating the 'frame' of the image.

Since GIFBUILDER's capabilities for creating raw geometric images are fairly modest, it's necessary to be a bit creative when building new images. Reviewing the list of GIFBUILDER's objects and properties, we will not find an 'outline' or 'border' object. We do, however, find an object named "BOX."

The TSref offers no description for what BOX actually does, but it seems reasonable to assume that it makes rectangles. If so, we should be able to use it to place a white rectangle 466 x 58 pixels precisely in the center of the existing grey rectangle—the effect will be of a white rectangle surrounded by a one pixel grey border.

Looking closely at the TSref, we learn that BOX has only three properties: "dimensions," "color" and "VHalign." Since we know for certain that our box will need a colour and dimensions, we'll start with those properties first.

The "Color" property has a datatype we've seen before—GraphicColor—so we can uncomplicatedly assign it the colour that we want to use for the main part of the graphic: #ffffff.

The "dimensions" property has a datatype of "x,y,w,h +calc". It turns out that +calc  isn't present in the datatype reference (though it is present in the Objects and Properties section of the TSref), but "x,y,w,h" is. The entry in the datatype is almost identical to the property's description under BOX. Apparently, this object expects four comma-separated values, where the first two indicate the offset of the top left corner of the current object from the top left corner of the parent object and where the second two values are the size of the current object.

The current object needs to be 468-2 pixels by 60-2pixels, and it needs to be offset by one pixel in the x direction and one pixel in the y direction. This gives us a value for the dimensions property of "1,1,466,58". We'll now add those values into our working code sample:

Our new code yields the following result:

TS output

In other words, we've now achieved two out of three of our chief aims: we've created an image with a white background, and we've surrounded it with a one-pixel grey border. Now, we can move on to the most involved part of the banner—adding the text with GIFBUILDER's TEXT object.

Text with GIFBUILDER's TEXT object

Whle the GIFBUILDER object doesn't include a specific object for creating borders, it does seem to include one for creating graphical text. Unsurprisingly, this object is called TEXT. With this object, we should be able to achieve the last and most interesting part of our banner project: the text on the image. But before we proceed, there is one thing to recognize that may not be immediately apparent–even though it can be determined by reading the TSref closely…

GIFBUILDER's TEXT object is not the TEXT cObject!

The single most important thing to understand about GIFBUILDER's TEXT object is that it is not the same as the TEXT cObject. A common mistake with the TEXT object in GIFBUILDER is to duplicate the syntax of a working TEXT cObject—which will not work.

The difference is in how GIFBUILDER's TEXT object and the TEXT cObject are supplied with content. The Text cObject, for example, is supplied with content either a) through its "value" property, or b) via .stdWrap properties and functions.

The GIFBUILDER TEXT object, on the other hand, is supplied with content via its 'text' property. In fact, the way the GIFBUILDER TEXT object works is more similar to the way the HTML cObject works—in that cObject, all value is supplied via the "value" property.

With the GIFBUILDER TEXT object, we can determine this using the TSref (though only by the process of elimination) by reading through the TEXT object's property list; none of the objects' property names (except .text) in any way suggests text-rendering. Moreover only the text property specifically mentions the output text string.

In theory, we ought to be able to determine this by consulting the various properties' datatypes, but in the TSref, the TEXT object's text property's datatype is given only as "stdWrap." This is correct as far as it goes, but is actually incomplete since the TEXT object's text property also accepts string input. Presumably, the TSref ought to give the text property's datatype as "string / stdWrap" or "HTML / stdWrap" as it does for the HTML object's nearly identical "value" property.

To further illustrate the subtle differences between GIFBUILDER TEXT, TEXT and HTML, the following code samples show how we could retrieve the title of a page in the website using the TEXT cObject, the HTML cObject, and the GIFBUILDER TEXT object:

Page title with TEXT cObject

Page title with HTML cObject

Page title with GIFBULDER TEXT object

Add TEXT to GIFBUILDER

The text object is involved enough that we should here repeat our strategy of listing the properties of the output we need to achieve. For our banner we need to text to have the following characteristics:

• font: Share Monospace (the official TYPO3 font) in black, about 30px high
• position: centered horizontally and vertically in the banner
• text: the name of this site: www.typo3apprentice.com

Since we've already seen TS samples for retrieving the page title, let's start with the last item.

1. Retrieve the site title

In our content-retrieving examples above, we used the .stdWrap property ".data"—which has the datatype "getText"—to retrieve the title of the current page using the "page:title". This method, while very useful, is not appropriate in this instance since it will always retrieve the title of the current page.

But if we return to our previous examples, we'll see that we've already used at least one property that could be used to retrieve information from a page according to the page's level in the page tree: "leveluid". If we now revisit the getText section of the datatype reference, we'll find that there is also a property called "leveltitle" which returns the title of the page of a given level. Since the root page is usually at level zero, we should be able to use "leveltitle:0" in our TS.

In this case, since the root page of the website is currently called "TYPO3apprentice" but the banner is meant to read "www.typo3apprentice.com," we'll need to see we can manipulate the title using .stdWrap functions.

First of all we'll need to change the case of the page title to lower case—and for this kind of job, we should always consult the stdWrap section of the TSref. In the stdWrap section, we find that there is a a property called "case" that exists specifically for converting the case of text in TS objects.

Secondly, we need to add "www." to the beginnig of the page title and ".com" to the end. This is a perfect job for the property that stdWrap is named after: "wrap".

Between .data, .case and .wrap, we should have everything we need to create the graphic text, but there is one important factor that we should always consider when using multiple stdWrap properties: "stdWrap properties are executed in the order they appear."

This means that any time we use multiple .stdWrap properties we have to ensure that they're processed in an order that makes sense for the requirements of the current TS object. In this case, we retrieve the information with .data, change the case with .case, and finally wrap the object with .wrap. In the .stdWrap table, we find that .data is processed first, followed by .case and .wrap, so we should have no trouble. At this point, our TS code looks like this:

2. Style and position the text

At this point, we're completely finished the basic banner except for the styling of the text—even though if you were to view the output of the code sample above, there would be no text visible.

This is because GIFBUILDER's TEXT object includes properties used for correctly positioning the text in the overall graphic, but we haven't used them at this point, so our text is not visible. These properties, and in fact all the remaining properties of the TEXT object are quite straightforward. As there are only four of them that we'll actually need to use, we will simply list their names, the values we give them, and what they actually do:

• align: this property is used to position the text horizontally with respect to the boundaries of the GIFBUILDER object as a whole. Datatype: align
• offset: this property is used to position the TEXT object within the GIFBUILDER object. When used in conjunction with the align property (see above), the x-coordinate value can often be set to zero. Datatype: x,y +calc
• fontSize: the font size in pixels; note that the results of this property can be confusing depending on the value of the configuration variable $TYPO3_CONF_VARS[GFX][TTFdpi] in localconf.php. Datatype: posint
  
• fontFile: this is the path to the font file (usually .ttf) used to render the text in the gifbuilder object. Datatype: resource

In the following code sample, we set the following values:

• align = center
• offset = 0,39
• fontSize = 32
• fontFile = fileadmin/templates/typo3apprentice.com/fonts/Share-TechMono.ttf

The resulting GIFBUILDER image is shown below:

Related news and blog posts

2007 Jan 01RTFM: Link an image with the TSref (Part 3 of 4)

2007 Jan 01RTFM: Create an image using the TSref (Part 2 of 4)

2007 Jan 01RTFM: How to read the TSref (part 1 of 4)

2007 Jan 01cObject: Typoscript Content Objects