TYPO3 Templates

Create and modify templates with TypoScript and TemplaVoila

• Build dynamic and powerful TYPO3 templates using TypoScript, TemplaVoila, and other core technologies.
• Customize dynamic menus, logos, and headers using tricks you won’t find in the official documentation.
• Build content elements and template extensions to overhaul and improve TYPO3’s default back-end editing experience.
• Follow along with the step-by-step instructions to build a site from scratch using all the lessons in the book in a practical example.

Our graphical menu, GMENU, has the ability to use a TYPO3 class, GIFBUILDER, to create images on the fly. We are going to look at GIFBUILDER in depth in just a moment, but the basic idea is that GIFBUILDER can help us build complex graphics for our menus dynamically so that we can use fonts that are not be supported by all browsers, build button-like graphics, and use drop-shadows and embossing for effect. This means that we don’t need to update Photoshop every time that we want to change the menu titles or replace the font, and we also don’t have to learn or use Flash or JavaScript just to create flexible menu titles.

We gain a lot of freedom and power with GMENU, but it does have some disadvantages compared to TMENU. Depending on our needs, we will be generating an image for every state (normal, rollover, active, and so on), for each menu item anytime we make a change. The nice thing is that TYPO3 will cache our images, so they are only generated after we make a change and reset the cache. Overall, we will use the server a little more heavily anytime we reset the cache, and our users will need to download images for each menu item. The last disadvantage is just that it is more complex than TMENU. If our frontend developers or designers have already provided us with some awesome CSS/JavaScript or Photoshop images, then we may only need a text-based menu. In return for those possible disadvantages, we will get freedom and cross-browser compatibility, so let’s see what we can do before we make any decisions.

Introducing GIFBUILDER

GIFBUILDER is a universal object in TypoScript that uses some basic TypoScript code to generate images using the ImageMagick (or GraphicsMagick) library in PHP. Generating images with ImageMagick is normally very complex, and we would have to learn a fair amount of PHP to make anything. Using GIFBUILDER, makes it relatively easy to make these same dynamic images without learning PHP or opening Photoshop. GIFBUILDER can actually be used for any images that we would want to create in TypoScript, but we are going to be using it specifically for GMENU in this article to turn our text fields into typographic images complete with layers and effects.

We are going to learn about three main objects in GIFBUILDER that will help us create our menu items:

• Boxes: We can layer simple boxes to make borders or button effects.
• Images: We can use uploaded or external image files as backgrounds or just display them as menu items.
• Text: Most importantly, we can use text objects to show our page titles in non-web fonts with drop-shadow or emboss effects.

A complete list of the properties available to GIFBUILDER is beyond the scope of this article, and not really necessary to build most menus. If you have any problems with GIFBUILDER, you may need to check your ImageMagic configuration in the TYPO3 Install Tool.

The BOX object

The BOX object is one of the key TypoScript objects in GIFBUILDER. The BOX object is, like it sounds, just a simple graphical box defined by its size and color. By itself, it’s not that helpful, but we can add boxes as layers to generate borders and backgrounds that will be flattened into our final generated images. We are only going to use two properties for our boxes:

• BOX.dimensions defines the dimensions of the box in the format x, y, w, h where x, y is the offset for the top right-corner and w, h is the width and height of the box.
• BOX.color defines the color of the inside of the box.

Here is an example of a gray box, 400 pixels wide, 20 pixels tall, and offset 3 pixels down and to the right:

lib.subMenu.1.NO {
5 = BOX
5.color = #aaaaaa
5.dimensions = 3,3,400,20
}

The IMAGE object

The next object we can use, IMAGE, will bring in an image for normal display or basic tiling and masking. The IMAGE object can be used for complex displays, but we are only looking at menu applications and will just look at a few options:

The TEXT object

Finally, we’re going to look at the options for a TEXT object in GIFBUILDER. TEXT objects are used to display any text we want in GIFBUILDER, but will be mainly using them to show the title of each page as a menu item. This list of properties is much more exhaustive because this would obviously be one of the most important objects to customize when we’re creating a menu using graphical text:

GIFBUILDER layers

We work with GIFBUILDER by creating new objects for the GIFBUILDER, designing them with properties, and layering them by number values. Each layer is stacked in ascending order (larger numbers on top), and then TYPO3 generates a final image by flattening all of the layers into one image. It sounds a little complex, but look at this example:

