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

How do we link the image?

The properties table of the IMAGE cObject doesn't list anything that will obviously enable us to link the image we've created. We can use the object's 'wrap' property to encapsulate the img element in a link:

TS output

This solution obviously works, but it's far from ideal; if we rely on it, the following problems are possible:

1. if the root page of the site ever changes, our banner link will break
2. if the site uses simulateStaticDocuments or RealURL (in other words any time the form of the link is not 'index.php?id=xx'), the link will be in the wrong format

Problem (1) is not a serious problem for the current example, but when we need to link to a page inside the site instead of to the root page, it becomes a serious concern.

We also can't avoid problem (2) by changing the format of the link to match the current site (e.g. by changing the url to 'home/'), because this creates the potential for the same problem in reverse. That is, if the path to the page ever changes or if the form of the link changes then, again, the links in our banners will break.

Fortunately both of these problems can be resolved by digging a little deeper into the stdWrap property of the IMAGE cObject. Furthermore, the same principles apply directly to other important cObjects such as HTML, TEXT and COA.

Use 'typolink' to create links

In what should by now be a familiar pattern, the 'stdWrap' property of IMAGE cObjects is 'stdWrap', and as we've already seen, properties with the 'stdWrap' datatype are passed to the stdWrap function.

One of the most useful properties of stdWrap is 'typolink'. If we refer to the stdWrap function's page in the TSref, we see that typolink 'Wraps the content with a link-tag,' and that its datatype is 'typolink'. As with stdWrap itself, 'typolink' is not listed in the datatype reference, but there is a section of the TSref devoted to the typolink function.

If we review the properties of the typolink function carefully, we again will not find a property whose name corresponds to the HTML attribute we need to populate (i.e. the href attribute). However, we will find a property named 'parameter'—again with 'string/stdWrap' as its datatype—whose description says "This is the data, that ->typolink uses to create the link."

If we read further in the description, we find that parameter accepts an integer corresponding to the id of the page to be linked to. This means we can alter our Typoscript to make it somewhat more dynamic:

TS output

At first glance, the output of our Typoscript looks wrong—the href attribute of the link is empty! However, closer examination shows that something else is going on. This website uses the RealURL extension to simulate a directory structure in the url. The RealURL extension requires that the page contain a base element containing the base url for all local links found on the site. In html and xhtml, the href attribute of the base element is interpreted as the 'base' or root of all relative links. This means that an empty href attribute on a relative link is interpreted as a link to the site root, and that the typolink function has, in fact, output the correct code, given the configuration of this TYPO3 installation.

But even though it works, this is not really a sufficiently dynamic solution for our needs; if the page id changes for any reason (in other words, if we change is the root page), then our links will break. What we need instead is a way of retrieving the id of the root page dynamically. We can see on the typolink function page in the TSref that typolink's 'parameter' property has a datatype of 'string/stdWrap'. Again, this means that we can use any one of stdWrap's properties to retrieve the root page's id.

Unfortunately, the TSref provides us with no way of searching functions or properties according to what they do. In this instance, the only way forward is to have studied the TSref in some detail, so we'll need a hint:

It turns out that one of the single most useful properties of the stdWrap function is the 'data' property, a property whose datatype is 'getText' but which has no description in the TSref. However, when we consult the Datatype Reference for 'getText', we find a virtual treasure trove of information and interesting tools.

If we browse through the rather confusing list of properties of the getText datatype, we almost immediately find an example of a property named 'leveluid'. The description accompanying the example says that it shows how to "get the id of the root-page of the website."

As we've already seen, the .typolink function can use the numerical id—the uid—of a page in order to link to that page. And the uid of the root page of the site is precisely what we needed—it turns out that this is a TS property that exactly matches our requirement!

TS output

Related news and blog posts

2007 Jan 01RTFM: Build a fully dynamic banner with the TSref (Part 4 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

Links:

www.bedlamhotel.com