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

RTFM?!

RTFM: "Read the f——— manual!" Participate in an open source software project long enough and you will eventually hear—or be told—"RTM," or worse, "RTFM!" It seems like good advice, but the situation is not always so clear-cut. The Typoscript Reference (the 'TSref'), for example is not exactly easy to understand.

This is partly due to the fact that the TSref is a reference, not a manual, and partly because it assumes at least a basic knowledge of Typoscript. On one hand, this allows the document to be succinct enough that information can be easily found within it, but on the other hand it can be problematic (i.e. since the TSref is the authoritative source for information about Typoscript, it is very important that newcomers to TYPO3 be able to read and understand it).

This series of articles discusses some of the basic characteristics of Typoscript, explains how these are used to organize information in the TSref, and illustrates their use in the construction of a simple custom banner image using Typoscript.

To top

Typoscript syntax is neither arbitrary nor regular

Newcomers to Typoscript do not always understand that there are a finite number of fixed TS properties and that properties cannot be arbitrarily invented and assigned to objects.

Typoscript consists of little else but the objects defined in the TSref and the functions and properties belonging to those objects. For example, the Typoscript cObjects 'HTML' and 'TEXT' are virtually identical except that the 'stdWrap' properties (such as 'wrap') belong to the object itself, and not to the object's 'value' property (as shown on line 4 of Example 2). We will explain more about what this means later; for the present, note that Example 1 below is correct, but Example 2 is not:

Example 1 (correct)

Example 2 (incorrect)

The above examples also illustrate the point that, in spite of the easily understood and javascript-like 'dot syntax,' Typoscript syntax is not regular. For example:

• not every object can make use of the same properties,
• not every object can make use of the same functions,
• similar or identical properties of different objects may have different names,
• objects, properties and data types sometimes share virtually (or actually) identical names,
• objects are consistently named in UPPERCASE but may or may not use underscores in multiple-word identifiers,
• multiple-word identifiers in the names of functions and properties alternately use camelCase, underscores or some combination of both.

These considerations make a memory aid such as the TSref critical for the effective use of Typoscript. They also make it vitally important that the TYPO3 developer understand how Typoscript is 'put together.'

To top

Typoscript has objects, functions, properties and data types

As referred to in the previous section, Typoscript has objects, functions, properties and data types, and since the TSref is largely organized according to these categories, it's important to know what each one is and how they interact with one another.

Objects, properties and data types

Typoscript objects are the building blocks of TYPO3 websites. The so-called 'Toplevel objects' are used for setting up and configuring sites and pages, while the 'Content Objects' or cObjects are used to create TYPO3 websites' content. In very general terms, the Toplevel objects are used for pages, but cObjects are used to create small parcels of HTML such as, for  instance, menus, titles, login forms etc.

Each type of object has its own set of properties that can be used variously to provide content, or parameters (such as, e.g. file paths) to the object. Each property of an object has a data type that determines what kind of content it can accept and what function (if any) to pass the input value to.

Simple, static html content, for example, can be created using the HTML cObject by loading the 'value' property with content (TS code and output shown below):

HTML Header 1

HTML Header 2

Even more interestingly, we can override the HTML cObject's value property altogether by using another stdWrap property to retrieve information dynamically. Here, we retrieve the current page's title:

HTML Header 3

As interesting as this capability is, however, it is worth reiterating here that typoscript syntax is neither arbitrary nor regular. This means that both the syntax and particular properties used must be known and understood—this is where the TSref comes in.

Functions

Besides objects, properties and datatypes, there are also various functions available in Typoscript. The most important of these by far is the 'stdWrap' function. As its name suggests, this function is often used to 'wrap' content—just as we did in the HTML Header 2 example above. In that example, we used the 'wrap' property of the stdWrap function to encapsulate the word 'Test' in opening and closing h1 tags.

But besides simple wrapping, stdWrap can also be used for many other purposes as we saw in the HTML Header 3 example, where we used the 'data' property of the stdWrap function to dynamically supply content to the HTML cObject.

In addition to wrapping and supplying dynamic content, stdWrap can also:

• retrieve data about the current page or content record
• perform simple calculations
• convert case
• render dates from timestamps using php's date and strftime functions
• process HTML
• call php custom php functions for tasks beyond Typoscript's native capabilities
• insert cObjects into other cObjects
• create links (in concert with the 'typolink' function)
• render content conditionally (in concert with the 'if' function)

To top

The TSref has objects, functions, properties and data types too

To a large extent, the TSref is organized by objects, properties, functions and datatypes, but the question is 'how can we use the TSref to put all the parts in the right place?' In fact, the process is quite straightforward.

The fact that the TSref's basic organizational principals are the same as the components of Typoscript enables developers working with Typoscript to follow a consistent workflow something like the following:

1. Plan the intended output,
2. Choose an appropriate cObject for the purpose,
3. Cross-reference the datatypes of the cObject properties to be used with the Data Type Reference in the TSref in order to determine which properties to use and how to used them.

To illustrate this workflow, the next part of this article shows how to construct an image banner something like the one used in the header of this site.

Continue to Part 2 of RTFM: how to Read the TSref »

To top

Related news and blog posts

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

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 01cObject: Typoscript Content Objects