lib.subMenu.1.NO {
5 = BOX
5.color = #aaaaaa
5.dimensions = 3,3,400,20
10 = TEXT
10.text.field = title
10.fontSize = 12
}

In the example that we just saw, lib.subMenu.1.NO is our GIFBUILDER object. Although the numbers used to identify objects (5 and 10 in the example) are sometimes arbitrary in TYPO3, they are very important for GIFBUILDER because they define the ordering in layers. GIFBUILDER stacks it’s subobjects from lowest number to highest. So, in the example that we just saw, TYPO3 is generating an image in a logical sequence:

1. A gray box is defined.
2. The dimensions of the gray box are defined to make it 400 pixels wide and 20 pixels.
3. A text object is created on top of the gray box to show the title field of the page from the menu item.
4. The size of the text for the title is set to 12 pixels.
5. TYPO3 generates a flattened image of our menu item title in a gray box.

Using this system, we can stack very simple objects on top of each other to draw basic buttons.

GIFBUILDER properties

The GIFBUILDER object will apply itself to all items in a GMENU menu. For the basic GIFBUILDER object, we are only going to look at two properties:

• XY defines the size of the image (width and height)
• backColor defines the background color for the entire image

The interesting trick for XY (and some of the other dimension properties) is that it can be based on hard-coded numbers and TypoScript constants, or it can be a calculation based on the size of another item. In the following code, the size of the GIFBUILDER object is tied directly to the size of the TEXT object declared below it:

10 = TEXT
10.text.field = title
XY = [10.w]+10,[10.h]+10

The references [10.w] and [10.h] read the current width and height of the object associated with 10. Then, we add 10 pixels onto each one to give ourselves a little bit of room for spacing. We’ll use this technique in GMENU to make sure that our boxes and graphic objects always line up with our titles.

GMENU properties

The first thing that you’ll probably notice going from TMENU to GMENU is that we are about to multiply the number of properties at our disposal dramatically. We’ve already covered the common menu properties. We’re just going to cover the most basic or necessary properties in the following tables to get an idea of what we can do. If it looks intimidating, don’t worry. Most of the properties are created logically and build upon our earlier knowledge. Most importantly, there’s no requirement to learn all of GIFBUILDER before we start playing around.

The menu object itself has just a few key properties that we need to look at:

Creating our first graphic menu

The first change we can accomplish is updating our main menu with a custom font and some rollover functionality. We can do that with minimum fuss, and it’ll update our whole look nicely. I chose a freeware font from Larabie Fonts (http://www.larabiefonts.com) called Deftone because it’ll show off GIFBUILDER, and my boss loves it. You can use any TrueType font file you would like, though. Some fonts seem to work better with ImageMagick then others, so you may need to experiment. In any case, let’s start updating our menu:

1. We need to change lib.mainMenu.1 = TMENU to lib.mainMenu.1 = GMENU to use the GMENU objects.
2. We want a consistent height for our entire menu, so we’ll enable useLargestItemY in our template:

   lib.mainMenu.1.useLargestItemY = 1

3. Let’s update the normal menu state first. We won’t be using the div tags around our menu items, so want to add a class to our images:

   lib.mainMenu.1.NO.ATagParams = class=”menu-link”

4. We can set the background color and dimensions of our menu items. We are going to use 10 for our text object, so we can go ahead and use that as part of the size calculation to make our items exactly the same width and 5 pixels taller than the text:

   lib.mainMenu.1.NO {
   backColor = #ffffff
   XY = [10.w],[10.h]+5
   }

5. Now we can create the TEXT object. This is our main menu, so we’re just going to use the title as our text content. We’re also going to use the Deftone font at a size of 36 in a classic black:

   lib.mainMenu.1.NO {
   10 = TEXT
   10.text.field = title
   10.fontFile = fileadmin/templates/deftone.ttf
   10.fontSize = 36
   10.fontColor = #000000
   10.align = left
   }

6. The main menu is already looking better, but we can add some flair by tilting the text up with the angle property. Because of the angle changing the dimensions, we’ll push the text down a little more by adding a 50 pixel offset to the height:

   lib.mainMenu.1.NO {
   10.offset = 0,50
   10.angle = 3
   }

After all of our modifications, this is what our menu should look like: