Build a banner using the TSref

1. Design the output

It's difficult to overstate the importance of this part of the process. For all its many components and capabilities, TYPO3 does little else at the output end than publish HTML pages. A Typoscript project begun without a clear idea of the expected HTML output can be extremely difficult to debug if something goes wrong. On the other hand, if the developer has followed through on the the output design, the expected and actual outputs can easily be compared and used for debugging.

Our banner project is meant to be a simple 468 x 60 image with appropriate alt and title values, linked to www.typo3 apprentice.com. Since we would like to be able to change the text on the banner we'd like to build it entirely in TYPO3 rather than uploading a static image to the site. We'd like the result to look something like this:

In summary, we would like to achieve the following:

1. An img element with src, width, height, and alt attributes
2. A link with href and title attributes containing the img element

To top

2. Choose an appropriate cObject

Referring to the list of cObjects in the TSref, we can see that there are three cObjects that seem to involve images:

• IMAGE,
• IMG_RESOURCE, and
• IMGTEXT

Our first task is to determine which one is appropriate to the task at hand; there is no explicit description for the IMAGE cObject, but we can quickly rule out IMG_RESOURCE (which returns only the url to the image), and IMGTEXT (which is used for aligning images and text). As it turns out, this is the correct choice because the IMAGE cObject actually returns a complete HTML image element, including the src, width, height and alt attributes.

We can now proceed to the tricky part of the process—picking out the requisite properties from the TSref and building the IMAGE cObject with them.

To top

3. Consult the TSref

Our basic familiarity with Typoscript allows us to start the TS object easily enough, but we will have to consult our reference manual before we go any further:

The 'src,' 'width,' and 'height' attributes

Consulting the IMAGE cObject's page in the TSref, there is no property whose name corresponds directly to the 'src' attribute of an image element, but there is a property named 'file' with the data type 'imgResource'. We can check the Datatype Reference in the TSref to see if this property is appropriate for what we need to do.

According to the Datatype Reference, the value passed to a property with the imgResource datatype may be "A 'resource'"—which is "A reference to a file"—plus "imgResource properties" or a "GIFBUILDER-object."

As this suggests, we can pass a literal file path directly to the file property of IMAGE and display an image element that way. We'll test it by loading the IMAGE object's file property with the path to our sample image:

The above Typoscript produces the following result (shown as code and as rendered by your browser):

The very first thing we should notice about the output of the TS object is that TYPO3 has rather conveniently calculated the width and height of our image and created the appropriate attributes in the img element. We can cross width and height off of our list. We can also see that TYPO3 has included empty alt and title attributes in the output, but we'll return to these in a later section.

Having achieved our first success with the TSref, we should recall that the Datatype Reference also mentions 'imgResource' properties as permissible values for the the imgResource datatype. What does that mean? It turns out that 'imgResource' is also a Typoscript function. This is a common pattern in Typoscript; as mentioned in the introduction to the Objects and Properties section of the TSref, datatypes are often "parsed through" the function of the same name "...with the properties of the value as parameters."

In other words, when a cOject has a property whose datatype has the same name as a TS function, that property can make use of all the properties of the function. In the case of our current example, that means that the file property of the IMAGE cObject can make use of all of the properties of the imgResource function. We could, for example, vary the size of our output image using the width (or height) property of the imgResource function (Typoscript, code output and actual image shown below):

As we can see, the image has been modified to suit the new dimension provided.

But our initial specification called for a dynamic image, so we can't simply feed a known file path to the IMAGE object's file property. If we review the imgResource entry in the Datatype Reference, we can see that the value supplied to file can also be a GIFBUILDER object. GIFBUILDER is another cObject which can be used to create custom images, so it should be ideal for our purposes. But since it is quite complex, we will complete all the other parts of our banner image—the link and the alt and title attributes of the img element—before returning to create a custom image with GIFBUILDER.

To top

The 'alt' and 'title' attributes

For the 'alt' and 'title' attributes, we return to the TSref's IMAGE page. There, we find properties with the names 'altText' and 'titleText'. As we saw earlier, TYPO3 includes both attributes in img elements even though only the alt attribute is required by the relevant standards. Nonetheless, it is possible to specify an empty title attribute when necessary.

If we investigate the data type of the IMAGE cObject's altText and titleText properties, we again find something interesting; the datatype for both objects is listed as 'string/stdWrap.' If we then return again to the Datatype Reference we find, unsurprisingly, that the 'string' datatype expects a simple string value. However, we do not find 'stdWrap' listed as a datatype. This appears to be an omission, but the case of stdWrap is the same as 'imgResource'; the value passed to a property with the stdWrap datatype is passed to the stdWrap function. The stdWrap function could be the subject of an entire book, but as mentioned previously, stdWrap is fantastically useful. We could, for example, use stdWrap to return many sorts of dynamic information or to return the value of a custom php function.

In this case, however, we will simply use static values:

The resulting HTML code looks like this:

To top

Next: Link the banner image with TS