This content was uploaded by our users and we assume good faith they have the permission to share this book. If you own the copyright to this book and it is wrongfully on our website, we offer a simple DMCA procedure to remove your content from our site. Start by pressing the button below!
In this book, Daniel Koch provides you with all the information needed to master TypoScript in a clear and practical way with many examples to develop your skills. Written in a clear, easy-to-read style, the book provides step-by-step instructions on using TypoScript for TYPO3 website development, template and extension development, and back-end and front-end administration.
What you will learn from this book
• • • • • • • • •
Design and develop templates in TYPO3—design templates, pure TypoScript templates, and TemplaVoilà Develop extensions in TYPO3; build extensions using Kickstarter Understand the objects, properties, operators, and datatypes in TypoScript Understand the entire TYPO3 back end, including the Info/Modify tool, the Object browser, the Template Analyzer, and the TypoScript Properties display Work with design templates using markers, subparts, and HTML comments Understand how to present different views of content with different menu entry types Understand TYPO3 database structure and query it using SQL Use user groups to distribute the editing and management of content on your site Customize the back end with Page TSConfig and User TSConfig
This book is suitable for TYPO3 developers, administrators, and designers who want to develop fully featured TYPO3 websites using the power of TypoScript. A basic knowledge of TYPO3 is expected, and PHP and MySQL programming experience is useful, though not essential for using this book. $ 49.99 US £ 30.99 UK € 44.99 EU Prices do not include local sales tax or VAT where applicable
F r o m
T e c h n o l o g i e s
t o
S o l u t i o n s
Mastering TypoScript
TYPO3 Website, Template, and Extension Development Daniel Koch
Who this book is written for
Mastering TypoScript
TypoScript is a declarative configuration language that offers developers, administrators, and designers full control over the configuration of TYPO3 and its template engine. Only with a good command of TypoScript can you leverage the powerful capabilities of the TYPO3 engine to customize and control all aspects of your TYPO3 sites.
TYPO3 Website, Template, and Extension Development
Mastering TypoScript: TYPO3 Website, Template, and Extension Development
A complete guide to understanding and using TypoScript, TYPO3’s powerful configuration language
Packt Publishing Birmingham - Mumbai
www.packtpub.com
Daniel Koch
Mastering TypoScript: TYPO3 Website, Template, and Extension Development
A complete guide to understanding and using TypoScript, TYPO3's powerful configuration language
Credits Author Daniel Koch Development Editor Louay Fatoohi Translator Wolfgang Spegg Technical Editor Ashutosh Pande Editorial Manager Dipali Chittar
Project Manager Patricia Weir Indexer Bhushan Pangaonkar Proofreader Chris Smith Layouts and Illustrations Shantanu Zagade Cover Designer Shantanu Zagade
About the Author Daniel Koch is a freelancing author and developer. His main focus is on Open Source Web Applications and Content Management Systems.
Daniel lives in Hamburg, Germany. He has authored/coauthored eighteen books and frequently contributes to IT magazines. His website is http://www.medienwerke.de/. Thanks to Sarah for the last 11 years, which have been wonderful.
Table of Contents Preface Chapter 1: Introduction to TypoScript
1 7
Prerequisites Dummy Package Setting up an Example Page Structure Declarative Programming with TypoScript The Power of TypoScript What is TypoScript? Back-end Configuration with TypoScript TypoScript and PHP TypoScript Templates Summary
7 7 7 10 10 12 13 13 16 18
Chapter 2: Getting to Know TypoScript
19
Hello World! Creating a Template Syntax Objects and Properties Copying Objects and Properties Referencing Objects Classic Sources of Errors The Classification of Objects Constants Operators Value Assignment Value Assignment over Several Lines The Copy and Delete Operators Referencing Conditions
19 19 22 22 24 26 27 28 28 29 29 29 30 30 30
Table of Contents
Faster Writing Through {} Datatypes Simple Datatypes Objects as Datatypes Functions as Datatypes The Wrap Principle Comments Conditions The ELSE Condition Extended Options Defining Your Own Conditions Functions Working with TSref Datatypes Objects and Properties Conditions Functions Constants Setup cObjects GIFBuilder MENU Objects Media/Scripts Plug-Ins Standard Templates PHP Include Scripts Casestory Index.php Tips Summary
Title Sitetitle Description Resources Constants Setup Editing the Whole Template
45 45 46 46 46 46 46
Choosing an Editor Syntax Highlighting in UltraEdit The Info/Modify Tool Elements
43 44 44 45
The Object Browser
47 [ ii ]
Table of Contents
The Template Analyzer The TypoScript Properties Display The Admin Panel Categories
49 50 50 51
The Constant Editor Preparing Constants A Practical Demonstration: Defining Heading Colors through Constants Categories Subcategories Field Types Describing Categories TypoScript in HomeSite HTMLArea RTE Using Your Own CSS Styles Activating and Deactivating Buttons Setting the Permitted Tags Customizing the Color Field Making Additional Functions Available Customizing the Rich-Text Editor (RTE) Configuring the Toolbar Defining Your Own Classes Paragraph Formats Defining Colors User-Defined Menus Modifying the Background Color Managing the Output
Design Templates versus Templates Principles of Design Templates Markers Subparts HTML Comments and Subparts Double Headings Summary [ iii ]
51 52 52 52 52
76 76
79
79 79 80 80 81 82 84
Table of Contents
Chapter 5: Templates
The Concept of Templates Hello World! Hello World! Part II Inheriting Templates Template Elements Objects and Properties of Websites Defining Page Properties with TypoScript bodyTag stylesheet meta
85
85 85 86 87 88 91 91
91 92 92
Integrating Design Templates Activating the Design Template Activating Placeholders
92 92 94
The Auto Parser Template Installing the Parser
97 97
Activating Subparts Integrating a Stylesheet Activating Markers Locating Errors
95 95 96 96
Creating a Sample Application Editing the Settings
98 98
Standard Templates template temp.* styles records (example) content (default) frameset plugin Pure TypoScript Templates TemplaVoilà System Prerequisites Preparing TemplaVoilà Setting up the Data Structure Creating Content Conclusion Flexforms Summary
Drawing Boxes Graphical Text Anti-Aliasing with niceText Advanced Options Shadows Relief Showing the Page Title as a Graphic Importing Graphics from the Database Caching What is Cached in TYPO3 Emptying the Cache Summary
130 131 133 135 135 136 137 138 139 140 140 142
Positioning Levels
Chapter 7: Menus
Available Menu Types Hello Menu! Specifying Menu Properties Defining States Defining the Starting Point of a Menu Specifying Menu Types Defining the Entry Level Specifying the First Menu Entry Specifying the Number of Menu Entries Excluding Menu Items Text Menus Properties of Text Menus Defining Sub-Menus Using Stylesheets Spacing between the Menu Items OptionSplit: Adding Vertical Lines Menus and Tables Text Menus and JavaScript JavaScript Menus Calling Pages from the Menu Graphical Menus Creating Menu Items []
Integrating Sub-Menu Items Creating Lines Automatically Customizing the Menu Width Adding Background Graphics An Alternative to GMENU GMENU_FOLDOUT Layer Menus Formatting the Menu Text Menus in Layer Form ImageMaps Special Menus Next Page (Browse Menu) You are Here (Rootline Menu) Keywords Menu Updated Pages Directory Menus List Menu Summary
Hello Frames! Advantages and Disadvantages of Frames Creating Frames Rows Columns Nesting Frames Defining Frame Properties Frames without Borders An Elegant Solution for Using Frames Iframes Installing the Extension Defining the Properties of Iframe Summary Building Forms Mandatory Fields The Forms Wizard Designing Fields A Completed Form Masking out Pre-Initialized Values Displaying Form Elements in Columns [ vi ]
Setting up a Password-Protected Area Installing the System Folder Setting up User Groups Defining Access Restrictions Setting up the Login Form Refining the Login Form User Registration MailformPlus Standard Search Customizing the Search Customizing and Deleting the Selection Field Specifying the Target Window Defining Your Own Error Messages Formatting the Output Integrating the Extended Search Linking the Form Configuring the Search Improving the Display Selective Indexing
Problems with Multilingual Websites Searching on Every Page
228 229
Chapter 10: TypoScript and SQL
233
Chapter 11: Extensions
247
The Database Structure Reading Database Contents Dynamically Checking for Empty Fields Manipulating SQL Statements Arranging Content Selecting Specific Columns Formatting Elements in Specific Columns SQL Queries Constructing an Extension with Kickstarter Plugin Preview Creating a New Record Inserting SQL Queries Summary Building Extensions Extension Categories
The Extension Manager Installing Extensions Useful Extensions News Calendar Editor
248 251 253 253 258
Customizing the Output
258
Newsletter
259
Creating a Registration Form Unsubscribing from the Newsletter
262 263
Integrating a Chat Room Developing Your Own Extensions The Kickstarter Extension
263 266 266
Setting up an Extension Key The Kickstarter Component Integrating the Front-End Plugin
Extension Structure Functions of the Extension Manager TER Account Administering Extensions in TER Offering Documentation
Designing your own Extension Practical Extension Development Coding Guidelines File Naming Classes Functions Headers and Copyright Notice Line Formatting Source Code Documentation Variables and Constants
266 267 269
270 272 273
273 273
274 279 279
280 280 280 281 281 282 283
Database Abstraction
284
Security
287
The Wrapper Class Building Queries Query Execution Functions Database Abstraction in Real Life
284 285 285 286
Cross-Site Scripting Manipulating SQL Queries
Extending the References Extension Addressing Subparts Replacing Markers Summary
TypoScript and Multilingualism The Multiple-Tree Concept The One-Tree-Fits-All-Languages Concept Automatic Selection of Languages Menus and Multilingualism Publishing Multiple Versions Offering a PDF Version Installing HTMLDoc under Linux Making HTMLDoc Available for TYPO3
Offering a Print Version Deactivating "Page is being generated" TYPO3 and Search Engines Inserting Meta Tags Simulating Static Documents RealURL Protection from Email Spam Customizing the Page Header Summary
Chapter 14: Customizing the Back End with TSConfig Page TSConfig Configuring Back-End Modules Customizing Editing Forms with TCEFORM [ ix ]
306 307
308 310
311
311 311 312 316 316 317 317
317 318
320 321 322 323 324 325 327 327 329
331
331 332 334
Table of Contents
Configuring System Tables with TCEMAIN User TSConfig Setup admPanel options Summary
Appendix A: TypoScript Reference Functions Date and Time Functions date strftime
336 336 337 338 338 339
341
341 341
341 341
if
342
imageLinkWrap
343
parseFunc
346
select
347
directReturn equals isFalse isGreaterThan isLessThan isInList isPositive isTrue negate value
Preface Free, open-source, flexible, and scalable, TYPO3 is one of the most powerful PHP content management systems. It is well suited for creating intranets and extranets for the enterprise. While providing an easy-to-use web interface for non-technical authors and editors of content, its messaging and workflow system allow shared authoring and collaboration. TYPO3 provides flexible and powerful interfaces for both content editors and administrators, giving them full control of the core aspects the system. However for developers who need to customize the system, TYPO3 offers a powerful configuration language called TypoScript. Good knowledge of TypoScript is really a prerequisite for implementing complex applications with TYPO3 and gives developers full control over the configuration of TYPO3 and its template engine. TypoScript enables the complete output template to be created and manipulated, giving you full control over the layout of the site. TypoScript also allows you to integrate dynamic contents, JavaScript-based menus, Flash, Graphics, etc. with ease. You have maximum control over the design of the website and can control all options that would otherwise be addressed by HTML—simple text output, formatting, and much more. TypoScript also allows you to generate graphics at run time and display different content dynamically.
What This Book Covers
Chapter 1 provides an introduction to TYPO3 and TypoScript, its configuration language. Chapter 2 looks at the main features of TypoScript and also explains its basic principles. Objects, properties, operators, and datatypes in TypoScript are explained. The chapter winds up with a brief discussion on using TSref, the TypoScript online reference.
Preface
Chapter 3 covers certain development tools that make creating TypoScript code easier. UltraEdit is a simple text editor that allows syntax highlighting. The Constant Editor is used to edit standard templates by modifying constants. The HTMLArea Rich-Text Editor is now bundled with TypoScript (from Version 4). Since the Rich-Text Editor (RTE) was the standard tool for entering and editing content until version 3.8.x of TYPO3, it is still widely used, and hence included in this chapter. We cover defining custom classes, paragraph formats, menus, colors, and customizing the front-end output. Chapter 4 covers design templates, which control the basic layout of any TYPO3 website. They are different from normal templates. All design templates contain static and dynamic elements. All static elements are hard-coded in the HTML file. On the other hand, everything dynamic is marked with placeholders. These placeholders can then easily be replaced with dynamic content. There are two different types of placeholders—markers and subparts. We also discuss using HTML comments to maintain clarity in subparts. Chapter 5 covers using templates in TYPO3. We discuss the integration of design templates using TypoScript, defining page properties, menu generation, dynamic image generation, and integrating extensions. We also cover TemplaVoilà, a new extension that makes it possible for TypoScript developers to integrate templates using a graphical user interface. The biggest advantage of TemplaVoilà is that various layouts can be implemented without any PHP knowledge. Chapter 6 covers graphics processing in TypoScript. We discuss embedding and modifying the size of graphics. Next we look at creating graphics dynamically using the GIFBUILDER tool. Using this tool you can create and position levels, draw boxes, create text as graphics, and enable anti-aliasing. We then discuss the advanced graphical options available in TYPO3, such as creating shadows and embossing. The chapter winds up with a discussion on caching in TypoScript. Chapter 7 Menu creation is the one of the most powerful functions of TYPO3 and text, graphical, JavaScript, and layer-based menus can be created. The HMENU (hierarchical menu) object assembles menus in TypoScript, while sub-objects are responsible for rendering menu elements. This chapter takes a detailed look at creating and customizing different kinds of menus in TypoScript. Chapter 8 covers creating and configuring frames in TYPO3. We also cover creating Iframes using the IFRAME and IFRAME2 extensions. Chapter 9 covers building forms and searching in TYPO3. TYPO3 supports three basic types of forms—Mail forms, Search forms, and Login forms. The chapter discusses building forms with the Forms Wizard. Forms can contain mandatory fields that must be filled out by the user before submission. Custom form fields can be defined []
Preface
using CSS and HTML. We then discuss setting up a password-protected area (user authentication) using TypoScript. The Front End User Admin extension allows user registration and the MailformPlus extension can simultaneously send form data to a number of email addresses. Chapter 10 covers handling SQL queries in TYPO3.We take a quick look at the structure of the database used in TYPO3. We can dynamically read specific database fields from pages and output content from database tables. It is possible to select individual columns as well as format the elements of different columns differently. The second half of this chapter discusses creating and testing an extension with Kickstarter, populating some records, and finally outputting the records using SQL queries. Chapter 11 covers installing and updating extensions using the Extension Manager. We then introduce some of the most important applications in real-life scenarios such as News, Calendar, Newsletter, and Chat room extensions. The second half of the chapter focuses on developing, testing, documenting, and deploying your own extensions. Chapter 12 covers a very important concept—creating true barrier-free websites with TYPO3. This is very difficult, but TYPO3 offers various resources and extensions to help you achieve partial barrier freedom. The first part of this chapter covers extensions like CSS Styled Content, Accessible Content, CSS Styled Imagetext, Accessible XHTML Template, Acronym Manager, and Accessible Tables. The second half of the chapter discusses how to create barrier-free tables, forms, and menus in TYPO3. Chapter 13 covers some quick-and-easy methods of optimizing a TYPO3 project using TypoScript. We cover creating multilingual websites using two approaches—the multiple-tree concept and the one-tree-fits-all-languages concept. Users can manually set their languages via flags or this can be done automatically by reading browser settings. Next we cover creating PDF versions of your pages using HTMLDoc and the PDF generator extension. You can also allow users to view print-friendly pages by using special templates. We then explore TYPO3's advanced search-engine optimization functions, such as the integration of meta tags as well as replacing dynamic URLs with static URLs through Apache's mod_rewrite and the RealURL extension. The chapter winds up with a discussion on TYPO3's spam protection features such as e-mail address encryption. Chapter 14 discusses the back-end configuration of TYPO3 on two levels—the page level and the user level. We cover configuring individual pages of the website using Page TSConfig and site-wide configuration for users or groups of users using User TSConfig. []
Preface
Appendix A is a condensed version of the TypoScript Reference (TSref) and covers the important elements that you are likely to encounter in your day-to-day work.
Who This is Book For
This book is suitable for TYPO3 web developers, administrators, and designers who want to develop a fully featured TYPO3 website using the power of TypoScript. A basic knowledge of TYPO3 is expected, and PHP and MySQL programming experience is useful, though not essential for using this book.
Conventions
In this book, you will find a number of styles of text that distinguish between different kinds of information. Here are some examples of these styles, and an explanation of their meaning. There are three styles for code. Code words in text are shown as follows: "The primary element is ROOT and it is usually linked to the HTML element ." A block of code will be set as follows: temp.mainTemplate = TEMPLATE temp.mainTemplate { template = FILE template.file = fileadmin/_temp_/hello.htm
When we wish to draw your attention to a particular part of a code block, the relevant lines or items will be made bold: $template = $this->cObj->getSubpart($template, "###BODY_CONTENT###"); $template_reference = $this->cObj-> getSubpart($template, "###REFERENCE###");
New terms and important words are introduced in a bold-type font. Words that you see on the screen, in menus or dialog boxes for example, appear in our text like this: "The Table name field determines the name of the new table."
Warnings or important notes appear in a box like this.
[]
Preface
Tips and tricks appear like this.
Reader Feedback
Feedback from our readers is always welcome. Let us know what you think about this book, what you liked or may have disliked. Reader feedback is important for us to develop titles that you really get the most out of. To send us general feedback, simply drop an email to [email protected], making sure to mention the book title in the subject of your message. If there is a book that you need and would like to see us publish, please send us a note in the SUGGEST A TITLE form on www.packtpub.com or email [email protected]. If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, see our author guide on www.packtpub.com/authors.
Customer Support
Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase.
Downloading the Example Code for the Book
Visit http://www.packtpub.com/support, and select this book from the list of titles to download any example code or extra resources for this book. The files available for download will then be displayed. The downloadable files contain instructions on how to use them.
Errata
Although we have taken every care to ensure the accuracy of our contents, mistakes do happen. If you find a mistake in one of our books—maybe a mistake in text or code—we would be grateful if you would report this to us. By doing this you can save other readers from frustration, and help to improve subsequent versions of this book. If you find any errata, report them by visiting http://www.packtpub.com/ support, selecting your book, clicking on the Submit Errata link, and entering the details of your errata. Once your errata have been verified, your submission will be []
Preface
accepted and the errata added to the list of existing errata. The existing errata can be viewed by selecting your title from http://www.packtpub.com/support.
Questions
You can contact us at [email protected] if you are having a problem with some aspect of the book, and we will do our best to address it.
[]
Introduction to TypoScript TYPO3 is one of the most popular Content Management Systems in use today. This is hardly surprising, given that it can handle large web projects comfortably. However, if you want to have control not only over the content but also the design and functionality of your online presence, you require a good knowledge of TypoScript. This book introduces you to TypoScript and shows you how to create templates, generate menus and frames, and prepare your website for search engines.
Prerequisites
This book is targeted at experienced TYPO3 users and is meant to help you primarily during your day-to-day work. However, before you start with TypoScript, we must clarify the selection of packages and extensions that need to be installed to use this book. It does not matter in principle which TYPO3 package you have installed—TypoScript can be learned with any package. The following instructions are based on an installed dummy package.
Dummy Package
You of course want to use TypoScript for your own projects. As already mentioned, it does not matter in principle which TYPO3 package you have installed. However, for starting out with TypoScript the dummy package is recommended—you get an empty database and can experiment with TypoScript as much as you want. The installation of the dummy package is not shown here. You can download the dummy package from http://typo3.org/1274.0.html.
Setting up an Example Page Structure
You have bought this book to learn to use TypoScript in your own projects. Here TypoScript is explained using small independent examples, so that the book serves
Introduction to TypoScript
as a reference without you having to work through a large example or case study. However, some topics, such as the template auto-parser can only be explained with the help of a detailed example page structure. So in order to avoid having to define a new example each time in such cases, the following steps define a specific one. You can use the book quite well even if you don't use this example structure; however it makes things easier. The time spent on creating the example pages is less than 5 minutes.
First right-click TYPO3 and point to New. In the right frame New record click on Page (inside):
Give this page a title (e.g. Index); disable the Hide page checkbox in the upper area of the window and save the page. Call the Index page and click on Functions in the left menu. Make sure that the Create multiple pages wizard is selected in the drop-down list as pages can be created quite easily using this wizard. All you have to do is to enter the desired page titles. []
Chapter 1
The pages are created via the Create pages button. You can inspect the results immediately in the page tree. You can now assign sub-pages to the newly created pages. To do this, point to About Us, select the Create multiple pages wizard again, and create a few sub-pages. Repeat these steps for additional pages. The result should look like this in the page tree:
That's it. You can always build on this sample installation and keep coming back to it. []
Introduction to TypoScript
Declarative Programming with TypoScript The name TypoScript is confusing. TypoScript is not a classical script, let alone a programming language in the usual sense. It cannot even be classified as a descriptive language similar to HTML. What then is TypoScript? To answer this question you must take a look at the basic principle of all Content Management Systems—content and layout must be separated from each other and can be manipulated through templates and stylesheets. Tags that are dynamically replaced by the CMS's content are preferred. The type of tag varies mostly between and {Tag}, but the principle is always the same. But TYPO3 doesn't stop here—because of the ability to create the complete output template with TypoScript, the developer has full control over the layout. The influence of this template on the final design in comparison to normal HTML templates is disproportionately higher. Then what is TypoScript? The statement that it is not a programming language is not entirely true, since TypoScript, strictly speaking, can be regarded as a declarative programming language. TypoScript is a tool with which you specify what the output of the website and/or TYPO3 will look like. In contrast to a true programming language, you simply use TypoScript to describe the look of the result; the actual path to the solution is not programmed.
The Power of TypoScript
Unlike many other CMSs, TypoScript goes much beyond allowing you to integrate dynamic contents. Thanks to TypoScript, JavaScript-based menus, Flash, Graphics, etc. can be integrated with ease. You have maximum control over the design of the website and can control all options that would otherwise be addressed by HTML—simple text output, formatting, and much more. TypoScript also allows you to generate graphics at run time and the display of content can be changed according to the time of day or the user group. What does this multiplicity of functions mean to you? To begin with it saves you time learning TypoScript. Even though TypoScript is only a declarative programming language, you first have to get familiar with the syntax. Luckily, TypoScript is not as complex as PHP or Java. Although the ambitious TYPO3 developer may find this to be a limitation in some areas, this reduces potential errors. If you have developed complex menus via JavaScript, you know about the problems that crop up until the menu finally works reliably. For example, take a look at a really simple drop-down menu as used on numerous websites. <script type="text/javascript"> Chapter 1 function ����������������������������������������� MM_jumpMenu(targ,selObj,restore) { //v3.0 eval(targ+".location='"+selObj.options[selObj. selectedIndex].value+"'"); if (restore) selObj.selectedIndex=0; } //--> <select name="themes" onChange="MM_jumpMenu('parent',this,0)"> Please choose! Page 1 Page 2 Page 3 Page 4
This example illustrates some of the aspects and problems of JavaScript menus. If you want to create this type of menu, you have to understand JavaScript. Furthermore, you must have experience as to what browser the syntax works with and how to compensate for functions that create errors in others. Don't forget that this is a really simple example. When we approach dynamic websites, the effort and the likelihood of errors increase. If, for example, you want to provide semi-transparent navigation using graphics and layers, you have to have a thorough knowledge of HTML, DHTML, and JavaScript. The size of such scripts quickly bloats up to several hundred lines. It therefore takes some time before everything is running properly. The debugging adds to the difficulties. How does TypoScript circumvent these? What are its strengths? Take a look at the following menu: page.10.marks.MENU.1 = GMENU page.10.marks.MENU.1.expAll = 1 page.10.marks.MENU.1.NO { backColor = #000000 XY = 100, 20 10 = TEXT 10.text.field = title 10.fontColor = #ffffff 10.offset = 4,14 10.fontFile = fileadmin/verdana.ttf 10.fontSize = 11 wrap = | } page.10.marks.MENU.2 = GMENU page.10.marks.MENU.2.NO [ 11 ]
This is how menus are created in TypoScript. The example shown is representative of the size of scripts that create menus. Even graphical menus can be created with scripts of this length and the syntax is much simpler than that of JavaScript. Obviously menus are not the only area where TypoScript helps developers. Have you ever used PHP to create run time graphics? The experienced PHP developer doesn't usually have a problem with this, but the creation of a corresponding script requires a lot of development and testing time. With TypoScript this is no problem even for those with no PHP experience.
What is TypoScript?
Obviously TypoScript is not a normal programming or scripting language, and yet is very powerful. So how do we ultimately classify TypoScript? TypoScript can be used to configure TYPO3; it can thus be described as a configuration language for which no programming knowledge is necessary. In contrast to true programming or scripting languages, TypoScript lacks elements (such as loops) that are typical of such languages. In fact, TypoScript consists of configuration instructions that are incredibly simple in structure and are reminiscent of CSS in their simplicity (with respect to their syntax and not the effect). How TypoScript is structured can be seen with the help of the TypoScript Object Browser tool. For this, go to Web | Template and select the TypoScript Object Browser menu from the drop-down list.
[ 12 ]
Chapter 1
Here you can see the TypoScript objects in a clear tree structure. You will learn more about the TypoScript Object Browser and the objects on the following pages.
Back-end Configuration with TypoScript
Using so-called TSConfig instructions you can personalize the back-end for individual users or user groups. For instance, certain modules can be masked out in a user's working environment. For a different user one can, in turn, deactivate single options in a checkbox list. The entire back end can be controlled this way and be customized to the needs of the respective editors.
TypoScript and PHP
We have already pointed out that TypoScript is programmed in PHP. However, you do not have to know PHP syntax to be able to work with TypoScript; but knowledge of PHP is definitely an advantage. You can, for example, easily import information from the PHP class files using appropriate objects and values. The following example will show how this works. [ 13 ]
Introduction to TypoScript
Anyone who wants to know more about the structure and the development (from a programming point of view) of TypoScript should take a look at the tslib directory. It contains the PHP classes that control TypoScript. For a better understanding open the file typo3/sysext/cms/tslib/class.tslib_ content.php. You will find numerous PHP functions in it. We will concentrate on the CTABLE() function. function CTABLE ($conf) { $controlTable = t3lib_div::makeInstance('tslib_controlTable'); if ($conf['tableParams']) { $controlTable->tableParams = $conf['tableParams']; } // loads the pagecontent $controlTable->contentW = $conf['cWidth']; // loads the menues if any if (is_array($conf['c.'])) { $controlTable->content = $this->cObjGet($conf['c.'],'c.'); $controlTable->contentTDparams =isset($conf['c.'] ['TDParams']) ? $conf['c.']['TDParams'] : 'valign="top"'; } if (is_array($conf['lm.'])) { $controlTable->lm = $this->cObjGet($conf['lm.'],'lm.'); $controlTable->lmTDparams = isset($conf['lm.'] ['TDParams']) ? $conf['lm.']['TDParams'] : 'valign="top"'; } if (is_array($conf['tm.'])) { $controlTable->tm = $this->cObjGet($conf['tm.'],'tm.'); $controlTable->tmTDparams = isset($conf['tm.'] ['TDParams']) ? $conf['tm.']['TDParams'] : 'valign="top"'; } if (is_array($conf['rm.'])) { $controlTable->rm = $this->cObjGet($conf['rm.'],'rm.'); $controlTable->rmTDparams = isset($conf['rm.'] ['TDParams']) ? $conf['rm.']['TDParams'] : 'valign="top"'; } if (is_array($conf['bm.'])) { $controlTable->bm = $this->cObjGet($conf['bm.'],'bm.'); $controlTable->bmTDparams = isset($conf['bm.'] ['TDParams']) ? $conf['bm.']['TDParams'] : 'valign="top"'; } [ 14 ]
Thanks to this function, elements can easily be positioned with the help of a table. What does this mean for TypoScript? To understand this take a look at the following syntax, which uses the Content Object (cObject) CTABLE: page = PAGE page.10.marks.TABLE = CTABLE page.10.marks.TABLE { tableParams = width="800" border="0" cellpadding="3" cellspacing="0" offset = 0,0,0,0,0 cMargins = 15,15,15,15 rm.TDParams = width="100" valign="bottom" tm.TDParams = width="300" valign="bottom" lm.TDParams = width="300" valign="bottom" bm.TDParams = width="100" valign="bottom" c.TDParams = width=80% c.10 < styles.content.get tm.10 = HMENU tm.10.1 = TMENU tm.10.1 { NO.allWrap = | target = page } }
Using page.10.marks.TABLE, a new TypoScript object of the CTABLE type is defined. Using TypoScript, the remaining lines define the look and the content of the table. You are surely familiar with the HTML layout attributes; TypoScript's own attributes such as HMENU etc. will be shown later. Note that you will need templates and placeholders to get this example to work. More information on these can be found in Chapters 4 and 5. The output of this example is shown below:
[ 15 ]
Introduction to TypoScript
If you want to work more closely with the PHP functions, take one function after another and experiment with it. You will gradually understand how the meshing between TypoScript and PHP works. At the same time you also have an opportunity to learn about the weaknesses of TypoScript. Each TypoScript object can only deliver what the programmer has designed into the respective function (except when you develop your own functions). The core of TypoScript is the typo3/sysext/cms/tslib/index_ts.php file. It charts the information about the template datasets of the website tree. How this works is shown by the following TypoScript: page = PAGE page.typoeNum = 0 mybicycle.color = blue mybicycle.size = 26
This syntax creates the TypoScript object mybicycle. You assign the properties color and size to the mybicycle object. These two properties in turn are assigned the following values: color becomes blue and size gets the value 26. In the TypoScript Object Browser you will see objects, properties, and values represented as follows:
PHP can also be used directly in TYPO3; we will cover more about this later.
TypoScript Templates
You will get a detailed introduction to TypoScript templates in the next chapter. At this point we want you to simply make an initial contact. If one wants to describe a template, the word 'mould' immediately comes to mind. A template is simply nothing more than a master that is used over and over. Templates determine how the content that is entered by the editor and stored in the database will be displayed on the website. To put it bluntly, you can enter as [ 16 ]
Chapter 1
much as you want into the database—TYPO3 will not be able to display it in the front end without templates. You can check this out with an easy experiment. As an experienced TYPO3 user you have no doubt encountered the error message Error: No pages are found on the rootlevel. This message tells you that no page has been created yet for the current project. The following message, however, is rarer:
When this error message appears all the time in the front end you have to create a template before any content can be displayed. In Chapter 5 you will learn how this works, what template inheritance is, and what peculiarities you need to be aware of when creating templates. TYPO3 offers ready-made templates to make your work easier for most areas of application. You don't have to develop a new template each time you want to create a link, for example. However, the focus in this book is on the development of your own templates. This will help you create an appropriate solution for each and every application. Without spending too much time on templates at this time, we want to make the following observations: •
Templates contain information that describes a website precisely.
•
Cache, frame layout, content, and HTML header instructions are controlled through templates during the generation of the output.
•
A page can contain several templates.
•
Inheritance (cascading) plays an important role in templates. Templates are always passed on to subordinate pages.
[ 17 ]
Introduction to TypoScript
You now have an idea of how powerful templates are and what possibilities they offer. In a nutshell, the quality of a TYPO3 website depends on the quality of its templates.
Summary
In this chapter we provided an introduction to TYPO3 and the prerequisites for installing it. We set up an example page structure that we will use in the examples throughout this book. We then introduced TypoScript, a configuration language for which no programming knowledge is necessary. In contrast to true programming or scripting languages, TypoScript lacks elements (such as loops) that are typical of such languages. In fact, TypoScript consists of configuration instructions that are incredibly simple in structure. We wound up with an introduction to TypoScript templates.
[ 18 ]
Getting to Know TypoScript This chapter will look at the main features of TypoScript. We will explain the basic principles that are a part of learning any new language. Although TypoScript is not a programming language in the normal sense, it contains many features that you would expect a programming language to have, such as operators, constants, and datatypes. You will learn about these in this chapter.
Hello World!
What better way to begin than with the classic "Hello World" program? In this section, you will not only write your first TypoScript code, but also create your first TypoScript template. We are assuming that you have installed the Dummy Package and have not created a template yet. If you already have a template, you may skip the template creation section and go straight to the actual TypoScript section.
Creating a Template
There are a number of different ways to create the template. We will look at two of these methods, but the others work just as well. For the first method, point to Page under Web, call the context menu of one of the pages, and click on New. This creates a dataset of the type Template. For the second method, go to Web and there to Template, and select the root page in the side-bar. TYPO3 then responds with the (very appropriate) information NO TEMPLATE.
Getting to Know TypoScript
You now have two options. You can either select the standard template from the drop-down list or create a new template by clicking on the Create template for a new site button. We will choose the second of these, so that you will be creating your own template. After you have clicked on the Create template for a new site button, you have to answer the question Are you sure you want to do this? Subsequently TYPO3 creates a template dataset with the title NEW SITE. To edit the template, click on the Click here to edit whole template record link. This opens an input mask, which allows you to edit all of the fields in the template. At first, this mask appears somewhat cluttered and discouraging. It is better to go directly to the Setup field. To do this, go to the pencil icon next to Setup. The Setup content is then displayed. # Default PAGE object: page = PAGE page.10 = TEXT page.10.value = HELLO WORLD!
[ 20 ]
Chapter 2
If this page is now called from the front end, the following screen is displayed:
That's it! You have seen that text output can be created using a few lines of code. You can now change the source code as follows: page = PAGE page.10 = TEXT page.10.value = Hello World! page.10.wrap = |
If you have prior experience with HTML, you will immediately recognize what this modification has done—the string HELLO WORLD is now in italics. To check this, display the page again from the front end. Do not forget to click the Update button, as otherwise the changes will not be applied!
You can experiment a little with the Setup field. For example: page.10.wrap = |
This time the text is underlined. Other combinations are also possible. For example, if you enter: page.10.wrap = |
the character string is underlined and italicized. A glance at the source code generated at the front end is always interesting. The TypoScript code creates the following HTML code in the browser: Hello World!
This example was very simple, but it showed you how easy it is to create templates and how TypoScript can be used.
[ 21 ]
Getting to Know TypoScript
Syntax
TypoScript is less complex than most programming or scripting languages, but you will still need to know about such things as syntax, datatypes, and functions. However you will not have to worry about such things as flow diagrams for loops. In terms of difficulty, TypoScript is probably somewhere between HTML and CSS.
Objects and Properties
The following example will help you understand what objects are and how they are handled. You have several options for going to work every morning. You can travel by bus, train, car, or bicycle. All of these means of transport can be represented in TypoScript by the variable myVehicle. The actual means of transport can now be assigned to this variable as an object. Typical object types in this case would be TRAIN, CAR, or BICYCLE. We will focus on the third and most ecologically valuable of these options: myVehicle = BICYCLE
This syntax declares that myVehicle is an object of type BICYCLE. Of course every BICYCLE has properties, such as the size and the number of gears, even if it is only one gear in the simplest case. A BICYCLE object could therefore be described as follows: myVehicle = BICYCLE myVehicle.size = 28 myVehicle.gears = 3
These lines of code tell TYPO3 about the BICYCLE object—its size is 28 inches and it has three gears. The operator = (equality sign) is used to assign a value to a property. (Operators and value assignments are covered later in this chapter in the Operators section.) TYPO3 would already know that a BICYCLE object has properties for size and gears before these values are set. A BICYCLE object could have other properties such as color, age, and dynamo. It would be tiresome to type in all these properties every time, so TYPO3 assigns a default value when no explicit input is given for a property. Objects can be viewed using the TypoScript Object Browser, which is discussed in detail in Chapter 3. The BICYCLE object is represented as follows:
[ 22 ]
Chapter 2
TYPO3 has a number of built-in objects, for example, the HRULER object, which outputs a horizontal line. The properties of HRULER are lineThickness and lineColor. The following code defines a horizontal line: page = PAGE page.typeNum = 0 page.20 = HRULER page.20 { lineThickness = 10 lineColor = #000000 }
The third line creates a TypoScript object of the type HRULER. The following lines set this object's properties. (The meaning of the curly brackets will be explained later.) In summary, the following general syntax can be used for objects: [Object] . [Property] [Operator] [Value]
Let's take a closer look at the syntax of the Hello World! example. page = PAGE page.typeNum = 0 page.10 = TEXT page.10.value = Hello World!
[ 23 ]
Getting to Know TypoScript
If we translate this into a general syntax it looks like this: myObject = OBJECT myObject.Property = value1 myObject.subObject = OBJECTTYPE myObject.subObject .Property = value2
All TypoScript code concerned with objects will have a similar structure. Term
Description
Object
The object name can be chosen freely except for a few words such as config and styles, which are listed in the TypoScript reference documentation.
Type
The nature of an object is determined by its type. TypoScript recognizes a number of object types such as IMAGE or TEXT.
Property
The TypoScript reference documentation specifies properties for each object type. For example, the object type TEXT has a property called value.
Value
Properties are assigned values using the assignment operator =.
Path statements also play an important role in TypoScript. This is because each object and its properties can be addressed using a path. This path always consists of the objects and properties that are superordinate to the object. The individual elements of a path are separated by a dot.
Copying Objects and Properties
TypoScript code can be shortened by copying objects and properties using the < operator. This operator copies entire object trees. To understand this, look at the following code, which will cause the text Hello World! to be output three times, the first time normally, the second time in bold, and the third time in both bold and italic: page = PAGE page { typeNum = 0 10 = TEXT 10.value = Hello World! 15 = HTML 15.value = <strong> 20 = TEXT 20.value = Hello World! 25 = HTML [ 24 ]
You can see that the source code becomes larger as the number of objects increases, and it would be much worse if there were many objects and properties. The < operator makes it possible to compress this code to: page = PAGE page { typeNum = 0 10 = TEXT 10.value = Hello World! 15 = HTML 15.value = <strong> 20 < .10 25 = HTML 25.value = 30 < .20 }
The result is identical, but the source code is much clearer and more concise. As before, we start by defining a content object TEXT with the value Hello World!. This time the text is to be displayed in bold after the line break. To do this, we assign the element <strong> to the content object HTML in addition to the line break. Now you only need to copy the object page.10 to page.20. This is done by the line 20 < .10, which assigns page.20 the content object TEXT, the property value, and the value Hello World! of page.10. The same thing happens when we copy page.20 to page.30. This time we want the HTML to include <strong> as well as the element. The result of this syntax appears as follows at the front end:
Objects can be deleted using the > operator. For example, the following code will delete the object page.30 along with its properties, its subordinate objects, their properties, and so on: 30 > [ 25 ]
Getting to Know TypoScript
Finally, you should note that when an object is copied or deleted, only the properties and subordinate objects that have been assigned in previous lines of code are involved.
Referencing Objects
There is an alternative to copying objects. You can reference objects using the =< operator. Whereas copying only involves the properties and subordinate objects that have been assigned in previous lines of code, referencing also involves the properties and subordinate objects that are assigned later on. The following code illustrates the difference between copying and referencing an object: myObject = TEXT myObject { value = Hello World! textStyle.color.default = green textStyle.size.default = 3 } page = PAGE page { typeNum = 0 10 =< myObject 10.value = Hello World! as reference 15 = HTML 15.value = 20 < myObject 20.value = Hello World! as copy } myObject.textStyle.size.default = 5
Here is the result:
Where the object myObject was copied, the text is in point size 3 but, where the object myObject was referenced, the text is in point size 5. Because the =< operator was used, the object page.10 is a reference to the object myObject. This means that it can be used within the script wherever you want to. Any changes that are made to the referenced object are automatically made for all references. [ 26 ]
Chapter 2
When referencing, you must always give absolute values for objects. The usual method of writing a preceding dot does not work in this context.
Classic Sources of Errors
There are strict rules when using objects and properties. The HRULER example in the Objects and Properties section demonstrated how to draw a black line. The syntax was comparable to: page = page page.typeNum = 0 page.20 = HRULER page.20 { lineThickness = 10 lineColor = #000000 }
The syntax is, however, only comparable, not identical in both versions. You will notice this when you run the code and get this error message in the front end:
TypoScript is case-sensitive. For example, if you write linethickness instead of lineThickness, this property of the HRULER object will be assigned the default value. The names of object types must have all letters in upper case. If you write page = page instead of page = PAGE or myVehicle = Bicycle instead of myVehicle = BICYCLE, you will see the same error message. The names of properties must always start with a small letter and must not contain any special character. For example, when defining the BICYCLE object type, we could not have called a property Gears instead of gears. However, letters in the middle of the names of properties can be upper case, and this can be useful—numberOfGears is easier to understand than numberofgears.
[ 27 ]
Getting to Know TypoScript
The Classification of Objects
In Appendix A of this book there is an object index where the most important object types and their properties are listed. In this section we will look at how object types can be grouped. In principle, the object types in TypoScript can be grouped as follows: •
Top-level objects (TLOs): As you can guess from the name, these objects are at the highest level in the object hierarchy. The TLOs include PAGE, FRAMESET, and FRAME, and also sitetitle and config.
•
Content objects (cObjects): These objects are below top-level objects in the hierarchy, but are very important in TypoScript, as they are the objects used to create the output. The content objects include FILE, TEXT, HTML, and CONTENT.
•
Graphical objects (GIFBUILDER, GBObj): These objects can be created with the help of the GIFBUILDER object and its subsidiary objects. The graphical objects include EMBOSS, BOX, and IMAGE.
•
Menu Objects: These objects do not actually constitute a special object group. Strictly speaking these are subsidiary objects of HMENU. However, because menu objects are so numerous and diverse, this classification tells us very little. Various types of menus can be generated using menuObj. The menu objects include GMENU, TMENU, and GMENU_LAYERS.
Constants
You can define constants in TypoScript that are passed to the Setup field from the Constants field. Constants in TypoScript can only be defined in conjunction with the Constant Editor (which is described in detail in Chapter 3). Here we will just look at the general syntax for constants. To do this, open the Constant Editor, and enter the following line: myText.Content = Hello World!
In the Setup field enter the following: page = PAGE page { typeNum = 0 10 = TEXT 10.value = {$myText.Content} }
Calling the page at the front end gives you the text Hello World!. To access a constant, you should use $ followed by the constant inside curly brackets. [ 28 ]
Chapter 2
Using a constant in this way makes little sense, but constants are useful for setting the global configuration of a template. We will look at this in more detail in Chapter 3. Please note that constants can only be used inside templates. They cannot be used in other areas in which TypoScript can be used (such as back-end development).
Operators
There are many operators in TypoScript. You have already seen some of these operators in earlier sections of this chapter.
Value Assignment
You have already used the most important operator, the assignment operator = (equality sign). This operator can be used to define an object by assigning another object to it. It is also used to give properties their values. The syntax is always the same. To the left of the equality sign is the signifier of the object and/or the property. Everything to the right of the equality sign is assigned to the object or property as its value. page = PAGE page.typeNum = 0 page.10 = TEXT page.10.value = Hello World!
In this example the = operator is used several times. The line page = PAGE creates an object of the type PAGE and with the name page. typeNum is a property of the object type PAGE. Here this property is assigned the value 0. In the third line page.10 is defined as an object of the type TEXT. Finally you assign the value Hello World! to the value property of this object.
Value Assignment over Several Lines
So far we have only seen assignments on one line, but you can assign values over several lines. To do this, you need to use parentheses (round brackets) as follows: page.10 = TEXT page.10.value ( Hello, World! )
[ 29 ]
Getting to Know TypoScript
Here the value Hello, World! is assigned to the value property. Note that the equality sign is not used and that that it is distributed over two lines. This sort of value assignment that is distributed over several lines can make TypoScript code much clearer, but the final result at the front end is just the same—the text Hello, World! appears quite normally on one line. If you want a line break, you should use an appropriate HTML tag such as
or .
The Copy and Delete Operators
The operators < and > were introduced earlier in this chapter, but for the sake of completeness here is another example that uses both these operators: page = PAGE page.10 = TEXT page.10.value = Hello World! page.20 < page.10 page.20 >
This syntax creates a copy of the object page.10 and copies it to page.20. The last line deletes the object page.20.
Referencing
The operator =< is used to reference an object path. This operator is used to reduce the amount of source code for large templates. You will find an example later in this chapter. All changes made to the original object are automatically assigned to the reference. On the other hand, all changes made to a reference are also transferred to the original and to other references.
Conditions
You can define conditions with the [] operator. It is comparable to the if constructions of other languages. Code can be attached to certain assumptions with conditions, as in this example: [browser = msie] TypoScript-Code
The TypoScript code in the second line will be executed only when the browser is recognized to be Internet Explorer.
[ 30 ]
Chapter 2
Faster Writing Through {}
Braces (curly brackets) can be used to simplify TypoScript code. You have already seen the following syntax: page = PAGE page.typeNum = 0 page.20 = HRULER page.20.lineThickness= 10 page.20.lineColor = #fff000
Each of the last three lines begins with page.20. How would this look if the object definition is more extensive—for example, if we assigned values to other properties of the HRULER object such as spaceLeft and spaceRight? The source code would soon become too complicated to understand. We can avoid this problem by using the following syntax: page = PAGE page.typeNum = 0 page.20 = HRULER page.20 { lineThickness = 10 lineColor = # fff000 }
The principle of this "bracketing" is that TYPO3 gives precedence to the code area before the opening curly bracket over the bracketed lines. In this example this is page.20. The technique of bracketing is used extensively in TYPO3, and you will encounter it a number of times in the course of this book. Nesting is possible—for example, the above code can be also written as: page = PAGE page { typeNum = 0 20 = HRULER 20 { lineThickness = 10 lineColor = # fff000 } }
The result is the same, but this approach saves you some more typing. This example is too small to show you the true potential of bracketing. More complex examples will follow in the course of this book. It is important to make sure that the brackets are correctly inserted. It is best to get used to the correct bracket "insertion rhythm". [ 31 ]
Getting to Know TypoScript
Datatypes
Like other programming languages TypoScript has datatypes, but there are some differences between datatypes in TypoScript and in other languages. There are too many datatypes to list here, so we will only look at the basic types here.
Simple Datatypes
Some of the datatypes in TypoScript occur in other programming languages, but others will be less familiar. The following table shows you some of the more important datatypes: Data type boolean
Description
int
An integer is represented by an int value. For example, the xy property of a GIFBUILDER object, which determines the size of the graphic, is represented by two int values—by setting xy = 200, 300, a graphic of breadth 200 and height 300 pixels is generated.
string
The truth content of a statement is represented as a boolean value. By default, the values used are 1 for true and 0 for false.
The datatype string represents a string of characters. The altText property of a GIFBUILDER object, which is used to assign a text to a graphic has a value of the type string. For example: altText = My Graphic.
pixel
This data type is used for the value of some properties. Its meaning should be obvious.
VHalign
The vertical and horizontal orientation of an HTML element is assigned using this data type. Permitted values are r (right), c (center), and l (left) for horizontal alignment, and t (top), c (center), and b (bottom) for vertical alignment. Both values must always be given for this data type—the first determines the horizontal and the second the vertical alignment. A typical example is r, c.
For example, if you want to make the background for a graphic transparent, the property transparentBackground must be assigned a boolean value as follows: transparentBackground = 1
The value 1 is equivalent to "true". If you don't want a transparent background, you should set the transparentBackground property to 0.
[ 32 ]
Chapter 2
Objects as Datatypes
Some properties have object types as datatypes. Some of the possible datatypes are cObject, frameObj, menuObj, and GifBuilderObj. One example of the use of such datatypes is the cObject HMENU. This object recognizes the property 1/2/3..., which comes from the menuObj datatype. It allows you to define different menu objects, such as TMENU and GMENU for different menu levels. page.10 = HMENU page.10.1 = JSMENU … page.10.4 = TMENU
If you look in the TypoScript reference, you can find the datatypes that can be used in each case in the data column type of the respective object.
Functions as Datatypes
Some properties have a function as datatype. These properties inherit all of the properties of that function. An example of that is the menu object GMENU and its property allStdWrap, which has the function stdWrap as a possible datatype. This function in turn recognizes the property preUserFunc, which can now be assigned allStdWrap.
As already mentioned, this is only a fraction of all the possible datatypes. TypoScript datatypes are linked to properties or functionalities unlike the simple datatypes of other programming languages. There is a comprehensive overview of all datatypes that can be used in TypoScript at http://typo3.org/documentation/ documentlibrary/doc_core_tsref/Datatype_reference/.
[ 33 ]
Getting to Know TypoScript
The Wrap Principle
When working with TypoScript, you will often encounter the "wrap principle", where strings of characters are separated by the pipe sign | as in the following example: page = PAGE page { typeNum = 0 20 = TEXT 20.value = Hello World! 20.wrap = <strong>| }
The HTML output is <strong>Hello World!. This method not only allows you to format text; you can also use it for constructing tables. The following example will demonstrate the usefulness of the wrap principle. Suppose you want to read out a page title dynamically from the title field of a database. The TypoScript code could look like this: page = PAGE page { […] 20.marks.PAGETITLE = TEXT 20.marks.PAGETITLE.field = title }
But what if the page title is to be output in bold? Theoretically, you would modify the code like this: 20.marks.PAGETITLE.field = title
However, if you did this, TYPO3 would look for the database field title, which of course does not exist. The field is called title not title! It is precisely for such cases that the wrap concept exists: page = PAGE page { […] 20.marks.PAGETITLE = TEXT 20.marks.PAGETITLE.field = title 20.marks.PAGETITLE.wrap = | }
This does exactly what is desired—the title field is accessed, and the value returned is shown in bold. [ 34 ]
Chapter 2
Comments
When TypoScript source code becomes extensive, it should contain comments. There are various ways of doing this: /A single-line comment //A single-line comment #A single-line comment
Single line comments are marked by 1 or 2 forward slashes, /, or a hash sign, #, at the beginning of the line. Comments must be on separate lines and cannot be combined with "normal" TypoScript syntax. A typical mistake when defining a comment is the following: page.10.value = Hello World! #Output of Hello World!
Everything after a value assignment, that is after an equality sign, is interpreted by TypoScript as the value of a property or as an object. Thus a line like the one above will be output inclusive of the intended comment. Here the text that is displayed on the front end will be Hello World! #Output of Hello World!. You can have multi-line comments just like those in JavaScript or in PHP, for example. These are preceded by /*. Everything that follows, irrespective of the number of lines over which it extends, is part of the comment, continuing until it is ended with */. /* Multi-line comments can also be used */
Conditions
Like other programming languages, TypoScript has conditional statements. These allow actions to be executed when a particular condition is fulfilled. For example, browser detection can be used to redirect a visitor to the pages optimized for his or her browser. The following example shows how browser detection works: page = PAGE page.typeNum = 0 [browser = msie] page.20 = HTML page.20 { value = You are using Internet Explorer } [GLOBAL] [ 35 ]
Getting to Know TypoScript
This checks whether the visitor is using Internet Explorer. If they are, the character string You are using Internet Explorer is output. Conditions are enclosed in square brackets in TypoScript, []. If the condition is fulfilled, the TypoScript code up to [GLOBAL] or [END] is executed. Otherwise, this code is ignored. Several conditions can be defined simultaneously. For example: [browser = msie] [system = mac]
Here, the subsequent code is executed as soon as a condition is fulfilled. In this case the condition is fulfilled if Internet Explorer is recognized as the browser or if Macintosh is recognized as the operating system. As you can see, TYPO3 can detect operating systems as well as browsers. A complete list of possible conditions can be found in Appendix A.
The ELSE Condition
What would be the point of defining conditions without the option of an "else" condition? The code within the [ELSE] branch is executed when the condition is not fulfilled. page = PAGE page.typeNum = 0 [browser = msie] page.20 = HTML page.20.value = You are using Internet Explorer [ELSE] page.20 = HTML page.20.value = You are using another browser [GLOBAL]
If the visitor is using Internet Explorer, the character string You are using Internet Explorer is displayed. If he or she is not using Internet Explorer, You are using another browser is shown. You must end the "else" condition with [GLOBAL] or [END].
Extended Options
By default, TypoScript does not have an "and" operator. However, the Extended TS Conditions extension, which can be loaded using the Extension Manager, provides an && operator, which enables you to write the following code: [browser = msie] && [system = mac]
[ 36 ]
Chapter 2
The subsequent code is executed only if both the conditions are fulfilled. More complex structures are possible using the "or" operator, ||: [browser = netscape] && [version => 5] || [browser = msie] && [version => 5]
This code checks whether the browser is either Netscape version 5 or Internet Explorer version 5.
Defining Your Own Conditions
You are not restricted to the predefined conditions in TYPO3; you can define your own conditions. The new conditions must be defined in the file typo3conf/ localconf.php. Adding the following code to the end of the localconf.php file defines a condition that checks whether the visitor is using a Macintosh:
The browser used is determined by the PHP array $_SERVER. Detailed information about this can be found at http://www.php.net/manual/en/reservedvariables. php. The function user_match() can now be used in a condition. [userFunc = user_match(checkMac)] //Some more TypoScript code [end]
This code calls the function user_match() with checkMac as the parameter. The return value given by this function is true or false. In this example the function will only return true if mac occurs in the $_SERVER variables, that is if the visitor is using a Macintosh.
[ 37 ]
Getting to Know TypoScript
You can employ the TypoScript Object Browser to simulate conditions. Thus you can test what effects the conditions will have in the front end. More about this in the next chapter.
Functions
It is not easy to describe what TypoScript functions are. They are more like functional datatypes than true functions. This may appear all the more surprising if you look at the TypoScript reference documentation at http://typo3.org/, where you will find a section on TypoScript functions. This is because at PHP level the datatypes are replaced by independent functions. To understand TypoScript functions, we will look at the imageLinkWrap function. You can use this function to create links for graphics. The hyperlink created by this function can also be used to display an enlarged version of the graphic in a pop-up window: imageLinkWrap = 1 imageLinkWrap { bodyTag = wrap = | width = 800m height = 600m JSwindow = 1 JSwindow.newWindow = 1 JSwindow.expand = 0,20 }
You can now see how easy it is to use the imageLinkWrap function. All TypoScript functions can be used in a similar way. An overview of the most important functions can be found in Chapter 13. If you have trouble finding a particular function there, you can get a complete list at http://typo3.org/documentation/ documentlibrary/doc_core_tsref/.
Working with TSref
TSref is a great help when working with TypoScript. The original document is available at http://typo3.org/documentation/document-library/references/ doc_core_tsref/current/view/. There is also a reference at the end of this book listing relevant objects and properties. The broad topics covered by TSref are outlined in the following sections.
[ 38 ]
Chapter 2
Datatypes
The first section introduces the datatypes that are used in TypoScript. There is an example and a default value for each one.
Objects and Properties
This chapter demonstrates how to use objects and their properties. Besides referencing the usable datatypes, there is also a comprehensive explanation of optionSplit. OptionSplit allows you to assign different values to objects in an array with only one value assignment.
Conditions
This section contains a reference to all of the available conditions. An example and the syntax for every condition is provided.
Functions
You can get information about all available TypoScript functions in this section. There is a list of properties, datatypes, and their default values for every function.
Constants
This area explains how to use constants effectively.
Setup
This section gives you an overview of top-level objects. Included in this is information about configuring the website in the front end, with hints on whether to display the XML prologue and how to use the caching function.
cObjects
The usage of cObjects is demonstrated here. These objects allows you to define how page content is rendered. HTML, TEXT, IMAGE, etc. are all part of this. Properties, datatypes, and default values are introduced for each page type.
GIFBuilder
The GIFBuilder object lets you generate graphics dynamically. This section will show you the possible properties, datatypes, and default values. [ 39 ]
Getting to Know TypoScript
MENU Objects
This section introduces you to the MENU object that lets you define the most diverse types of menus. Almost everything is possible from text, or graphic, to JavaScript menus. In addition to all of the menu versions, this section demonstrates the properties and datatypes as well as all of the possible menu conditions.
Media/Scripts Plug-Ins
The focus in this area is on the media/scripts directory in which the standard plug-ins are located. You will learn how to link your own scripts and how to address their markers, subparts, and properties.
Standard Templates
This section strictly deals with information about the static templates that we links using the template record. These are undergoing constant changes and can vary greatly from version to version.
PHP Include Scripts
This section of TSref demonstrates how to utilize your own PHP scripts. In the Casestory area you are then given information on how to edit these scripts.
Casestory
This section shows you how to use include scripts in TYPO3.
Index.php
Index.php is the central file responsible for the display of pages with TYPO3 and TypoScript. This section introduces the methodology of this file and shows you how to pass data to it.
Tips
This area shows you tips and tricks to make TypoScript easier to use. There aren't too many tips yet; at this time you will find mainly information on how to use Direct Mail and Indexed Search.
[ 40 ]
Chapter 2
Summary
In this chapter we looked at the main features of TypoScript and explained its basic principles. We introduced objects in TypoScript and covered copying objects and properties, referencing objects, and the classification of objects into top-level objects, content objects, graphical objects, and menu objects. Next we covered the various operators in Typoscript, including the value assignment operator (=), the copy () operators, the object path reference (changetitle
In this case the page title would be My Page title.
[ 45 ]
Tools and Editors
Description
This field is there for clarity and has no effect on the front end. You should still enter a brief description of the template here—the customer, when the template was created, and who created it.
Resources
Resources enable the linking of files and/or elements such as PDF files, fonts, style sheets, and HTML files to the template. These resources can be accessed directly without having to enter the file path.
Constants
Constants can be defined using the Constants field. Constants are used to assign global values to variables. The mix of constants and variables in this last sentence will surprise developers who are used to other programming languages, where there is a clear difference between the two. In most programming languages variables get variable values while constants are assigned constant values. TYPO3 handles this a bit differently. There is no distinction between constants and variables. The value of both can be changed as often as you like. You can define a constant in the Constants field and then give it a series of different values. The last value assigned to it is always the valid one.
Setup
This is the most important array. The TypoScript code entered here controls the look of the page in the front end.
Editing the Whole Template
In the Click here to edit whole template record area you can configure all of the elements of the template. In addition to all of the fields already mentioned, you can also access other functions. The template can be deleted using the "recycle bin" icon in the upper area of the window. If you do this, the template is not actually deleted but marked with a deleted flag in the database. It is still available in the TYPO3 database. This is covered in detail in Chapter 5.
[ 46 ]
Chapter 3
The Object Browser
You will already be familiar with this tool, which diplays the TypoScript code in the form of a tree. In addition to displaying the constants, you can also use it to test conditions. You can access it by selecting TypoScript Object Browser from the drop-down menu under Web | Template.
This object browser works particularly well with bulky source code. The search facility (Enter search phrase) can be used to search for strings (for example, if you have entered the color value #fff000 somewhere in the template but can't remember where). The results of the search are then highlighted in color. Objects and properties can be edited directly. To do this, click on the relevant element in the tree structure. You can now make the desired changes in the form that was just opened. You can consult the entire TypoScript documentation by clicking the TS button. It is also possible to simulate conditions with the object browser. To demonstrate this, enter the following code into the Setup field: page = PAGE page.typeNum = 0 [browser = msie] [ 47 ]
Tools and Editors page.20 = HTML page.20.value = You are using Internet Explorer [ELSE] page.20 = HTML page.20.value = You are using another browser [GLOBAL]
This condition checks whether the user is accessing the page with Internet Explorer. If he/she is, the message You are using Internet Explorer is displayed. If a different browser is being used, the message You are using another browser is displayed.
Calling Setup from TypoScript's object browser displays the following image:
[ 48 ]
Chapter 3
In the bottom area of the window you can see the available conditions, among them [browser = msie]. By enabling the checkbox and clicking on Set conditions, this condition is applied to the current setup. The result looks like this:
Use this option for testing conditions, especially with bulky setups. Mistakes that can be made easily when using a number of conditions can easily be found and corrected.
The Template Analyzer
This tool displays a clear overview of the structure of the template. It can be accessed via Web | Template and the Template Analyzer option in the drop-down field.
This table displays whether Rootlevel, C. Setup, and C. Const constants have been set, what the page ID is, and at what root level the template is located. If you click on [ 49 ]
Tools and Editors
the template title, CONSTANTS and SETUP are displayed. The content of CONSTANTS, however, only appears if Clear Constants is not enabled in the template. The Template Analyzer also provides various tools to check the TypoScript code. For example, you can insert line numbers by enabling this in the Linenumbers checkbox and then clicking on the template title. Syntax highlighting can be activated by clicking on the Syntax HL checkbox. This causes objects, properties, etc. to be displayed in different colors for easy recognition. Looking at the TypoScript template code is particularly useful for beginners. You can gain an insight on how professionals use TypoScript.
The TypoScript Properties Display
This tool can be accessed via the TS-Symbol under the open Setup field. It displays objects, their available properties, the datatypes, and their descriptions. You can use it to transfer the displayed properties of an object to the Setup field with a single click of the mouse. You will see the various object types in a tree structure. To get more details about one of the objects, click on the corresponding Go hyperlink. The possible values, the datatype, a description, and the default value are displayed in a dialog box. Click on the + symbol to transfer the property to the input field. The dialog box is closed with Transfer and Close, and the selected properties are transferred to the Setup field.
The Admin Panel
Normally the Admin Panel only plays a role in front-end editing. With it, an authorized user can directly edit the website. You can activate it by entering the following lines in the Setup field of the template: config.admPanel = 1
The Admin Panel is subsequently displayed in the front end. You can use the installation tool to set which interface is made available after logging in. Call up Tools | Install and open All configuration. By default, under [Interfaces] you will now see backend. If you enter "backend, frontend" in this field you will get a menu after login that allows you to choose whether you want to edit the back end or the front end.
[ 50 ]
Chapter 3
If you don't like the terms Username, Password, etc., you can customize them. The settings for these are found under All configuration. Look for [login labels] and enter your terms.
Categories
The Admin Panel is divided into six categories. There is a back-end option behind each one of these categories. These areas can be opened by clicking on the plus sign in front of each name. We will look at these categories in more detail.
Preview
In this area it is possible to fade-in hidden pages and datasets for the purpose of editing. If start and stop times have been defined for the display of pages, these pages can be simulated with this option. This way you can check immediately whether the results satisfy your expectations. [ 51 ]
Tools and Editors
Cache
During the development stage of a project one normally has to delete the cache manually over and over again. You can avoid this by activating No Caching in this area. You can also set the number of levels of pages that this applies to.
Publish
You can save your TYPO3 pages as static HTML files. The advantage here is that you can access these pages quicker than normally cached content. In order to use this option, you have to define the path to where these files are saved in All configuration within the installation tool. Specify the directory in the [publish_dir] array. In order to make changes in these static pages visible in the front end, you have to explicitly release them via the Publish module.
Editing
The editor can use a number of the tools that you are already familiar with from the back end to edit page content. Among these are: •
Display edit toolbar: This will display the edit dataset, move dataset, delete dataset, and create a dataset like this one icons.
•
Display edit icons: There is a pencil icon after every content element. Click on it and you can edit the respective element.
TypoScript
There is a list of features that can be enabled or disabled in TypoScript. In practice, you do not need most of the available options and the entire Admin Panel is of limited use for actual TypoScript development. There are some options, however, that can be really useful, but are deactivated by default. The following table describes the options: Entry
Description
Recommendation
Tree display
The tree structure is displayed. This is clearer than the standard display.
Enable
Display rendering times
The time taken to display the Disable page elements is displayed.
Display messages
Messages for rendering, such as error messages, are displayed. [ 52 ]
Enable if there are problems
Chapter 3
Entry
Description
Recommendation
Follow rendering of contents
Additional rendering information is displayed.
Disable
Display contents
The HTML code of the corresponding TypoScript objects is displayed.
Enable
Explain SELECT command
The SQL queries used are displayed and analyzed.
Disable
Force TS rendering
The page is refreshed every time instead of calling it up from the cache.
Enable
The entry config.admPanel = 1 is only available to administrators. Normal users activate the Admin Panel by adding Tsconfig entries. A typical activation looks like this: admPanel { enable.edit = 1 module.edit.forceDisplayFieldIcons = 1 hide = 1 }
This code activates the edit property of the Admin Panel, displays the pencil symbol for editing, and hides the Admin Panel. You can assign more values to the enable property and activate more modules this way. Name cache
Description
edit
Editing symbols can be displayed or hidden.
info
Different types of page information such as the ID are shown.
preview
Hidden pages and page elements can be displayed, and user groups can be simulated.
publish
Pages are released.
tsdebug
A TypoScript debugger is made available.
The caching of pages can be disabled, and the cache can be deleted.
You can enable all the modules by specifying enable.all.
[ 53 ]
Tools and Editors
The Constant Editor
This tool can be accessed via Web | Templates | Constant Editor. It is mainly used to edit standard templates (for example, text and background color) by modifying constants. (We saw how to define constants in TypoScript in the Constants section above.) However, as we will see, the Constant Editor only makes sense if there is additional data within the constant definition.
Preparing Constants
The Constant Editor can only be used effectively if constants are appropriately commented. These comments tell the constant editor what the constants are used for. For example, the constant example introduced earlier contains the following code: myText.Content = Hello World!
Here myText.Content is a constant, but without comments it cannot be edited by the Constant Editor. If you define this constant as above and start the Constant Editor, it reports back with the messages No constants available and There are no editable constants available for the Constant Editor. If you want the Constant Editor to recognize the constant so that it can be edited later, you should modify the code as follows: #cat=MyText;type=string;label=A Greeting myText.Content = Hello World!
If you now select the entry Constant Editor in the upper drop-down field instead of Info/Modify, you will see the following:
[ 54 ]
Chapter 3
This time the constant is recognized as such by the Constant Editor. All constants should be defined with comments so that the Constant Editor can process them. This can be done with the following general syntax: #cat=[Category];type=[Input-Type]; label=[Description]
A Practical Demonstration: Defining Heading Colors through Constants
There would be little point in having constants if they were only used to define static text. The following simple example demonstrates the true power of constants and of the Constant Editor. It will also introduce you to wraps, a concept that you will find often in this book, as it involves defining wraps and constants that will be used to change the heading color of the template. Select Info/Modify from the drop-down field, click on the pencil icon next to Constants, and enter the following code there: content.defaultHeaderType = 1 content.wrap.header1 = | content.wrap.header2 = | content.wrap.header3 = | content.wrap.header4 = | #cat=colorDefinition;type=color;label=Colour of h1 h1_colour.value = maroon #cat=colorDefinition; type=color;label=Colour of h2 h2_colour.value = green #cat=colorDefinition; type=color;label=Colour of h3 h3_colour.value = silver #cat=colorDefinition; type=color;label=Colour of h4 h4_colour.value = lime
Save this information, and enter the following TypoScript code in the Setup field: page = PAGE page { typeNum = 0 10 = TEXT 10.value = Hello, World! 10.wrap = {$content.wrap.header1} 15 < .10 [ 55 ]
This code uses the constants defined in the Constants field. To understand the advantages of this approach, start the Constant Editor, and select COLORDEFINITION under Category:
Here you can see the defined constants in the form of drop-down fields. The color values of headlines can be changed using these fields. Try it out and modify a color and then take a look at the page created in the browser. This example has shown how useful constants can be. You can define the editable data of the template like colors and image sizes as constants and then use the Constant Editor to change them as required. A few things need to be kept in mind when creating constant comments. Every comment must be typed in the line before the corresponding constant. Furthermore, the different parts of the comment must be separated from each other by a semicolon. [ 56 ]
Chapter 3
In summary, constants must be defined whenever you want to have the option of making changes to a template from a central location.
Categories
Categories are used to pack constants into logical bundles so that you can see instantly how they are related. You can choose category names at will, but the names should be meaningful (particularly if you are going to sell your templates), and TypoScript suggests a few categories in the standard templates: : Category
Description
advanced
Advanced functions that are rarely used
basic
Constants that are particularly important for the template and are customized frequently
content
Constants that influence the look of content elements
menu
Constants that control menu settings are assembled here
page
Constants that control the general settings such as meta-tags
plug-in
Constants of the relevant plug-ins
When defining your own categories, chose meaningful names, especially if you intend to sell them to clients. The more meaningful the name is, the easier it will be for a client to get familiar with the template.
Subcategories
Subcategories are used to arrange constants in the Constant Editor. Subcategories and categories are assigned using a slash as in the following example: # cat=basic/color/a; type=color; label=Background color bgCol = white
The constants are shown here in the opposite order to their definition in the CONSTANTS field. The subcategory color is assigned to the category basic. Constants can be sorted by assigning the parameter a. If you do not assign a parameter, TYPO3 assigns the default value z.
[ 57 ]
Tools and Editors
The following subcategories are permitted: Subcategory color
Description
dims
size details of pictures, tables, frames, etc.
enable
options of enabling/disabling important functions in a template
file
locations of files for background pictures, fonts, etc.
language
language-dependent options
links
hyperlinks
typo
typographic content
color details
The following subcategories are based on the content elements of TYPO3: cheader, cheader_g, ctext, ctextpic, cimage, cbullets, ctable, cuploads, cmultimedia, cmailform, csearch, clogin, csplash, cmenu, cshortcut, clist, cscript, and chtml.
Field Types
You can use the type parameter to determine the field type. This specifies the manner in which the constant can be edited in the Constant Editor. For example, a constant called fontColor would probably have the field type color, because it is only through this field type that the color selection field is displayed in the Constant Editor. Available field types are: Field type boolean
Description
color
HTML-coded color
comment
Code marked as a comment (selected ="", not selected ="#")
int
Whole number for which a value range (e.g. [0-10]) can be defined
int+
Positive whole number
file
Name of a file to be uploaded
offset
Series of comma-separated whole numbers
options
Selection field in which the individual values must be separated by commas
string
Text input field
wrap
Permission for the editing of wraps
Boolean value
[ 58 ]
Chapter 3
We will now look at some examples of the various field types and the element label, which can be used to define headings: # # # # # #
The heading must be given at the same time so that the purpose of each field can be seen at a glance. If a heading is not enough, you may also give a description, which will appear automatically under the heading, using the following syntax schema: Heading: Description text
The description text is separated from the heading by a colon. TYPO3 automatically recognizes it as description text and displays it accordingly.
Describing Categories
You should only describe categories if it is really necessary—for example, if your project has many categories or you want to describe the template more precisely for the customer. You may have already seen categories described in the context of standard templates, where the descriptions are used for things such as displaying screenshots and describing category elements more precisely. This example shows a typical application: ## TSConstantsEditor Config TSConstantEditor.basic { header = My Template description = This is my template. It is based on frames. bulletlist = 3 Frames. image = gfx/mytemplate.png 1=leftFrameWidth 2=topFrameHeight 3=page.offset 4=page.contentWidth,styles.content.imgtext.maxW 5=background.file.left
[ 59 ]
Tools and Editors 6=background.file.top 7=background.file.page,page.file.stylesheet,bgCol }
This code is entered in the Constants field of the template. The result can be viewed in the Constant Editor, where you can select the BASIC category from the CATEGORY list field. Elements can be easily recognized and modified if necessary, using this page. However, the descriptions are more useful in combination with a screenshot, and it really helps if the elements are further visualized through numbers. Value
Datatype
Description
Array, 1-20
List of constant names
You have seen that numbers are inserted in the screenshots. The numbers given here allow a context to be created between the constants and the screenshot so that you know immediately which element acts on which page element.
bulletlist
String
This creates a
list using which important statements about the category can be made. Each of the individual list entries must be introduced with //.
description
String
This describes the actual template. To add a line break, add //.
image
Image
This merges the screenshot. The graphic itself must either be in the gfx directory or must be merged via the resource field of the dataset template.
header
String
This defines the descriptive heading. All characters are displayed in uppercase.
TypoScript in HomeSite
There is a TypoScript syntax parser for Macromedia's HomeSite that can be used to create TypoScript code. It can be downloaded from http://www.rainerkuhn.net/ projects/ts4hs/ts4hs.html. It includes a good integrated syntax highlighting facility, but unfortunately the syntax parser does not yet run as smoothly as it should. For example, there are problems with comments. A workaround is to put a space before single-line comments so that you need to type # Comment rather than #Comment.
[ 60 ]
Chapter 3
However, the installation is problem-free. The downloaded scc file is copied into the parser directory of HomeSite. And then you create the Registry key TypoScript for TYPO3 under the branch HKEY_CURRENT_ USER\Software\Macromedia\ HomeSite5\Parsers\. To use the parser, activate the color-coding scheme in the options menu under Settings and Editor. The result becomes visible when you use TypoScript code in HomeSite.
HTMLArea RTE
The Rich Text Editor (RTE) was the standard WYSIWYG editor for TYPO3 for a long time. With Version 4.0 this has changed and HTMLArea RTE is now included. HTMLArea is one of the best open-source rich-text editors. With it you can set up content from a browser in a WYSIWYG environment, which is then stored in HTML format. But this new editor is anything but popular in the TYPO3 community. For one thing, it often needs to be reconfigured after an update. This isn't usually a huge problem, but with HTMLArea RTE one often has to experiment with TSConfig to get it done. So if you are planning to make HTMLArea your editor you absolutely have to look around the appropriate forums to check whether there are any serious implications for you. http://www.typo3.net/ would be a good place to start. [ 61 ]
Tools and Editors
As we have mentioned, the installation of HTMLArea is easy for TYPO3 4.0 users. If you are using an older TYPO3 version, you can install HTMLArea. Uninstall the old version of RTE; subsequently the new editor can be started up using the extension manager (the extension key is rtehtmlarea).
The editor can then be customized using Page TSConfig in the page dataset. The configuration gets set in the page tree dependent on what inheritance is desired. If you want the configuration to apply to the entire website, write it into the root page.
Using Your Own CSS Styles
It is possible to combine the CSS styles of the editor with those of the front-end page. The styles used in the editor can also be used for the creation of the web pages. The CSS statements for the alignment of text, for instance, is one of these styles. In order for these CSS styles to be used, the HTMLArea CSS file must be loaded in the front end. page.includeCSS { file1 = fileadmin(mycss.css file2 = typo3/sysext/rtehtmlarea/htmlarea/plugins/DynamicCSS/ dynamic.css
In order to be able to use your own styles in the editor, the dynamic.css file has to be customized. Simply add the desired CSS definitions. p.mytext{color:#fff000; border:solid 1px}
In addition, the CSS classes have to be activated. To do that, the TSConfig field of the root page is expanded with the following entry: RTE.default.classes.Paragraph = mytext
Now you can mark the desired text in the editor and format it with the newly installed CSS style in the selection box. And since the CSS file is also used in the front end, this new CSS style is indeed used.
[ 62 ]
Chapter 3
Activating and Deactivating Buttons
Not all buttons are displayed in the editor by default. If you want to show all of the buttons in the editor, add the following line into the TSConfig field of the page: : RTE.config.tt_content.bodytext.showButtons = *
You can see a lot more buttons in the editor now.
It is also possible to just hide individual buttons. In this way you can, for instance, make sure that the editor doesn't strike through or subscript elements. R �TE.default.hideButtons = underline, strikethrough, subscript, Superscript
This table offers an overview of all of the available buttons: Property bgcolor
Button
bold
Bold text
center
Centering
chMode
A selection box under the input field through which the HTML code can be displayed
class
Sign formats
copy
Copy
cut
Cut
emoticon
Add an icon
fontsize
Font size
fontstyle
Font style
formatblock
Format block
indent
Indent
image
Add image
italic
Italics
Background color
[ 63 ]
Tools and Editors
Property left
Button
line
Line
link
Hyperlink
outdent
Remove indent
orderedlist
Ordered list
paste
Paste
redo
Redo
removeformat
Remove format
right
Right alignment
strikethrough subscript
Text that has a line through it subscripted text
table
Table
textcolor
Text color
underline
Underlined text
undo
Undo the last step
unorderedlist
Unordered list
user
User-defined elements
Left alignment
Setting the Permitted Tags
Together with the configuration of the HTML editor, transformation also plays a deciding roll. The content of the text is in the editor during editing and is in a different format after saving into the databank than when being displayed in the front end. Transformation therefore takes three paths: 1. Editor to database: Depending on the configuration, the entered content is stripped of unwanted tags. Only permitted tags,
tags with classes, and special TYPO3 tags (i.e. ) end up in the database during saving. 2. Database to editor: The data are transformed once more. All permitted tags and classes show up in the editor again. 3. Database to front end: Depending on configuration, some of the enclosed
tags are amended. The transformed page is then outputted to the front end.
The control of the transformation between editor and database happens via an appropriate configuration parameter. For pages that are based on CSS Styled Content, ts_css is used (if you are using Static Template Content, select ts).
[ 64 ]
Chapter 3
ts_css takes care of the following settings:
•
Headlines and lists are saved directly as HTML ( and
or ).
•
Tables stay intact.
•
Externally linked graphics are stored in the uploads/ directory. Absolute path designations for local graphics are transformed to URLs.
•
Absolute links are changed to relative ones.
The standard setting in HTMLArea is ts_css (if you want to change the mode, use overruleMode = ts). You can define which tags are preserved after parsing with allowTags. Make sure that no amendments are made, but that all tags that have to be rendered are preserved. allowTags = b, i,strong, em, table, tbody, tr, th, td, h1, h2, h3, h4, h5, h6, div, p, br, span, ul, ol, li, pre, blockquote, strong, em, a, img, hr, tt, q, cite, abbr, acronym, address
Always specify the tags you want with leading blanks and comma delimited.
Customizing the Color Field
The available default color selection box makes choosing colors really easy.
With this, editors can choose just about any color hue and create beautiful colorful pages. If the design of the webpage doesn't warrant so many colors, you can customize the color box accordingly. A reduced color picker could look something like this:
[ 65 ]
Tools and Editors
The editor now must chose only from the six available colors. In order to define this color selection, we must first deacivate the standard color picker and then replace it with our own color definitions. Add the following to Page | TSConfig. RTE.default.disableColorPicker = 1 RTE.default.disableSelectColor = 0 RTE.colors { color1 { name = orange value = #ff6600 } color2 { name = blue value = #3366ff } color3 { name = light grey value = #f1f1ff } color4 { name = black value = #000000 } color5 { name = white value = #ffffff } color6 { name = grey value = #999999 } }} RTE.default.colors = color1, color2, color3, color4, color5, color6
You can define as many colors as you want. The value after name is displayed in the selection box and value describes the color value that is used. You have garnered some insight into the configuration of HTMLArea. The following commented example illustrates what a complete configuration could look like: RTE > #Own Css classes are defined in an external file RTE.default.contentCSS = fileadmin/_temp_/my.css #This is where the own CSS classes that will later be offered for [ 66 ]
Chapter 3 #formatting are entered RTE.default.classesCharacter = light,dark #The definition of the buttons that are to be displayed RTE.config.tt_content.bodytext.showButtons = textstylelabel, textstyle, formatblock,left, center, justifyfull,outdent, indent, textindicator, line, link, image, findreplace, spellcheck, chMode, removeformat, copy, cut, paste, undo, redo, showhelp, about RTE.default.hideButtons = underline, strikethrough, subscript, superscript RTE.default.proc { #These tags are permitted allowTags = b, i, strong, em, table, tbody, tr, th, td, h1, h2, h3, h4, h5, h6, div, p, br, span, ul, ol, li, pre, blockquote, strong, em, a, img, hr, tt, q, cite, abbr, acronym, address #CSS styled Content is being used overruleMode = ts_css dontConvBRtoParagraph = 1 internalizeFontTags = 1 allowTagsOutside = img, hr, address denyTags = sup, sub, strike, center, u #The permitted classes are defined allowedClasses = light, dark entryHTMLparser_db = 1 entryHTMLparser_db { allowTags < RTE.default.proc.allowTags xhtml_cleaning = 1 htmlSpecialChars = 0 noAttrib = b, i, u, strike, sub, sup, strong, em, quote, blockquote, cite, tt, br, center tags.hr.allowedAttribs = class tags.span.allowedAttribs = class tags.b.remap = strong tags.i.remap = em keepNonMatchedTags = protect } }
This is a comparatively short definition, yet it offers numerous options. We recommend that you take a look at other examples of configurations. You can find one at http://www.contentschmiede.de/files/rte_pagets_working.txt.
Making Additional Functions Available
You decide with the configuration whether the Advanced option is activated or deactivated. If you activate it, all the options of the editor are made available. If this option is deactivated, only a few configurations can be selected. [ 67 ]
Tools and Editors
Even though HTMLArea offers a multitude of functions, the editor can also be controlled via your own plug-in interface and can be extended with numerous tools. Plug-in
Description
Acronyms and UserElements
Allows you to define your own tags and abbreviations. Tag administration can be handled with the custom tag extension (de_costum_tags).
CharacterMap
Allows the entry of special characters using a character map.
ContextMenu
This activates a context menu.
DynamicCSS and InlineCSS
Allows you to assign predefined CSS styles to areas of text. The styles are stored in an external CSS file, which is defined with RTE.default.contentCSS.
FindReplace
Permits find and replace functions inside of the editor.
InsertSmiley
Smileys can be added to text.
QuickTag
Allows insertion of user-defined tags to the editor.
RemoveFormat
Redundant formatting is removed. This plug-in is useful when adding Word text into the editor. RemoveFormat automatically deletes the redundant foramtting.
SelectColor
The HTMLArea color selector is replaced by the TYPO3 color selector.
SpellChecker
Gives you a spell-check option.
TableOperations
This plug-in makes additional buttons available for editing data tables.
TYPO3Browsers
HTMLArea by default uses pop-up windows to insert hyperlinks and graphics. This plug-in makes sure that TYPO3's own windows are used.
Customizing the Rich-Text Editor (RTE)
Up until version 3.8.x, RTE (Rich-Text Editor) was the standard tool for entering and designing content. With TYPO3 4.0 it was replaced by the HMTLArea RTE. A lot of users are still working with older TYPO3 versions, which is why we will take a look at the configuration of RTE.
[ 68 ]
Chapter 3
We are not going to explain how to use this editor, only how to customize it, for which there are numerous options. RTE can be configured on three levels: •
Page level: RTE can be equipped differently for different elements of a website. You can, for instance, prevent the use of complicated formatting in a particular area of the website.
•
Content level: The use of available elements depends on the content being displayed. If you want to make sure that no colors are used when the content type is Text, you can disable the color selector.
•
Access-right level: The configuration depends on which user is working with RTE. If an editor, for instance, uses too much formatting in text areas, you can remove some of the formatting elements from his or her RTE.
Configuring the Toolbar
In the standard display, only some of the formatting elements are shown in the RTE. If you want more elements to be available, you need to add them manually. The following table contains all of the available values: Property bgcolor
Button
bold
Bold text
center
Centering
chMode
A selection box under the input field through which the HTML code can be displayed
class
Sign formats
copy
Copy
Background color
[ 69 ]
Tools and Editors
Property cut
Button
emoticon
Add symbol
fontsize
Font size
fontstyle
Font style
formatblock
Format block
indent
Indent
image
Add image
italic
Italics
left
Left alignment
line
Line
link
Hyperlink
outdent
Remove indent
orderedlist
Ordered list
paste
Paste
right
Right alignment
table
Table
textcolor
Text color
underline
Underlined text
unorderedlist
Unordered list
user
User-defined elements
Cut
For example, if you want the administrator to have access to all of the elements, enter the following code in the TSConf field of User Admin: options.RTEkeyList= bgcolor,bold,center,chMode,class,copy,cut,emoticon,fontsize, fontstyle,formatblock,indent,image,italic,left,line,link,outdent, orderedlist,paste, right,table,textcolor,underline,unorderedlist,user
[ 70 ]
Chapter 3
The next time the RTE is started, it will be extended with these additional fields.
Now you can determine which fields are enabled for each user. The RTE can be enabled or disabled for different parts of the page tree. For example, if you want the RTE to be displayed only for the text elements Regular text element and Text with image, enter the following in the Page | TSConfig field: RTE.default.disabled = 1 RTE.config.tt_content.bodytext.types { text.disabled = 0 textpic.disabled = 0 }
Defining Your Own Classes
You can use your own style classes to extend the RTE. The newly defined formats can then be seen under character type as in the following example: RTE.classes { bold { name = Bold font value=font:bold } boldandred { name = Bold, red font value=font:bold; color:red } } RTE.default.classesCharacter = bold, boldandred
The two classes bold and boldandred are inserted into the field Set character type using this syntax. The syntax is always the same—the name to be displayed in the window is defined by name, and the desired formatting is specified by value. [ 71 ]
Tools and Editors
To ensure that the defined classes are actually shown in the editor, you must assign them to the classesCharacter property in the default area of the RTE object.
Paragraph Formats
Style classes can be defined not just for characters but also for paragraphs. By default the classes h1 to h6, p, and pre are available for paragraph definitions. However, you can use the following syntax to remove standard classes and to add new style classes: RTE.classes { runningText { name = Normal value = font:regular; font-size:11pt; font-family:Verdana; } Heading { name = Heading value = font:bold; font-size: 14pt; font-family: Verdana; } RTE.default.classesParagraph = runningText, Heading RTE.default.hidePStyleItems = * }
The syntax is almost identical to that for the style classes for characters—you assign a name to the class with name and the desired formatting with value. To have the style class actually recognized as a paragraph definition, you must set RTE.default. classesParagraph. It is advisable to delete the default classes. This can be done using the code: RTE.default.hidePStyleItems = *
Of course you don't have to delete the standard classes; if you want to you can also customize them. By default, the RTE is configured with the following style sheet code: BODY{ border: 1px black solid; border-top: none; margin: 2 2 2 2; font-family:Verdana font-size:10px color :black background-color :white } TD {font-family:Verdana; font-size:10px;} DIV {margin-top:0px; margin-bottom:5px;} PRE {margin-top:0px; margin-bottom:5px;} OL {margin: 5px 10px 5px 30px;} [ 72 ]
These settings can be overridden using the mainStyleOverride property. A typical example is the following: RTE.default { mainStyleOverride_add.P = font-size:14px;
The content of the subpart is displayed completely normally on the page and you can see right away what this page will look like. This subpart will later be replaced dynamically just like the marker.
Double��������� Headings
When generating the design template, one important aspect must be considered. Take a look at this simple design template: Hello, World! ###NEWS###
When this design template is called later from the front end (assuming the appropriate template), you will get an HTML error. Display the source text in the front end and you will see the following: <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> [ 82 ]
The source text was shortened for reasons of space. Nevertheless two problems can be seen: the generated HTML document has two heading areas as well as two tags. TYPO3 handles the design-template in accordance with this principle: TYPO3's own source code is imported up to the first tag and after that comes the complete design-template. This is obviously an error. There is an easy workaround for this problem: one more subpart has to be inserted into the design template. Hello, World! Heading on top
The subpart ###BODY_CONTENT### is annotated within the tag. You can later specify via TypoScript that the design template applies only to this area. When the TYPO3 basic framework is merged with the design template, any elements that are located outside of the subpart ###BODY_CONTENT### are not imported. And this solves the problem of the double heading and body areas.
Summary
The basic layout of a website is normally determined by using design templates. They are different from normal templates. All design templates contain static and dynamic elements. All static elements are hard-coded in the HTML file. On the other hand, everything dynamic is marked with placeholders. These placeholders can then easily be replaced with dynamic content. There are two different types of placeholders—markers and subparts. To maintain clarity in subparts, the use of HTML comments is recommended.
[ 84 ]
Templates You are probably familiar with the concept of templates from other content management systems. The basic principle of TYPO3 templates is, however, somewhat different and more comprehensive. For example, it has its own language—TypoScript—that is used to generate templates.
The Concept of Templates
The importance of TYPO3 templates is underlined by the fact that it is not possible to display pages from the TYPO3 project without them. The following tasks are performed by templates: •
Integration of design templates
•
Definition of the page properties
•
Menu generation
•
Dynamic generation of images
•
Integration of extensions
How the templates address these tasks is explained in the following sections.
Hello World!
Templates can be created and managed using the Web | Templates module. When this module is called up for the first time in a project, no templates will be displayed on the right-hand side of the screen. In order to create a new template, click on the Create template for a new site button and the template NEW SITE will be created (answer the security question Are you sure you want to do this? by clicking on OK). You can rename this template later to whatever you want.
Templates
If you call this page from the front end, HELLO WORLD! will be displayed without you having to do anything else. This value is automatically entered into the template by TYPO3. For detailed information, please refer to the previous chapter.
Hello World! Part II
Let's go full speed ahead to gain a better understanding of templates. You are about to create your first template. Once again the classic Hello World! will make an appearance. There are no detailed explanations of the code here; we want you to get a feel of how templates work and what you have to do to create them. Under fileadmin/_temp_/ create the file hello.htm with the following content: Hello World! Is this text really displayed?
Call the Setup field from the template dataset and enter the following code: temp.mainTemplate = TEMPLATE temp.mainTemplate { template = FILE template.file = fileadmin/_temp_/hello.htm } page = PAGE page.typeNum = 0 page.10 < temp.mainTemplate
The previously created hello.htm HTML file is imported by the FILE object. But nothing spectacular happens when the changes are called up in the browser: the sentence Is this text really displayed? is displayed. Even when you look at the [ 86 ]
Chapter 5
source code of the created HTML file you can see that the HTML page is displayed in its original form. Although this is correct in this case, it is not really the gist of the matter. Then why use a CMS at all? It is precisely here that a special feature of the cObject TEMPLATE comes to light—not only is the HTML file imported with its help, but individual areas are also replaced by dynamic content. Make the following changes to the content of the Setup field: temp.mainTemplate = TEMPLATE temp.mainTemplate { template = FILE template.file = fileadmin/_temp_/hello.htm workOnSubpart = BODY_CONTENT subparts.BOLD = TEXT subparts.BOLD.value = Hello World! } # Default PAGE object: page = PAGE page.typeNum = 0 page.10 < temp.mainTemplate
When this file is called from the browser, you can see that the dynamic content Hello World! is displayed. A glance at the source code displays these changes: <strong> Hello World!
The changes can be looked at without paying any attention to the exact syntax: the TEMPLATE cObject received the command to edit the ###BODY_CONTENT### section. In addition, ###BOLD### was replaced by a cObject TEXT.
Inheriting Templates
You surely know the principle of inheritance from CSS. The style definitions that are specified for an element are also assigned to the subordinate elements. The following example shows how this works without paying too much attention to the CSS syntax: body { font-family: Verdana, Sans-Serif; color: #000; background-color: #fff; } [ 87 ]
Templates
Define font, font color, and background color for the tag. Font and font color belong to the CSS properties that are inherited. Therefore, it is sufficient to define these properties in the , since all other elements inherit it. h2 { color: #f00; background-color: transparent; }
The script of the heading h2 is displayed in the same font as is defined in the tag. But a new color was defined. This way you can save a lot of keystrokes in bulky stylesheet definitions. But what does CSS have to do with templates in TYPO3? A lot, at least from the point of view of the inheritance principle, because the templates are inherited by subordinate elements in a manner similar to CSS properties. In the case of templates the subordinate pages are relevant for the elements. All instructions given by TypoScript in a page are applicable not only to the current page but also to all subordinate pages.
Template Elements
In principle, the creation of a template is not complicated. However, when the Template module is called for the first time for the purpose of creating a new template, one can be completely overpowered by the number of the input fields.
[ 88 ]
Chapter 5
You will learn about the significance of the individual fields on the following pages. Some of the elements have already been covered in detail; we will only mention those here. To ensure that all options are displayed on the page, the checkbox Show secondary options (palettes) in the bottom area of the window must be enabled. •
Template title: This field defines the name of the template. This name is displayed in the back end for an overview. You can choose whatever name you want; there are no syntax restrictions. The name should be meaningful and the template should be identifiable by the name alone.
•
Website title: The name assigned here is used in the tag of the website. This always takes place in accordance with the {Web site title}::{Page name} formula. The page name should therefore be selected carefully. The name of the company is usually entered here. If you are bothered by the way the title is allocated, please refer back to Chapter 3 to read how page titles are assigned.
•
Constants: In the Constants field, the values for the constants are defined. Chapter 3 provides detailed directions about TypoScript constants and the significance of the Constants field.
•
Setup: We have already discussed the Setup field in detail. This field is the most important element since you are writing real TypoScript code here. [ 89 ]
Templates
•
Resources: Here you have the ability to specify resources for the template. These resources can be images, HTML templates, True Type fonts, etc. The advantage is that when copying template datasets, the references to the resources remain preserved. This is also true if a resource is renamed. In TypoScript the resource data type exists to reference these resources.
•
Clear: Both Clear Setup and Clear Constants play a decisive role in template inheritance. You can set the checkboxes to prevent the cascading of Constants or Setup.
•
Rootlevel: The root of the page tree is defined by the rootlevel. You will recognize the rootlevel by a blue arrow in front of the template symbol. Inheritance also plays an important role with the rootlevel: the root template serves as the starting point for all TypoScript instructions and remains so until another template is defined as the root level.
•
Include static: In the Standard Templates section of this chapter you will learn about the standard templates that can be imported with Include static. To import a template you only have to click on it in the list box on the right. You can also import several templates. You can specify the sequence in which these templates will later be executed using the arrow keys. TYPO3 is configured to first execute the standard templates and then the basis templates by default. If the Include static AFTER basedOn checkbox is enabled, the order is reversed.
•
Include static (from extension): This allows you to load extensions that contain standard templates. To use this option the appropriate extension has to be loaded.
•
Include basis template: Basis templates are libraries that help organize TypoScript code. To import a basis template, select the directory symbol to browse for records. If you want to create a completely new basic template, click on the pencil symbol. If you want an overview of the sequence of templates, use the Template Analyzer, which you can call up via Web | Template.
•
Static template files from T3 Extensions: In this field you specify the sequence for inserting static templates. Three options are available:
Option Default (Include before if Root-flag is set) Always include before this template record Never include before this template record
Description In this option the standard templates of the extensions are inserted before the root template. The standard templates of the extensions are inserted immediately before the relevant template. This option ensures that the template of the extension is not inadvertently changed by one's own TypoScript code. The insertion of the standard template before the relevant template is prevented with this for that reason. [ 90 ]
Chapter 5
•
Template on next level: This option defines the responsibility of the template dataset for the next lower level. The purpose of this is to avoid having to assign a separate template dataset to each page of the subsequent level. This is useful, for example, if you want the front page for web access to have a different design than the sub-pages.
•
Description: Here you can enter a description for the template. You will primarily enter those things that will help you and/or your customers to quickly become familiar with the function of the template.
•
Backend Editor Configuration: Don't use this input field. The principle (which has since been revised) is that the CSS editor can be customized with stylesheet statements.
Objects and Properties of Websites
The use of TypoScript objects has already been covered. The objects that occur in completely normal websites, however, were not discussed in detail. Before moving on to the creation of websites via templates in the next section, we are therefore reviewing the objects that make up a website and how TypoScript handles them.
Defining Page Properties with TypoScript
If you have mastered HTML, you know that a website consists of several elements. In TypoScript these elements/properties are defined with the PAGE object. PAGE has numerous properties for this, of which only the most important ones are presented here. There is a complete overview of the properties in the list in Appendix A.
bodyTag
You can engineer a complete tag using this property. A typical statement for this property could look as follows: page.bodyTag = bodyTag =
You can use all known HTML attributes within the tag. Use CSS syntax, especially if modularity and editability are required. We could customize the above example as follows: page.bodyTag = bodyTag = [ 91 ]
Templates
stylesheet
Here you have the option of inserting a stylesheet file. If the stated file exists, it is linked in accordance with the usual HTML syntax . stylesheet = fileadmin/style.css
There are also other ways of defining CSS properties; more about this later. The most commonly used form is stylesheet. You can also use the @import syntax. This is made possible by the PAGE property includeCSS, the syntax for which is presented in Appendix A.
meta
Meta tags describe web pages more precisely. The meta property is designed for this purpose. The syntax always follows the same principle—after meta, type the name of the desired meta tag separated by a dot. page.meta.AUTHOR = Daniel Koch page.meta.DESCRIPTION = A descriptive text
A slight discordant note: By default no Dublin Core meta tags can be used here. If you want to do this, you have to integrate the plugin.meta static template.
Integrating Design Templates
In the previous chapter we showed you how the basic layout of a website is created using a design template. Only two steps are required for using the design template: 1. The design template is integrated. 2. The markers and subparts are activated. Incidentally there are other ways of creating templates. You can, for example, create pure TypoScript templates or modify the standard ones provided by TYPO3. The basic principle of both of these options will be presented to you in the course of this chapter.
Activating the Design Template
When the design template is ready, a logical link has to be created between it and the template. To do this, generate a new design template with the following content:
[ 92 ]
Chapter 5 Hello, World! Heading on top
You can now save this file under the name hello.htm in the fileadmin/_temp_/ directory. If this directory does not exist yet, create it. If you want to, you can change the directory and file names, provided the same changes are reflected in the template. Then create the file css.css with the following content in the fileadmin/ css directory: h1 { font-family : Georgia, "Times New Roman", Times, serif; font-size : 16px; line-height : 12px; font-weight : bold; color : #660000; } div { font-size : 12px; color : #213c4d; font-style : normal; font-family : Verdana, Arial, Helvetica, sans-serif; }
This CSS file will format the two elements and . The file hello.htm can now be called statically from the browser. The design template can be checked one more time with this. Are all the elements in the right place? Is the formatting correct? If everything is in order, the actual creation of the template can begin. To do this, call [ 93 ]
Templates
the template module and enter the following in the Setup field. If you have not yet created a template, first click Create Template for a new Site: temp.mainTemplate = TEMPLATE temp.mainTemplate { template = FILE template.file = fileadmin/_temp_/hello.htm } page = PAGE page.typeNum = 0 page.10 < temp.mainTemplate
The design template is integrated into the template using this syntax. The heart of the matter is the FILE object using which the content of a file can be loaded. Check the file extension to find out the file type. Since the file in this case is a text or HTML file, its content is outputted at the specified location. You have to specify the path to the file in the property; the starting point for the path statement is the typo3/ directory. If you call the page from the front end, you get the following:
Although the content of the page is shown, note that the stylesheets have been removed. This is on account of the already mentioned problem with the two heading and body areas, which are inserted by default. You will learn how to solve this problem in the next chapter.
Activating Placeholders
The page that we have called from the front end so far shows little (or nothing) spectacular. Only the design template has been inserted. This is hardly the point— after all the markers and subparts have to be replaced. In order for this to work, you have to find a way to activate these placeholders. [ 94 ]
Chapter 5
Activating Subparts
We have already pointed out the problem of double headings with design templates. The solution to this was the subpart ###BODY_CONTENT###. TypoScript can now be instructed to reduce the design template to the content of the subpart ###BODY_CONTENT###: temp.mainTemplate = TEMPLATE temp.mainTemplate { template = FILE template.file = fileadmin/_temp_/hello.htm } page = PAGE page.typeNum = 0 page.10 < temp.mainTemplate page.10.workOnSubpart = BODY_CONTENT
If you call this page from the front end you will see that there is indeed only one area now. This, however, leads to a new problem, because the page is now displayed in the front end without formatting. A look at the source code reveals why this is so: the reference to the stylesheet file that was there in the design template is gone thanks to the condensing of the design template to the subpart ###BODY_CONTENT###.
Integrating a Stylesheet
To apply the stylesheet, re-integrate it via the stylesheet property of the PAGE object. For this, the path to the CSS file is assigned to stylesheet: temp.mainTemplate = TEMPLATE temp.mainTemplate { template = FILE template.file = fileadmin/_temp_/hello.htm } page = PAGE page.typeNum = 0 page.10 < temp.mainTemplate page.stylesheet = fileadmin/_temp_/css/css.css page.10.workOnSubpart = BODY_CONTENT
As soon as this page is called from the front end, the formatting is visible. The well-known syntax is now shown in the source text.
[ 95 ]
Templates
Activating Markers
Up until now, the marker ###NEWS### appears exactly as it was defined in the design template. This is about to change by replacing the marker ###NEWS### with the text There is also some news: temp.mainTemplate = TEMPLATE temp.mainTemplate { template = FILE template.file = fileadmin/_temp_/hello.htm } page = PAGE page.typeNum = 0 page.stylesheet = fileadmin/_temp_/css/css.css page.10 < temp.mainTemplate page.10.workOnSubpart = BODY_CONTENT page.10.marks.NEWS= TEXT page.10.marks.NEWS.value = There is also some news
The marker of the design template is activated using marks. The syntax of marks differs somewhat from the versions discussed so far. Which placeholder is to be activated is first specified in marks. After that, the object that is to be used with this placeholder is specified. In the example shown this is a TEXT object, to which the character string that is to replace the placeholder ###NEWS### is transferred using value. Of course this procedure doesn't make a lot of sense since hard-coded text in the template is every bit as easy to insert in the design template. The principle of this example, however, is the same as in the replacement of placeholder with dynamic content which we will see later.
Locating Errors
When working with placeholders, error analysis is particularly time-consuming. The tendency is to search through the entire TypoScript code, even though this is usually not necessary: error sources can normally be pinpointed to a few places. page.10.marks.NEWS= TEXT page.10.marks.NEWS.vaue = There is also some news
When this code is called from the front end, the marker ###NEWS### cannot be seen, but neither is the new content displayed. If this occurs, it is most likely due to a wrongly typed property. In the example we just illustrated, the property vaue is used, which does not exist; the correct property is value.
[ 96 ]
Chapter 5
Another common error is the use of a wrong marker name. The result of this is that the marker continues to be displayed in the front end: page.10.marks.NEWTHINGS= TEXT page.10.marks.NEWTHINGS.value = There is also some news
The marker ###NEWS### can still be seen at the front end. The reason for this is that instead of ###NEWS### the marker ###NEWTHINGS### was used. The error is not always this obvious. If the marker, however, continues to be displayed in the front end in its original glory, it is most likely due to a wrongly typed marker name.
The Auto Parser Template�
There are usually a number of people involved in creating an online presence with TYPO3. The designer creates the layout, which is then implemented by an HTML author and then modified for TYPO3 by a programmer. This chain of involved persons often leads to problems. It gets particularly awkward if the HTML author makes changes to the code written by the programmer. Template comments are often deleted or moved—which of course destroys the template. The paths to graphics and stylesheet files are also risky: if these are not correct, display problems are created. The list of risks and errors could be continued indefinitely. The fact is, however, that later modification of templates (especially by inexperienced HTML authors) can have serious consequences. The Template Auto Parser extension is designed to help you avoid these problems. It gives you an edge in several areas: first of all, you can create modern layouts with it that use CSS for the positioning of elements instead of tables. In addition, this extension manages the paths to graphics and other external files (CSS, JavaScript, etc.). The Auto Parser is unfortunately not perfect; it takes a long time to learn and the markers are more accurate if set manually.
Installing the Parser
Before you can use the Auto Parser, it has to be installed. The Extension Manager usually helps you do this. If you don't have the extension, install it manually. Download the extension from http://typo3.org/extensions/repository/ search/automaketemplate/0.1.0/. After you have done this, open the extension manager and click on the search button in the Import Extensions area to find and highlight the downloaded t3x file. Click on Upload extension file und then on Install extension and you are finished. To check whether this worked, call up the relevant template in the Template module. Select TypoScript Object Browser from the drop down-box in the upper part of the window. The following entry should now be displayed in the plugin branch. [ 97 ]
Templates
Creating a Sample Application
Theory is always dull. Let us use a typical example to demonstrate how the Auto Parser Template works. Create the field hello.htm in fileadmin/_temp_/ with the following content: The Auto Parser Navigation Content Footer
It is immediately clear that this is an HTML page that is based on a CSS layout. Pay particular attention to the paths of the integrated CSS file and the logos, which will change in the course of the subsequent statements.
Editing the Settings
In order for the Auto Parser to control the output, it must first be configured. In this section you will learn the required procedure step by step. First enter the following code in the Setup field:
There are a number of new elements here: content loads the previously created template file hello.htm. The HTML elements that are to be wrapped with subparts are defined under elements. In this example these are the tag, the , the , and the tag. The elements and get a marker, subparterMarker, so that they can be activated with the TEMPLATE cObject. The page title, however, is a problem with the hello.htm template; it has already been defined but, as is well known, TYPO3 sets the tag by default. The tag can be automatically deleted from the template with rmTagSections = title. The problems with the paths to the CSS file and the graphics are solved with relPathPrefix. The relative paths of the templates are edited with it. And finally, the page is created. When it is called from the browser, the following source text can be seen: [ 99 ]
Templates Navigation Content Footer
The new source text looks completely different; to begin with, there are numerous subparts in the source code, the element has been deleted and finally the paths of the - and the tags have been changed. But that is not all: the Auto Parser Template starts getting really interesting when the marked subparts are replaced with content. For this, you have to add some a few more statements into the Setup field: plugin.tx_automaketemplate_pi1 { content = FILE content.file = fileadmin/_temp_/hello.htm elements { BODY.all = 1 BODY.all.subpartMarker = DOCUMENT_BODY HEAD.all = 1 HEAD.all.subpartMarker = DOCUMENT_HEADER HEAD.rmTagSections = title DIV.all = 1 H1.all = 1 } relPathPrefix = fileadmin/_temp_/ }
[ 100 ]
Chapter 5
The first part is identical to the one already defined. In the next step, the mainTemplate object, which is enclosed by the DOCUMENT_BODY placeholder, is created. With the workOnSubpart property you can specify that the object is applicable only to the part of the HTML template that is identified with DOCUMENT_BODY. temp.mainTemplate = TEMPLATE temp.mainTemplate { template =< plugin.tx_automaketemplate_pi1 workOnSubpart = DOCUMENT_BODY
The next lines define the subparts and populate them with dummy texts. The syntax here is rather simple: the relationship is specified in each case by the ID that was assigned to the HTML element in the template. subparts.navi= TEXT subparts.navi.value = The navigation goes here subparts.content = TEXT subparts.content.value = The content goes here subparts.footer= TEXT subparts.footer.value = The content of the footer goes here }
What was done for the element at beginning of the source text is repeated here for the element: temp.headTemplate = TEMPLATE temp.headTemplate { template =< plugin.tx_automaketemplate_pi1 workOnSubpart = DOCUMENT_HEADER }
Finally the page is generated in the usual way; the content of mainTemplate is copied to the area and the content of headTemplate to the area. page = PAGE page.typeNum = 0 page.10 < temp.mainTemplate page.headerData.10 < temp.headTemplate
If you now call the template from the front end and look at the source text, you will be surprised: [ 101 ]
Templates <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> My Root The navigation goes here The content goes here The content of the footer goes here
The source code has been completely modified. For reasons of space, only the most important elements are printed here. In a real-life situation you will see that the standard TYPO3 comments and the JavaScript are also there. Furthermore, the content and the relative paths to the CSS file and the graphics have been automatically modified. The contents of the and tags have also been replaced.
Standard Templates
TYPO3 comes with a few standard templates. These can be seen under Web | Template | Click here to edit whole template record by clicking on the Include static field. Standard templates are very useful if you don't want to create your own templates. You can modify the standard templates that come with TYPO3 as you wish, but your options are limited. If you want to create your page with a minimum of effort, use the standard templates. The following example shows how easy these templates are to use:
[ 102 ]
Chapter 5
You will find a brief description of the templates in the following pages. This should make it easier and faster to select the right template. Not all templates are listed; that would take too long. You can find a complete list of standard templates that can be used with TYPO3 at
All templates beginning with template access the standard template content for rendering. These templates are particularly useful for new users of TypoScript who want to get quick results. Templates can be customized quite easily with to the Constant Editor. The following table describes these templates: Template
Description
template; TU
This is a frameless template. The template has a menu on the left. The individual menu items can have a background graphic. A graphic on top, possible definitions of page divisions, and page width are additional features.
template; RE
A template with three frames. The navigation is in two parts. The first menu level is shown in the upper frame. Various background pictures for active, normal, and rollover can be assigned to the left menu.
template; NEWSLETTER
This template, as the name implies, is designed for sending newsletters (this is done in combination with the Direct Mail Module extension).
template; HYPER
A template with frames. The upper frame contains a DHTML menu and the logo.
template; GREEN
A very green HTML template. The advantage of this template is that it can easily be edited using an HTML editor. The upper frame contains a DHTML menu, a logo, and a graphic.
template; GLUECK
This is optically one of the most daring templates. The default colors blue, purple, green, and yellow compete for the viewer's attention. The template consists of a threecolumn table. The individual columns can each have a different background graphic.
template; FIRST
This is a frame-based template that has a two-level menu. The background color and size can be specified separately for each of the three frames.
template; CrCPH
This one-page template is based on a single HTML page. The template contains two text menus and two columns for the content. [ 103 ]
Templates
Template
Description
template; CANDIDATE
This is also based on a single HTML page. The right column can be hidden if needed. A title graphic is displayed in the upper area of the page. The header graphic can be displayed across two columns and the content of the right column can be displayed in the left column.
template; BUSINESS
This template is based on frames. A graphic is displayed in the left frame. Below this, there is a two-level text menu. You can select a different background graphic for each of the two frames.
template; MM
A very simple one-page template with navigation in the upper area. A right column can be added if desired.
template; BLUG
This template consists of three frames. A graphic is displayed in the upper frame; there is a graphical menu in the left frame, which can be fine-tuned through a variety of options. In addition, the size and background color of all frames can be changed. The right frame can be used for any and all content.
temp.*
A number of help templates have been created in TYPO3. For example, temp. tt_board(shared) [DEPRECIATED], which belongs to the plug-in forum, is included by default. This template, as well as plugin.tt_board_list and plugin.tt_board_tree, which are based on it, should not be used any more. Their tasks are now handled by the Message board, twin mode (tt_boar) extension.
styles
All templates beginning with styles contain code snippets that perform all kinds of tasks. What these tasks are can be determined from their names. Thus, for example, styles.hmenu.tu is used to define a menu. The styles templates thus offer the possibility of integrating specific elements such as menu, site maps, etc. into the page without too much effort.
records (example)
This template illustrates very simply how content from the tt_* extension tables can be rendered. The developers of this template expressly point out that it is only meant for demonstration purposes and is not suitable for practical use.
[ 104 ]
Chapter 5
content (default)
The most frequently used template is content (default). Not only are websites and other templates based on it, but it also contains general information about how data is outputted to the front end.
frameset
In frameset you can find all of the templates using which frame-based layouts are realized. Which template handles which layout can be gleaned from the name. For instance frameset; top-page entails a two-part frameset, with one frame above and one below.
plugin
This merges mainly dynamic content that is based on your own PHP functions. A look at the plugin list will show you that a number of templates are marked with [DEPRECIATED]. Ideally none of these templates should be used anymore since their functionality can now be found in the respective extensions.
Pure TypoScript Templates
So far we have been speaking constantly of HTML design templates when discussing templates. Of course this is not the only approach. You can also create templates that are based totally on TypoScript. There are no disadvantages to this approach. If you are a TypoScript expert, it probably will not take you any longer to create a TypoScript template than to build an HTML design template. With TypoScript templates you create the content step by step with TypoScript and then publish them. TypoScript templates are created using the Template module; you can create a new dataset of the Template type with the Pages or Lists module. Here is a simple example: page = PAGE page.typoeNum = 0 page.bodyTag = page { 10 = HTML 10.value =
20 = TEXT 20.value = Welcome 20.wrap = | 30 = HTML [ 105 ]
Templates 30.value = 40 = TEXT 40.value = 50 = HTML 50.value = 60 = HTML 60.value =
20 = TEXT 20.value = Welcome 20.wrap = | 30 = HTML 30.value =
40 = TEXT 40.value = Menu 50 = HTML 50.value =
60 = HTML 60.value =
}
A very simple HTML layout can be generated by using various content objects. Use the content object TEXT to output normal text. This example accesses the content element HTML for defining the table. The table could, however, also be realized via Ctable as in the next example. The TypoScript template generates the following HTML syntax in the front end:
Welcome
Menu
Although this present example made use of a table construction, CSS-based page layouts are actually better. To create such layouts you normally need a stylesheet file, which is integrated in the following way: page.stylesheet = fileadmin/_temp_/styles.css [ 106 ]
Chapter 5
So far the example has consisted of only text and various HTML elements. Graphics can also be integrated easily: 50 = IMAGE 50 { file = fileadmin/_temp_/img/logo.jpg altText = My Logo }
As you can see, anything that can be done via HTML templates can also be realized directly with TypoScript. The method you choose when all is said and done is a matter of taste.
TemplaVoilà
The latest method for creating templates is using TemplaVoilà. This is a new extension that makes it possible for TypoScript developers to integrate templates using a graphical user interface. The purpose of the templates can also be specified here. The biggest advantage of TemplaVoilà is that various layouts can be implemented without any PHP knowledge. Thanks to TemplaVoilà, an HTML master can be formatted as a template with just a few mouse clicks. And the best part—new content types can be created that are no longer limited by the structure of the database tables. In addition, elements can be nested within each other at will, putting an end to the rigid three-column limitation. TemplaVoilà also introduces another important new feature: once content is created, it can be reused in multiple locations. This is not a copy and paste procedure, but is handled via a link to the content. All this is realized with XML. Flexforms are another new feature in TYPO3. They provide another option for entering and saving data. Flexforms are covered at the end of this chapter. TemplaVoilà and Flexforms are very interesting topics. For more information about both of these topics, go to http://typo3.org/documentation/document-library/ templavoila/.
System Prerequisites
Let's demonstrate the functionality of TemplaVoilà with a simple example. So that you can use the same example as this book, go to http://de.selfhtml.org/ layouts/nr10/index.htm and download the template. This template was created by Jeena Paradies with SelfHTML. It serves our purposes very well and it may be used freely. [ 107 ]
Templates
Before you can use TemplaVoilà, you have to install the following additional extensions: •
css_styled_content
•
static_info_tables
•
templavoila (The Enable the classic page module checkbox in the lower part of the window has to be enabled; if you don't do this now, it will not be possible to start TemplaVoilà up later on.)
Before you start working on or with TemplaVoilà, you should first empty the cache. You will find the settings for this in the lower left area of the window under Admin functions. Click on Clear cache in typo3conf/.
Preparing TemplaVoilà
After the installation of the extensions and the refreshing of the back end, the Web array has been expanded by the addition of TemplaVoilà.
Now you have to tell TYPO3 that TemplaVoilà is now responsible for the administration of templates and contents. Enter the following setup into the template of the root page: page = PAGE page.10 = TEXT page.10 = Hello, World! page.10 = USER page.10.userFunc = tx_templavoila_pi1->main_page
With TYPO3 versions earlier than 3.8 you have to also use page.typeNum = 0. You also have to pick the CSS_Styled_Content extension in Include static (from extensions). [ 108 ]
Chapter 5
Next, create a new SysFolder (e.g. TemplaVoilaData). This type of page is not meant to display pages in the front end; its purpose is to administer datasets in the back-end. SysFolders are best compared to directories in the file system.
In the next step, let the root page know where the template files can be found. To do this, go to the root page context menu and click on Edit page properties. The previously created SysFolder TemplaVoilaData should be selected under General Record Storage page.
Setting up the Data Structure
Copy the downloaded layout into the _temp_ directory. In order to call up the editor provided by TemplaVoilà, you have to call up the layout page (in the current _temp_/layout/index.htm example) using the Filelist module. [ 109 ]
Templates
Specify the document structure in the window that opens and select TemplaVoilà from the context menu of index.htm. Create the template with these two steps: 1. Define the placeholders that will later be replaced by the content. 2. Link the placeholders to the HTML elements using the graphical interface. How you do this is up to you. You could define all of the placeholders first and then link them together or you could define and link them one after the other. The most clearly laid out way and the way we did it in the example is to follow the logical construction of the page and work through the elements from top to bottom. The primary element is ROOT and it is usually linked to the HTML element . Click on Map and select the tag. The selected element is transferred and you can now choose from the following two options in the drop-down list: •
INNER: The selected tag remains where it is and is linked inside the tag.
•
OUTER: The selected tag does not remain and is not transferred to the element.
Always select INNER if the content is later to be placed inside the element. You always have to select INNER for the tag. The changes are then applied with Set. You can now create the next element. How this works is illustrated with the help of a simple content element (Page title). Enter field_header for the field name. Call up the next dialogue window by clicking on Add and you will see the following options:
[ 110 ]
Chapter 5
Field
Description
Mapping Type
Defines the mapping type. Specify here whether this is an element, container, or attribute.
Title
Specifies the title of the element.
Mapping instructions
Determines how the field is mapped.
Sample Data
After the element has been mapped, the content defined is displayed.
Editing Type
Determines the type. If this is a normal content element, Content Elements is selected. Options available are: Plain input field: An input field. Header field: An input field with a linking option. This field is designed for headings. Header field, Graphical: Graphical headings. Text area for bodytext: Multi-line input field. Link field: The TYPO3 dropdown box for a URL. Integer value: Numbers. Image field: Dropdown box for a graphic. Image field, fixed W+H: Graphic with a set size. Content Elements: Content elements. Selector box: Drop-down box. TypoScript object path: TypoScript object.
[Advanced] Mapping Rules
Advanced mapping rules are defined via this field.
[ 111 ]
Templates
The settings for the activated heading element look like this:
Set up the document structure for all of the other elements of the page the same way. In our current example, Content Element is set for each of Header, Content, and Footer. TypoScript Object Path is selected for Menu and News. That way the News and the Menu can be dynamically loaded from the back end. The document structure should now look like this:
[ 112 ]
Chapter 5
Now the document structure has to be linked to the HTML element. Call up Preview and set the Exploded Visual mode in Mapping Window. The mapping is accomplished by clicking on the appropriate icons. The selected element is transferred and you can now choose between the two familiar options of INNER and OUTER. First link the ROOT element with the tag and then all of the other elements can be linked. The finished mapping for the example template looks like this:
[ 113 ]
Templates
After all of the elements have been mapped, you can check what it looks like with Preview and make whatever changes or improvements you see fit. In parallel with this, a respective template object is generated automatically. You can create the data structures and the template objects by clicking on Save as. The notice that Data Structure (uid 2) and Template Record (uid 2) was saved in PID "58" will then be displayed in the upper area of the overview page. If you want to see what data has been set up, click on List under Web and select the SysFolder that you created.
When discussing data structure (DS) one cannot avoid template objects (TO). Although the two have different definitions, they are nonetheless based on each other. The already mentioned template objects refer to the DS and determine how the DS elements are outputted. In other words, the TO has the instructions as to what HTML file is to be used for rendering. The difference between DS and TO can be summarized as follows: •
A DS defines which fields can be linked with the HTML template.
•
A TO determines which HTML elements are linked to which fields.
Data structures consist of a definition of arrays, fields, and field types. The following listing illustrates (in extracts) a typical DS: <meta type="array">
The start of a section containing meta-information: 1 1
The first object of a data structure always has to be the element ROOT of data type array. The rest of the objects of the document structure are contained in this object. [ 114 ]
Chapter 5 ROOT <description>Select the HTML element on the page which you want to be the overall container element for the template. �������������� array <el type="array">
That is how DS objects are defined. The header element for this case: Header <description>Page Title <sample_data type="array"> This is where the page title is entered. <eType>input_h
An input field is created: input <size>48 <eval>trim Header
The Content element is defined by the Content Element type. Here is how this works in XML syntax: Content <description>Content of the main window <sample_data type="array"> There is a lot of text [ 115 ]
Templates here. Mind you it is there strictly as a placeholder. What you enter as text is not very important. <eType>ce 10= RECORDS 10.source.current=1 10.tables = tt_content 0 group db tt_content <size>5 <maxitems>200 <minitems>0 <multiple>1 <show_thumbs>1 Content Menu <description>The Menu <sample_data type="array"> This is where the menu is <eType>TypoScriptObject lib.myObject News [ 116 ]
Chapter 5 <description>This is where the news are <sample_data type="array"> All of the news are entered here. <eType>TypoScriptObject lib.myObject Footer <description>The footer data <sample_data type="array"> This is where the Copyright and other important data is. <eType>ce 10= RECORDS 10.source.current=1 10.tables = tt_content 1 group db tt_content <size>5 <maxitems>200 <minitems>0 <multiple>1 <show_thumbs>1 Footer [ 117 ]
Templates
Creating Content
After the data structure has been set up, the content can be created. To accomplish this, you have to link the template object with a given page. Call up the context menu of the respective page and select Edit page properties. In General Record Storage page select the SysFolder you have created. Now you can select the template object.
[ 118 ]
Chapter 5
After saving, you will see new fields for the defined content Header, Content, and Footer in the lower part of the window.
Now you can create new content and configure your page the way you want.
Conclusion
TemplaVoilà is one the most powerful TYPO3 extensions and much too comprehensive to cover in more detail here. We wanted to give you an example to show you the revolutionary nature of this new approach to templates. The official documentation for this topic can be found at http://typo3.org/ documentation/document-library/extension-manuals/templavoila/ current/view/.
[ 119 ]
Templates
Flexforms
Although Flexforms are often mentioned in the context of TemplaVoilà, they can also be used independently and can in particular be used for developing extensions. With the help of an XML interface, extensions can break open the field assignments of the database tables. TemplaVoilà—surely the best-known extension to use Flexforms—shows how well this functions. With a few mouse clicks you can create templates that do not have to conform to the normal three-column grid.
Summary
TYPO3 has its own language, TypoScript, that is used to generate templates. The tasks performed by these templates are the integration of design templates, definition of page properties using TypoScript, menu generation, dynamic generation of images, and the integration of extensions. Templavoilà is a new extension that makes it possible for TypoScript developers to integrate templates using a graphical user interface. The biggest advantage of TemplaVoilà is that various layouts can be implemented without any PHP knowledge.
[ 120 ]
Working with Graphics TYPO3 also has a lot to offer in the area of graphics processing. In the simplest case, the editor integrates finished pictures as content elements. For this, the relevant graphic is selected from the Fileadmin area or loaded on the server from the local hard drive. The showstopper is that TYPO3 is not restricted to dealing with GIF, PNG, or JPEG files—even formats like TIF and PCX, which are not really suitable for the Internet, are not a problem for TYPO3. These file formats are automatically converted.
Prerequisites
In order to be able to reconstruct the following examples, put a few pictures in the Temp area. This chapter assumes that there is a sub-directory images/ in the Temp directory. The easiest way to upload the graphics is using the Images module. To do this, call the module, click on File Upload in the context menu of images and load at least two graphics on the server (what these graphics look like is of no concern). Normally you can run TYPO3 without any additional software. If you want to be able to edit images, however, you will need two additional software packages. One is the GD library (GDLib), which is an extension for the dynamic creation and manipulation of graphics. GD library is included with every standard installation of PHP and you can get more information on the project page (http://www.boutell. com/gd/). The second piece of software is ImageMagick which is really useful for creating and scaling thumbnail images. You can check with the install tool to see whether the functions for editing pictures are installed. Open the Image Processing section.
Working with Graphics
TYPO3 will let you know whether ImageMagick and GDLib are installed.
In case ImageMagick is not installed, you can find it at
There is also a pre-compiled version available for download at http://typo3. sunsite.dk/software/linux/imagemagick-4.2.9_i386-static-3.tar.gz. Unpack the archive into the designated directory: tar xfvz imagemagick-4.2.9_i386-static-3.tar.gz
If you wish to use a more current version than 4.2.9, you have to modify the file names accordingly. After that, enter the installation path into the Check this path for ImageMagick installation input field in the Basic Configuration area. The installation is just as easy in Windows. Simply follow the directions of the graphic installer. You have to enter the installation path into the input field with Windows as well. Check the two variables [GFX] [in the_path] and [GFX] [in the_path_lzw] to see whether the installation was successful. They both should contain the path to the ImageMagick installation (for the second variable the path may have to be selected manually from the drop-down box). [ 122 ]
Chapter 6
There is now a new project, GraphicsMagick, which has branched out from ImageMagick. In the future it is to distinguish itself with fewer releases, an open development model and a more stabile API. You can get comprehensive information about this at http://www.graphicsmagick.org/. Installation instructions for TYPO3 can be found at http://wiki.typo3.org/index.php/De:Webspace.
Embedding Graphics
It is easy to embed graphics with TypoScript. This is done with the IMAGE object, whose most important property is file. One precondition is that the marker ###IMAGE### has been inserted in the template: page.10.marks { IMAGE = IMAGE IMAGE.file = fileadmin/_temp_/images/logo.jpg }
This syntax is all you need to load the graphic from the specified directory and to create the appropriate HTML code in the back end.
There is one problem with this syntax: The alt and title attributes have no value. This is easily changed: page.10.marks{ IMAGE = IMAGE IMAGE.file = fileadmin/_temp_/images/logo.jpg IMAGE.altText = Hello, World! IMAGE.titleText = Hello, World! }
This assigns an appropriate value to title and alt. There is also the archaic value alttext, but it should only be used if altText doesn't have a value.
Modifying Graphics
A glance at the source text illustrates that the well-known attributes of the tag, such as width, height, etc. are set automatically. In other words, TYPO3 displays the embedded graphic in its original size. This can be easily changed.
[ 123 ]
Working with Graphics
Changing the Graphic Size
You can change the size of a graphic as desired by changing the file.width property of the IMAGE object. TYPO3 then creates this graphic afresh on the server, while the original graphic remains intact in the specified directory. The newly created graphic is stored in the typo3.temp/pics/ directory and loaded from there. IMAGE.file.width = 300 IMAGE.file.height = 200
You can see in the source text that the graphic is no longer being loaded from the specified fileadmin/_temp_/images/logo.jpg directory, but automatically from typo3.temp/pics/. TYPO3 did not even use the original file name. The typo3.temp/pics/ directory will soon be storage intensive. Every time the size of an image is changed, TYPO3 creates a new graphic in this directory, and the older graphics are not deleted. This will result in an enormous amount of data over the course of time. If you have limited storage space, you should clean out the pics directory regularly. To avoid problems, the page cache also has to be deleted, since it will still contain references to the deleted graphics. Details about the TYPO3 cache and how to delete it can be found in the Caching section of this chapter.
Creating Graphics Dynamically
The normal integration of graphics is only one of the options and is nothing spectacular. After all, you would not need TypoScript for this, the graphics could be integrated into the design template with completely normal HTML code. TYPO3 really becomes a powerful graphics tool when GIFBUILDER comes into play. This tool allows graphics to be defined and created on the server. If you want, you can insert a graphic and dynamically overlay it with text. GIFBUILDER gives the path to the created graphic as the return value. Knowledge of graphics editing programs like Photoshop is helpful when creating graphics with TypoScript, because here as well levels, positioning, etc. play a decisive role. To get a feel for graphics creation, take a look at a simple example utilizing GIFBUILDER: page.20 = IMAGE page.20.file = GIFBUILDER page.20.file { XY = 200,300 10 = IMAGE 10.file = fileadmin/_temp_/logo.gif 10.file.width = 200 20 = TEXT 20.text.field = title 20.offset = 20, 50 [ 124 ]
The following table contains the elements of this example and describes their meaning: Statement
Description
page.20 = IMAGE
A new IMAGE object is created at position 20.
page.20.file = GIFBUILDER
The GIFBUILDER object is assigned to the file property.
XY = 200,300
A width of 200 and a height of 300 pixels are specified for the graphic.
10.file = fileadmin/_temp_/ logo.gif
Integrates a graphic from the fileadmin/_temp_ directory.
10.file.width = 200
Specifies the size of the integrated graphic logo.jpg.
20 = TEXT
Creates a new TEXT object at position 20
20.text.field = title
The content of the database field title is specified as the value of the TEXT object. The page title is read from this field.
20.offset = 20, 50
Defines the position of the text field.
20.fontFile = fileadmin/fonts/ verdana.ttf
Specifies the font to be used for the text field.
20.fontSize = 20
Specifies a font size of 20 for the text field.
What does this syntax do? A graphic is defined as the background image and the current page title is dynamically placed on top of it.
GIFBUILDER
GIFBUILDER is the critical tool for the creation and manipulation of TYPO3 graphics. In the next chapter you will work with GIFBUILDER to create graphical menus.
The following table provides an overview of GIFBUILDER objects: Object ADJUST
Description
BOX
Defines a rectangle precisely as to color, size, etc.
CROP
This makes it possible to reduce the display of an image to a partial area of the image.
EFFECT
The specified image can be rotated, colors can be reversed, etc.
EMBOSS
With this you can create a relief effect for the TEXT object.
Tonal value corrections can be applied to the image with this.
[ 125 ]
Working with Graphics
Object IMAGE
Description
OUTLINE
Creates an outline around a TEXT object. This object should not be used; use SHADOW instead.
SCALE
The image is scaled to the specified size with width and height.
SHADOW
Creates a shadow. If it stands alone, the TEXT object that this applies to must be indicated by the textObjNum property.
TEXT
Generates a graphic from a text. It can then be selected by the getText and stdWrap datatypes.
WORKAREA
Defines a new work area.
This GIFBUILDER object can either reference an image or be used as a GIFBUILDER function.
So much for the various GIFBUILDER objects. Some of them will be described in greater detail later in this chapter. But next we will take a look at the various properties of GIFBUILDER: Property 1,2,3...10,20,30....
Description
backColor
Defines the background color of the graphic.
format
Specifies the format of the graphic to be created. Permitted values are GIF and JPG. GIF is the default value.
maxHeight
Specifies the maximum height of the graphic. This is only meaningful in the context of the dynamic calculation of the graphic width.
maxWidth
Specifies the maximum width of the graphic. This is only meaningful in the context of the dynamic calculation of the graphic height.
quality
The quality of JPEG images can be defined with quality. Possible values are between 10 and 100, with 100 being the highest quality.
transparentBackground
Specifies whether the graphic should have a transparent background. If you want the background to be transparent, you must assign the value 1 to this property.
transparentColor
Here you can specify the transparent color. Permitted values are HTML colors, color names, and RGB statements.
XY
Specifies the size of the graphic. You can enter either fixed pixel sizes or dynamically calculated sizes.
The graphics are made up of several levels, whose sequence you can specify.
[ 126 ]
Chapter 6
The following example illustrates how the properties are applied: page.10 = IMAGE page.10.file = GIFBUILDER page.10.file { XY = [10.w],70 10 = TEXT 10.text.field = title }
The syntax shows how the property XY, which defines the width and the height of the created graphic, is applied. In special cases the graphic width is geared to the text content of the title field.
Levels
Modern graphics programs like Photoshop use levels when creating graphics. With this you can create graphics with multiple layers. For example, a typical graphic consists of a background layer, a text layer, and a logo. The sequence of the layers can be changed at will; the levels are serially numbered for that purpose: Level 10 = Background Level 20 = Text Level 30 = Logo
This syntax reminds us of the previous TypoScript examples: here, too, different layers can be laid on top of each other. The Photoshop example could be reproduced in exactly the same form in TypoScript as well. When working with levels it is important to know that the layer with the lower number is superposed by the layer with the higher number. The following example will show how important the numbering of the levels is: page.10 = IMAGE page.10.file = GIFBUILDER page.10.file { XY = 300,400 backColor = #c0c0c0 10 = BOX 10.dimensions = 20,20,170,200 10.color = #808080 20 = TEXT 20.text = Hello World! 20.offset = 20,90 } [ 127 ]
Working with Graphics
Without going into the precise syntax, you can see that the image consists of several levels: a background level with the color #c0c0c0, a dark grey rectangle with the color #808080, and the text Hello World! The result of this syntax looks like this in the front end:
Admittedly, this is not spectacular. But what would it look like if the numbering of the levels is changed? page.10 = IMAGE page.10.file = GIFBUILDER page.10.file { XY = 300,400 backColor = #c0c0c0 20 = BOX 20.dimensions = 20,20,170,200 20.color = #808080 10 = TEXT 10.text = Hello World! 10.offset = 20,90 }
At first glance this syntax appears identical to the previous one. That this is not the case becomes apparent no later than when this code is displayed in the front end: [ 128 ]
Chapter 6
The text Hello World! has disappeared. The reason for this is that this TEXT level was given a lower number than the dark grey rectangle. A completely different graphic can easily be generated from the same elements. To clarify this once again: the layout of the levels has nothing to do with the order in which they are entered inside of Setup. This can also be seen from the following example: Version 1
Although the sequence of the levels has been changed between the two examples, the result is the same. Only the numbering of the levels is important. For greater clarity, however, the levels should be listed in the correct order (10,20,30...). [ 129 ]
Working with Graphics
Positioning Levels
The sequence of levels is just one aspect. Other important points are the level size and the positioning of the level; the offset property of each level is responsible for the latter. The first value to be entered is the desired horizontal offset from the left margin. The vertical offset is determined by the second parameter. An example of this is: page.10 = IMAGE page.10.file = GIFBUILDER page.10.file { XY = 300,400 backColor = #c0c0c0 10 = BOX 10.dimensions = 20,20,170,200 10.color = #808080 20 = TEXT 20.text = Hello World! 20.offset = 100,90 }
In this example, the TEXT level is shifted 100 pixels to the right and 90 pixels downwards. To shift the layer to the left or upwards, you have to use negative values.
Drawing Boxes
We have already used a powerful tool for creating graphics several times in this chapter: you can draw rectangles using the BOX object. If you now want to put some text in the rectangles, you can do this easily, as the following example shows: page.10 = IMAGE page.10.file = GIFBUILDER page.10.file { XY = 300,400 backColor = #c0c0c0 10 = BOX 10.dimensions = 20,20,170,200 10.color = #808080 20 = TEXT 20.text = Hello World! 20.offset = 20,90 30 = TEXT 30.text = Hello, GIFBUILDER! 30.offset = 50,19 }
[ 130 ]
Chapter 6
Normal levels are once again superposed on one another. The interesting thing, however, is the BOX object that creates a rectangle. You can see this new rectangle within the page.10.file square created by GIFBUILDER:
With dimension you can define the position and size of the BOX rectangle. The first two values define the position from the left upper margin. The size of the rectangle is defined by the last two values. In this example, the rectangle is 170 pixels wide and 200 pixels high. The color of the rectangle is specified using color.
Graphical Text
Until now we have often used a TEXT object using which totally normal text can be displayed in the front end. TypoScript also has another TEXT object available with which text can be placed on a graphic. This is completely different from the TEXT object discussed so far—text was treated in such a way that it was output to the front end marked with HTML code. The TEXT object shown here, which is actually a GIFBUILDER object, acts completely differently. With this object texts can easily be formatted as graphics or laid on other graphics. To make this creation of text as graphics possible, several diverse properties have to be assigned to the TEXT object. These include font, font size, and font color, among others. The following table provides an overview of the most important properties: [ 131 ]
Working with Graphics
Property align
Description
angle
Allows the text to be rotated. The value must lie between -90 and 90.
antiAlias
Switches the FreeType anti-aliasing on or off. This function is enabled by default. The property cannot be set if niceText is enabled.
doNotStripHTML
If this property is set to 1, HTML tags are removed, which is not otherwise the case.
emboss
A relief effect can be achieved with this. The emboss property has numerous sub-properties. These are shown in the Relief sections.
fontColor
Specifies the font color. HTML color names as well as RGB and hexadecimal values can be used.
fontFile
Specifies the font file. The name and the path of the TTF file to be used have to be specified.
fontSize
Specifies the font size. The size must be specified in points.
iterations
This is another version for displaying text in bold. The larger the number, the more often the text is superposed and the thicker it appears.
maxWidth
Defines the maximum permissible width of the text. You must, however, be careful when making this entry: if the text is too long due to the specified font size, it is automatically shrunk until it is no larger than the maximum indicated width.
niceText
This will give the text a soft effect.
offset
Determines the text position. The first value determines the distance from the left margin and the second value the distance from the right margin.
shadow
Assigns a shadow to the text. The shadow property has a number of sub-properties, which are presented under Shadows.
text
The text to be displayed is typed here.
textMaxLength
Specifies the maximum width of the text in number of characters.
wordSpacing
Defines the spacing between words.
Determines the horizontal orientation of the text.
You have seen how extensive the formatting options are. Let's demonstrate the use of the TEXT objects in combination with a few properties in a simple example. page.10 = IMAGE page.10.file = GIFBUILDER [ 132 ]
Chapter 6 page.10.file { XY = 300,400 backColor = #c0c0c0 20 = TEXT 20.text.field = title 20.fontSize = 20 20.fontColor = red 20.wordSpacing = 40 20.offset = 50,119 }
The source text in detail: the page title of the current page is selected from the database with text.field = title. This text is displayed in 20 point size by fontSize = 20. The font color has been specified as red and the word spacing as 40. With offset the text is positioned 50 points from the left margin and 119 points from the top margin.
This figure illustrates the effect of the syntax. This is only a very simple example, which makes use of base formatting, i.e. the most commonly used properties. We will introduce some of the less-used properties in the next few pages.
Anti-Aliasing with niceText
The FreeType library used by GDLib does not adequately support so-called anti-aliasing in all of its versions. With the niceText property, this effect can be replicated for smaller letters. Before using niceText, however, you have to be aware that it requires more computing power when generating graphics on the server. [ 133 ]
Working with Graphics
What does anti-aliasing do? Putting it simply, it gives you a more harmonious, softer font. This is achieved by evening out step transitions or edges. You have seen text where no anti-aliasing has been used. Such text looks unclean and has sharp edges. Whether anti-aliasing should be used or not is difficult to say. Although the advantages of smoothened edges and the elimination of pixel flicker cannot be overlooked, the text becomes less sharply defined. The niceText property is always recommended when there is writing inside of graphics. The principle behind niceText is quite simple: the text is rendered in double size on a mask which is then scaled down to the original size using ImageMagick. The weakness lies in the fact that ImageMagick produces different results depending on the version. So test it for yourself and decide whether niceText is for you. Due to the higher load on the server niceText should be used only where the effect is absolutely necessary. page.10 = IMAGE page.10.file = GIFBUILDER page.10.file { XY = 300,400 backColor = #c0c0c0 20 = TEXT 20.text.field = title 20.fontSize = 30 20.fontColor = black 20.offset = 50,30 30 = TEXT 30.text.field = title 30.fontSize = 30 30.fontColor = black 30.nicetext = 1 30.offset = 50,70 }
Anti-aliasing is enabled by the value 1. The default value is 0. If you do not want to use anti-aliasing, niceText does not have to be set. The figure shows two blocks of text, with the top one created without and the lower one with anti-aliasing.
[ 134 ]
Chapter 6
This example clearly demonstrates the difference between normal text (above) and nicetext. As already mentioned, the strength or actual conspicuity of the desired effect depends on the version of ImageMagick that you use.
Advanced Options
You now know the framework for creating graphics with TypoScript. On the following pages we will present a few somewhat more complex methods that you can use to achieve interesting effects.
Shadows
With the shadow property you can add a shadow to the font. Although this effect should not be used for continuous text as it affects legibility, it could definitely be used for headings and single words with interesting effect. The following table lists the sub-properties of shadow. Property blur
Description
color
Defines the color of the shadow.
intensity
Determines the intensity of the shadow. Permitted values are from 0 to 100.
offset
Determines the position of the shadow.
opacity
Specifies the opacity with which the shadow is to be drawn. Permitted values are from 0 to 100.
Specifies the intensity of the blur. Values between 1 and 99 are allowed. Above 40 you have to jump the value by tens.
[ 135 ]
Working with Graphics
As you can see, the definition of a shadow can be quite extensive. The following syntax clarifies this impression some more: page.10 = IMAGE page.10.file = GIFBUILDER page.10.file { XY = 300,400 backColor = #c0c0c0 20 = TEXT 20.text = Hello World! 20.offset = 10,45 20.fontFile = fileadmin/pala.ttf 20.fontSize= 20 20.fontColor = #000000 20.shadow.offset = 2,14 20.shadow.blur = 60 20.shadow.opacity = 2 }
In this example the character string Hello World! is shown with a shadow. Let us look at the source text in detail: Sub-property
Description
shadow.offset = 2,4
Specifies the position of the shadow at 2 pixels from the left and 4 pixels from the top.
shadow.blur = 60
Specifies that a blur with the medium strength of 60 will be used.
shadow.opacity = 40
The opacity of the shadow is set at 40 percent.
Relief
The emboss property can be looked at in the same context as the previously discussed shadow property with the difference that emboss goes one step further. This effect consist of two shadows that run in opposite directions and thus create a relief effect. The emboss object has the following properties: Property blur
Description
highColor
Defines the color of the top border. Color names, hexadecimal values and RGB values are permitted.
intensity
Determines the relief intensity. The permitted values are from 1 to 100.
Specifies the blur effect for highlighting.
[ 136 ]
Chapter 6
Property lowColor
Description
offset
Determines the position of the relief.
opacity
Specifies the opacity of the relief. The permitted values are from 0 to 100.
Defines the color of the bottom border. Color names, hexadecimal values, and RGB values are permitted.
Another simple example, but using all the properties: page.10 = IMAGE page.10.file = GIFBUILDER page.10.file { XY = 300,400 backColor = #c0c0c0 20 = TEXT 20.text = Hello World! 20.offset = 10,25 20.fontSize= 20 20.fontColor = #000000 20.fontFile = fileadmin/pala.ttf 20.emboss.offset = 1,1 20.emboss.lowColor = #ffffff 20.emboss.highColor = #000000 20.emboss.blur = 40 20.emboss.opacity = 60 }
Showing the Page Title as a Graphic The title of the current page can be easily displayed as a graphic. [ 137 ]
Working with Graphics
In order to execute this type of graphic, first the current title must be imported. You do that with field and by defining the title field. This causes the content of the title field to be imported. After the page title has been defined, it has to be output as a graphic: page.10.marks.IMAGE = IMAGE page.10.marks.IMAGE { wrap = | file = GIFBUILDER file { XY = 140,[20.h]+80 backColor = #cccccc 20 = TEXT 20 { case = upper angle = 90 text.field = title fontSize = 40,30 fontFile = fileadmin/pala.ttf fontColor = #000000 offset = 100,[20.h]+40 } } }
A special feature is that the title does not appear in the normal horizontal aspect but is rotated by 90 degrees. If you don't want this, simply omit the angle property.
Importing Graphics from the Database
This dynamic display of the page title is by far not the only alternative for static graphics. With file.import, for example, you can transfer graphics from a directory. The expected value is the directory in which the graphic that you want to display is located. So, you no longer have to specify the graphic to be displayed for each and every page individually. An example is: page.20 = IMAGE page.20.file = GIFBUILDER page.20.file { import = uploads/media/ import = field = media import.listNum = 0 width = 400 offset = 10,80 } [ 138 ]
Chapter 6
With import = uploads/media/ you specify that the graphic to be displayed is located in the directory uploads/media/. Which graphics are ultimately used for the current page can be specified with field = media. If several graphics have been assigned to a page, the media field gets a comma-separated list. With listNum = zero you can then specify that the first element should be used. Although this version works quite well, there is still a problem: every page has to be defined explicitly as Extended and then a picture has to be added. This is the case even if the same picture that is used on a higher-level page is being used here. It would be better to go through the specified directory recursively. This would ensure that a graphic appears on the sub-pages when needed even if no image has been added. page.20 = IMAGE page.20.file = GIFBUILDER page.20.file { import = uploads/media/ import.data = levelmedia:-1, slide import.listNum = 0 width = 400 offset = 10,80 }
This can be achieved with levelmedia:-1, slide. The value that is set for levelmedia depends on the page structure. It would also be possible, for example, to set levelmedia:2 or levelmedia:-2.
Caching
TYPO3 offers a caching mechanism. A glance at the operating mode of CM systems tells you how important this is. Except for static pages, most CMSs generate their contents from a database. With a high number of visitors, the page slows down considerably. To prevent this, the page is put into an intermediate storage position in the form of HTML code. If visitors call the page again, it is not composed afresh from the individual components of the database—the page already generated is displayed from the cache. TYPO3 undertakes the caching of pages itself. But as soon as changes are made in the page, the cache is automatically deleted.
[ 139 ]
Working with Graphics
What is Cached in TYPO3
Configuration settings, the HTML output of static pages, and picture sizes are the main items cached in TYPO3. Extensions also make use of the caching function in order to maximize output speed. Some elements do not use the cache even though it is commonly assumed that they do. Among these are pictures created on the server. Now that we have established what is being cached, the question of where the cached data can be found comes up. The pages that are displayed in the front end are cached in the two tables cache_pages and cache_hash. But when we look into the TYPO3 database structure, we can see that there are additional cache tables that have a lesser function (cache_imagesize for instance, contains the file names of used graphics and their dimensions).
Emptying the Cache
Although the automatic deletion feature of the cache does function, you should periodically empty the cache manually. There are various methods available for this: You have the option of manually deleting the cache from the back end.
What are the functions behind these two links? •
Clear cache in typo3conf/: Deletes all of the collected configurations of the two extension files ext_tables.php and ext_localconf.php.
•
Clear FE cache: Deletes the stored HTML output from the databank. In addition the template cache is emptied.
Sometimes even this does not help. Thus for example, there always seem to be problems with the caching of graphics. When this is the case you should manually delete the typo3temp directory. Subsequently the TYPO3 cache must be deleted, as otherwise the HTML code refers to graphics that no longer exist. You don't always have to delete the entire cache. Individual pages can be handled separately. The ADVANCED FUNCTIONS drop-down list is available at the end of each page in the Page view for this purpose. [ 140 ]
Chapter 6
If you want to learn more about caching, go to Info in the Web module, select the Pagetree overview and check the Cache and Age entry. Here you can specify how long the cache will be saved.
Click on the respective page in the page title column and set up the cache values. You can also use config to empty the cache at midnight every night. This is then executed by the cache_clearAtMidnight property. cache_clearAtMidnight = 1
You can also set the duration of the cache in seconds. config.cache_period = 86400
In this example, the cache is saved for 24 hours. There is even a solution for those that do not want to use any cache: With no cache enabled, the cache is not used at all. no_cache = true
You should make use of this property only in an emergency, since this severely affects the performance of the server, slowing down page generation completely. This property can be used during development as it saves the time you would spend manually deleting the caches.
[ 141 ]
Working with Graphics
Summary
This chapter discusses graphics processing in TypoScript. We discussed embedding and modifying the size of graphics using the IMAGE object. Next we looked at creating graphics dynamically using the GIFBUILDER tool. Using this tool you can create and position levels, draw boxes, create text as graphics, and enable antialiasing using the niceText property. We then discussed the advanced graphical options available in TYPO3, such as creating shadows, embossing, and showing text as a graphic. The chapter wound up with a discussion on caching in TypoScript.
[ 142 ]
Menus The previous chapter illustrated the options for creating graphics in TYPO3. Let us now use this knowledge to create menus. Menu creation is the one of the most powerful functions of TYPO3. Text or graphical menus, TYPO3 can do it all. The page tree that reflects the web page structure serves as the starting point for menus. Page names and their hierarchy are automatically imported from this page tree and the menu is generated based on that information. You are even given options for when you don't want one of the pages from the page tree to appear in the menu. These will be discussed in the course of this chapter.
Available Menu Types
If you believe that only the simplest menus can be created in TYPO3, you are mistaken. In the following sections you will learn how to create all of the possible menu types, what to watch for, and what else is possible. •
Text menus: Text-based menus can be created with TMENU. This is the simplest type of menu consisting of a combination of text and CSS.
•
Graphical menus: With GMENU, an image is generated from each entry of the page tree, which then constitutes a menu item. The options that TYPO3 offers, in particular with regard to graphical menus, are unique. Graphical menus can be created easily without having to create the images first in a graphics program.
•
JavaScript menus: JavaScript-based menus are created with JSMENU. The user can call the desired page from a drop-down list.
•
Layer menus: You can generate layer-based menus with TMENU_LAYERS. The uniqueness with these is that the menu items unfold: when you point to a menu layer, the subsidiary layer is automatically displayed. If you have already programmed this type of a menu yourself, you know how
Menus
error-������������������������������������������������������������������� prone this can be, particularly with regard to its ability to work properly in different browsers. TYPO3 handles all of this for you. Menus of the GMENU_LAYERS type are created in a similar fashion to TMENU_LAYERS, but the menu items are graphics instead of text.
Hello Menu!
To give you a feel of how easy it is to create menus, we begin this chapter with a typical example. For this, create the following file in the by now familiar fileadmin/_temp directory and call it hello.htm: Working on menus
Only the ###MENU### marker was created with this code. The illustrated file forms the basis for all other examples in this chapter. The following TypoScript code, when inserted into the Setup of the root page, creates simple text navigation from the familiar page structure: temp.mainTemplate = TEMPLATE temp.mainTemplate { template = FILE template.file = fileadmin/_temp_/hello.htm } page = PAGE page.typeNum = 0 page.stylesheet = fileadmin/_temp_/css/css.css page.10 < temp.mainTemplate page.10.workOnSubpart = BODY_CONTENT page.10.marks.MENU = HMENU page.10.marks.MENU.1 = TMENU page.10.marks.MENU.1.NO { before = after = | |*| | |*| } [ 144 ]
Chapter 7
The exact syntax will be discussed later; at this point let's focus on the simplicity of menu creation. Only six lines were required to display the page structure with the following menu in the front end:
Admittedly, the navigation is not very pretty, but you can transform it into an attractive menu with stylesheets. And it is every bit as easy to create a graphical menu.
Specifying Menu Properties
Everything related to menus in TypoScript is linked to the HMENU (hierarchical menu) content object. It doesn't matter which menu is being used. HMENU assembles the formation of the pages. The rendering of the menu entries, on the other hand, is handled by sub-objects, which are contained in a numerical list. You will learn more about this numbering and the related entryLevel property later. Now let's investigate the ways in which menus can be presented.
Defining States
You have been introduced to the various menu types. Various menu states can be defined for each of these versions. The principle behind this is as simple as it is clever: first the type of menu is specified and then a specific state is defined for individual menu elements. This procedure is made possible by the fact that each menu element consists of a single entry from the navigation. One typical menu state is rollover, which you might also know by the name of mouse-over. This defines the look of the menu element when you point to it with your mouse. But rollover is not the only state. The options that TYPO3 offers in this arena are described in the following table:
[ 145 ]
Menus
State ACT
Description
CUR
This is the menu item with the currently opened page.
IFSUB
This is where the configuration is done for menu elements with subsidiary pages.
NO
This describes the normal state of a menu element.
RO
Rollover menus are created with this.
SPC
This defines the appearance of spacing. You will need this if pages of the Spacing type are created within the navigation. The SPC state is then applied to these pages.
USR
This state comes into play when a user restriction has been specified for a page.
This defines all menu items that have the current page as their subsidiary.
The defined conditions cannot, however, be viewed on static pages. In certain situations it may be necessary to combine different states. The states ACTRO, CORRO, IFSUBCUR, and IFSUBPRO exist for those situations.
Defining the Starting Point of a Menu
When defining a menu the question naturally arises as to which position in the page tree is the starting point for the menu items to be created. The special property of the HMENU object is designed for this; it receives the ID of the relevant page as its value. But how does one get the ID? To find out, place the mouse cursor on the relevant page's icon in the page tree.
The ID is then displayed in a tool tip. The ID in the example shown is 1 and can be passed on to the special property: page.10.marks.MENU = HMENU page.10.marks.MENU.special = directory page.10.marks.MENU.special.value = 1 page.10.marks.MENU.1 = TMENU [ 146 ]
Chapter 7 page.10.marks.MENU.1.NO { before = after = | |*| }
|
|*|
You then use directory to specify that this is a standard menu consisting of only particular pages. The starting point of the menu is in the page with ID 1.
Specifying Menu Types
Apart from directory there are other values that can also be assigned to the special property and with them you can define the type of menu more precisely. There is more information about these special menus later in this chapter. •
directory: With directory you generate a menu that consists of only
•
list: Works in a manner similar to directory; the difference, however, is that the menu is generated from the page list that is specified by special. value. The sub-pages are not taken into account with this.
•
updated: You can create menus of the most recently updated pages with this
specific pages. We have already shown you how to do this.
This example generates a menu containing the pages that were last modified. You can specify the areas of the page tree from which these pages are selected with the value property. You can also specify several IDs; in this case you must separate the individual IDs with commas. •
mode: With this you can define how the age of the page is determined. There are many options for this; the most frequently used one, however, is tstamp,
using the tstamp field of the Content table. This field is defined automatically in the database when an entry is changed.
[ 147 ]
Menus
•
maxAge: This lets you specify the maximum age of the pages. In the example,
•
rootline: This lets you implement click-paths or breadcrumb menus. A
•
keywords: With this, pages containing specific words can be included in the menu. You have to define a list of these words with setKeywords (you can
it is 7 days. The maximum number of menu entries can be defined with limit in order to avoid the menu becoming overly cluttered. This type of menu can become very bulky and thus cluttered if a lot of pages have been modified recently. Avoid these problems by limiting the number of entries.
detailed description of this version can be found in the Special Menus section in this chapter.
also specify a page containing the key words).
Defining the Entry Level
The entryLevel property of the HMENU object allows you to determine the entry level for the menu. With entryLevel = 0, a menu that consists of the first pages of the website is generated. This is the default setting. If you want to display the pages of the second menu level, you have to set entryLevel = 1. Now the page titles of all of the pages of the second level that belong to the currently selected menu item of the first level are used. On the other hand, if the value is set to -1, the entries of the topmost levels are used.
Specifying the First Menu Entry
You surely do not always want to display all of the menu entries. The begin property is designed for this purpose. Indicate an integer that defines the starting point of the menu. page.10.marks.MENU = HMENU page.10.marks.MENU.begin = 3 page.10.marks.MENU.1 = TMENU page.10.marks.MENU.1.NO{ before = after = | |*| }
|
|*|
This code ensures that the first two items of the menu are skipped and the third entry is displayed. Be aware that this also affects the sub-menus! The entryLevel property acquires a special significance in the context of additional menu levels.
[ 148 ]
Chapter 7
Specifying the Number of Menu Entries
You can easily specify the minimum and maximum number of menu entries to be displayed. The minimum number of entries is specified with minItems. If the tree structure does not reflect the number given here, blank entries looking like . ".." are created; these are linked to the current page. The maximum number of entries that can be displayed in the menu is specified with maxItems: page.10.marks.MENU = HMENU page.10.marks.MENU.minItems = 6 page.10.marks.MENU.maxItems = 8 page.10.marks.MENU.1 = TMENU page.10.marks.MENU.1.wrap =
|
page.10.marks.MENU.1.NO { before = after = | |*| | |*| }
In this example the menu must have at least 6 but may not have more than 8 entries.
Excluding Menu Items
Use the excludeUidList property if you want one or more entries to not appear in the menu. The value expected is a comma-separated list of page UIDs. page.10.marks.MENU = HMENU page.10.marks.MENU.excludeUidList = 10,8 page.10.marks.MENU.1 = TMENU page.10.marks.MENU.1.wrap =
|
page.10.marks.MENU.1.NO { before = after = | |*| | |*| }
This syntax ensures that pages with the UIDs 10 and 8 do not appear in the menu.
Text Menus
The simplest type of menu is the text menu (even though the other menus are not any more difficult to create). TMENU creates a text-based menu from the page tree and the page titles defined there. The advantage of these menus lies in their speed. Although the graphical menus created by TYPO3 are relatively quick, they are noticeably slower than text menus.
[ 149 ]
Menus
TMENU is specified below HMENU as can be seen from the following example: page.10.marks.MENU = HMENU page.10.marks.MENU.1 = TMENU page.10.marks.MENU.1.NO { linkWrap = | }
This is the syntax that you use to create a text menu. There is a line break after each entry. This is done with linkWrap, using which the menu entries that are included using the tag are enclosed within the stated tags. With NO you can define the behavior of the NO state; i.e. the normal state. This results in the following text in the front end (reduced to one entry): Homepage
Properties of Text Menus
At the beginning of this chapter, the possible states for menus such as CUR and RO were described. Various properties can be assigned to each of these states. These are: Property after
Description
AtagParams
Additional attributes such as class and style can be defined for the tag.
allWrap
Encloses the entire menu entry.
before
Determines what will be displayed before the menu entry.
beforeImg
This specifies an image that will be displayed before the menu entry.
beforeROImg
Specifies the image to be displayed at the time of a rollover. For this, the RO property must be set to 1.
beforeWrap
Encloses the before code.
linkWrap
Encloses the tag of the menu entries.
Determines what will be displayed after the menu entry.
These properties can be combined with each other at will. Here is an example of this: page.10.marks.MENU = HMENU page.10.marks.MENU.1 = TMENU page.10.marks.MENU.1.NO { linkWrap = | beforeImg = fileadmin/_temp_/images/minus.gif AtagParams = } [ 150 ]
Chapter 7
This code creates a simple text menu. You can specify the image to be displayed before the individual menu entries with beforeImg. The image is, however, not linked using beforeImg. If you want to do this, you must set beforeImgLink = 1. With AtagParams you assign the class attribute with the value of the news CSS class to the tag.
Defining Sub-Menus
Menus, of course, do not usually consist of only one level. Even the menu for the page tree, which forms the basis of all the examples so far, has two levels. These can be created quite easily: page.10.marks.MENU = HMENU page.10.marks.MENU.1 = TMENU page.10.marks.MENU.1 { expAll = 1 NO.allWrap = | } page.10.marks.MENU.2 = TMENU page.10.marks.MENU.2.NO { allWrap = | }
The menu of the first level is created with page.10.marks.MENU.1. In this example it is important to indicate within this definition that the entries of the second menu level are to be expanded. This is achieved with the expAll=1 property. With allWrap you decide that the entire tag is to be enclosed within the tag. The second menu level is defined with page.10.marks.MENU.2. To display these menu entries in italics use the tag.
Using Stylesheets
Stylesheets are normally defined using the design template. There is another option, however, and that is of assigning suitable CSS definitions to the menu elements later. The briefly mentioned AtagParams property is available for this, using which you take direct appropriate action in the tag. AtagParams =
This example assigns the CSS class news to the tag.
[ 151 ]
Menus
The following example illustrates how effective the use of style sheets can be: A two-tone menu is created and the last menu entry is displayed in a dark color. In order to realize this menu in real-life, you need a CSS file that defines the three classes of light, dark, and last. page.10.marks.MENU = HMENU page.10.marks.MENU = TMENU page.10.marks.MENU.1.NO { allWrap = <span >| |*| <span >|||<span >||*| allWrap.override.cObject=COA allWrap.override.cObject{ if.equals.data=register:count_HMENU_MENUOBJ if.value.data=register:count_menuItems 10=TEXT 10{ value=<span >| if.isFalse.prioriCalc=1 if.isFalse.cObject=TEXT if.isFalse.cObject.insertData=1 if.isFalse.cObject.value={register:count_HMENU_MENUOBJ}%2 } 20| } }
Spacing between the Menu Items
The individual menu entries are very closely spaced by default. In the examples so far, however, care was taken to ensure that this situation does not occur. For this (but not only for this) purpose we have the linkWrap property using which each menu entry can be enclosed within HTML code, and this gives us the opportunity to force a space ( ) before each entry. The wrap symbol | is used for this. page.10.marks.MENU = HMENU page.10.marks.MENU.1 = TMENU page.10.marks.MENU.1 { NO.linkWrap = | }
This syntax places a space before each menu entry. If you want a space both before and after the entry, change the syntax as follows: NO.linkWrap = | [ 152 ]
Chapter 7
Revert to the before and after properties for more elaborate formatting and spacing definitions. The next section, for example, explains how lines are displayed between the menu entries.
OptionSplit: Adding Vertical Lines
Vertical dashes are often used to demarcate the individual menu items. The easiest way to do this is with the linkWrap property. But there is a problem with this: the vertical line is used as the pipe symbol in TypoScript to mark the position that is to be enclosed. Therefore the vertical line cannot be used directly; the ASCII code of the line must be used instead. That is | and can be typed just like this. NO.linkWrap= | |
This syntax first inserts a space followed by the menu entry and another space before the vertical dash is inserted. You can see this for yourself:
The desired result has been achieved and you can see a vertical line between each of the menu entries. This version has one unfortunate shortcoming: since the vertical line is inserted after each menu entry, it is naturally also inserted after the last menu entry. This problem can only be solved by the so-called optionSplit. With optionSplit, it is possible to segregate objects such as menus into separate areas. An example: linkWrap = [First element] |*| [Middle elements] |*| [Last element]
This is the general syntax for optionSplit. The individual areas are separated by |*|. But not only this rough division is possible; you can be more precise: linkWrap = [First element] [Second element |*| [Middle elements] |*| [Second-last Element] [Last element]
What does this segregation do? You can assign arbitrary elements to each of these individual elements. The problem with the unwanted vertical dash that was displayed after the last menu entry can be solved with optionSplit in the following manner: linkWrap= | | |*| | | |*| | [ 153 ]
Menus
The characters | | are assigned to the first menu element. This means that a space is displayed before the menu entry and a space followed by a vertical dash is displayed after. The menu elements in between also have | * | | | assigned to them. Since no vertical dash is to be shown after the last menu entry, type | at the end. This displays a space before the entry, but nothing else after the entry.
As you can see, the vertical line after the last entry has disappeared.
Menus and Tables
The formatting of menus is, of course, a matter of taste. While some swear by CSS, others favor tables. The CSS version is very simple: you only have to assign a CSS class or ID to the menu entry. You can then format the menu with the appropriate CSS statements. However, menu formatting is different if you use tables. The following example gives you a framework that can easily be modified for a variety of menus. First the template file: working with menus [ 154 ]
Chapter 7
The ###MENU### marker that will later be replaced by the actual menu is defined within the template. When creating the design template, it is important that the marker is positioned within a
tag. In the next step you will create a simple menu: page.10.marks.MENU= HMENU page.10.marks.MENU.entryLevel = 0 page.10.marks.MENU.1 = TMENU page.10.marks.MENU.1.NO { allWrap =
The values shown inside the selection list are generated by {field:title}, i.e. the respective page title.
JavaScript Menus
You can generate JavaScript-controlled menus with the JSMENU object. These very easily generate various list boxes with various contents.
In this example, the main categories are shown in the left drop-down list box. If you pick one of them, the corresponding sub-pages appear in the left drop-down box. The code responsible for this is as follows: page.10.marks.MENU = HMENU page.10.marks.MENU.entryLevel = .1 2.firstLabel = Sub-menu } }
You can now select the entry level for the menu using the already familiar entryLevel property. Now to the actual JSMENU; with levels, you can define the number of levels to be displayed. The value that is defined here determines the number of drop-down lists the menu will consist of. A JSMENU can have a maximum of five levels. Next you define the individual menu levels. And showActive determines whether the menu level pertaining to a page should be activated immediately when a page is called. The first label in the menu is defined via firstLabel. If this property is not set, the first menu entry remains blank.
Calling Pages from the Menu
With the help of a small trick, a normal TMENU can be turned into a better JSMENU to allow you to call the desired pages. The principle behind this is extremely simple: the moment a menu entry is selected, the relevant page is displayed in the browser. First the script: <script type="text/JavaScript">
Save the script by the name of script.js in the fileadmin/_temp_ directory.
[ 157 ]
Menus
In the next step you have to ensure that the script is available in the front end. Make the appropriate changes in the template for this: page.headerData.5 = TEXT page.headerData.5.value = <script type="text/javascript" src="fileadmin/_temp_/script.js" language="JavaScript">
In the last step, you customize the menu: page.10.marks.MENU = HMENU page.10.marks.MENU.1.special = directory page.10.marks.MENU.1.special.value = 13 page.10.marks.MENU.1.wrap = <select name="menu" onchange="go('parent',this,0)"> | page.10.marks.MENU.1 = TMENU page.10.marks.MENU.1.NO { doNotLinkIt = 1 before.data = field:uid before.wrap = stdWrap.field = title stdWrap.wrap = |*| | |*| after.wrap = | }
This is a normal menu. To actually call the desired pages, the appropriate value must be assigned to the value attribute of the tag. In this case, import the UID of the corresponding pages with field:uid and transfer it to the id parameter.
Graphical Menus
The options offered by TYPO3 for generating graphics were discussed in detail in Chapter 6. These features are also the foundation for the creation of dynamically generated graphical menus. This, of course, is an enormous advantage over generating graphical menus the normal way. For example, you no longer have to create the images of the individual items manually in a graphics program. The same is true with TYPO3 as with all graphical menus: the loading times are longer than for text menus. If this is not a problem for you, you have a powerful tool in your hand that will make it easy for you to integrate graphical menus into your website.
[ 158 ]
Chapter 7
Creating Menu Items
Graphical menus are created with the GMENU object, which works in a manner similar to TMENU. The properties for defining the respective states, however, come from GIFBUILDER. Let's start with an example based on the familiar page tree: page.10.marks.MENU = HMENU page.10.marks.MENU.1 = GMENU page.10.marks.MENU.1.NO { backColor = #000000 XY = 100, 20 10 = TEXT 10.text.field = title 10.fontColor = #ffffff 10.offset = 4,14 10.fontFile = fileadmin/verdana.ttf 10.fontSize = 11 }
As you can see the size of the source text is a little bit larger than with text menus. This is because graphics are being created here; the syntax, however, is still very clear. Instead of using the ###MENU### marker, a hierarchical menu is inserted with page.10.marks.MENU. With page.10.marks.MENU.1 = GMENU, you specify that the first level is represented by a graphical menu. What this menu looks like in its normal state is defined by page.10.marks. MENU.1.NO. The options mentioned in Chapter 6 can be used within this definition. Property backColor = #000000
Description
XY = 100, 20
Defines the width and height of the menu entries.
10 = TEXT
Creates a text object.
10.text.field = title
Populates the text object with the value of the page title.
10.fontColor = #ffffff
Defines the color of the font (in this case white).
10.offset = 4,14
Specifies the distance of the text from the left upper edge of the image. Here the text is positioned 4 pixels from the left and 14 pixels from the top.
fontFile = fileadmin/ verdana.ttf
Specifies the path to the TrueType font file to be used. If you want to use this syntax in a Linux/Unix environment, you need TTF-support.
fontSize = 11
Specifies the font size.
Specifies the background color (in this case black).
[ 159 ]
Menus
These statements suffice to create a graphical menu. The finished result is definitely usable:
Integrating Sub-Menu Items
In the previous examples, only the first level of the menu was shown. You can, of course, create menus with two levels. Here is an example of this: page.10.marks.MENU.1 = GMENU page.10.marks.MENU.1.expAll = 1 page.10.marks.MENU.1.NO { backColor = #000000 XY = 100, 20 10 = TEXT 10.text.field = title 10.fontColor = #ffffff 10.offset = 4,14 10.fontFile = fileadmin/verdana.ttf 10.fontSize = 11 wrap = | } page.10.marks.MENU.2 = GMENU page.10.marks.MENU.2.NO { backColor = #c0c0c0 XY = 100, 20 10 = TEXT 10.text.field = title 10.fontColor = #ffffff 10.offset = 4,14 10.fontFile = fileadmin/verdana.ttf 10.fontSize = 10 wrap = | }
To ensure that the second levels of the menu items are always visible, use page.10. marks.MENU.1.expAll = 1. The second menu level is then defined similarly to the [ 160 ]
Chapter 7
first. The most important difference is: you have to specify that the second level should be represented by a graphical menu. This is done via page.10.MENU.2 = GMENU. The other properties have already been explained in the previous section. Only their values have been changed in order to be able to distinguish the first from the second level.
Creating Lines
You have learned how to visually separate the individual menu entries in text menus with lines. The same thing can be done in graphical menus. The path leading to the same result is different, but it is not much more complicated. The following syntax inserts a vertical separator line between each pair of menu entries: page.10.marks.MENU = HMENU page.10.marks.MENU.1 = GMENU page.10.marks.MENU.1.NO { backColor = #000000 XY = 100, 20 10 = TEXT 10.text.field = title 10.fontColor = #ffffff 10.offset = 4,14 10.fontFile = fileadmin/verdana.ttf 10.fontSize = 11 20 = IMAGE 20.file = GIFBUILDER 20.file { XY = 1, 20 backColor = #ffffff } 20.offset = 0, 1 }
Calling this from the front end shows that our project has succeeded—a line has actually been added between each pair of entries:
[ 161 ]
Menus
Of course you recognize the principle behind this: this just involves creating a new graphic. Here are the details of the new syntax: Statement
Description
20 = IMAGE
A level 20 is created as an entity of the IMAGE object.
20.file = GIFBUILDER
This specifies that the image is to be created graphically with GIFBUILDER.
XY = 1, 20
Defines the size: a width of 1 pixel and a height of 20 pixels has been defined.
backColor = #ffffff
Sets the background color to white.
20.offset = 0, 1
Finally, an offset from the top left corner is specified for level 20.
This version is good enough for most applications. Things become difficult for horizontal menus in which a graphic is to be displayed above the first menu item. The syntax we just used does not do the job in this case. There are, however, other ways of overcoming this problem. In the simplest case, you add a static white line to the design template. In the second version, a line is added with wrap. The pre-condition for this, of course, is that the line exists as a graphic. 1x1 pixel graphics are best suited for this purpose. These can be formatted to the desired size simply by changing the width and height attributes. The following syntax is all it takes to integrate a static line into the menu: wrap = |
Automatically Customizing the Menu Width
If a menu item is too wide, it is cut off by default when the end of the menu is reached. This, of course, is not acceptable. There are various ways of dealing with this problem: if you are working with a fixed menu width, it is recommended that long menu entries be trimmed to the right width with a line break. You will see how this works in the next section. If the width of the menu does not matter, one can automatically adjust it to the width of the menu entries. An example is: page.10.marks.MENU = HMENU page.10.marks.MENU.1 = GMENU page.10.marks.MENU.1.NO { backColor = #aaaaaa XY = [10.w]+10, 20 [ 162 ]
The crucial part of this syntax is the XY = [10.w]+10, 20 array. It specified how the new dimensions of the menu entries are calculated from the width of the text object at position 10. An additional 10 pixels are added to this value. This version works very well but has one drawback, which you will notice after taking a look at the following illustration:
Because the page background is white in this example and the menu background is grey, we get this visually unacceptable figure. The simplest solution is to adjust the background color of the menu to that of the page. This has the disadvantage, however, that the menu doesn't stand out as impressively from the rest of the page as it did before. For that reason, it may make sense to define a background graphic for such menus. It could look like this for the current example: 5 = IMAGE 5.file = fileadmin/_temp_/background.gif
Now the background.gif graphic is displayed as a background image in the menu. There is more about the subject of background images in menus in the next section.
[ 163 ]
Menus
Adding Background Graphics
The integration of background images into menus is a type of formatting that you should use with caution. Although this, like everything else, is also a matter of taste, caution is still recommended when using background images. The use of images is generally acceptable, but if the selected graphics make the menu items hard to read, the designer has made a mistake. The following example shows a menu with a background image: page.10.marks.MENU = HMENU page.10.marks.MENU.1 = GMENU page.10.marks.MENU.1.NO { backColor = #000000 XY = 100, 20 10 = TEXT 10.text.field = title 10.fontColor = #ffffff 10.offset = 4,14 10.fontFile = fileadmin/verdana.ttf 10.fontSize = 11 5 = IMAGE 5.file = fileadmin/_temp_/logo.gif wrap = | }
Use file to indicate the image that is to act as the background. This example illustrates that the menu can be enhanced with a background image without affecting the legibility of the entries.
An Alternative to GMENU
One thing is clear: as a rule, graphical menus are responsible for higher server loads and are slower than text menus. You do not always have to use graphics to create attractive menus. List-based text menus can be an alternative to graphical menus. For more information on how to jazz up lists, go to http://www.alistapart.com/ articles/taminglists. Now we want to illustrate how to display menu entries in list form. page.10.marks.SEARCH = HMENU page.10.marks.SEARCH { stdWrap.required = 1 stdWrap.wrap = | entryLevel = 0 1 = TMENU 1 { wrap =
|
[ 164 ]
Chapter 7 noBlur = 1 NO = 1 NO { wrapItemAndSub =
|
stdWrap = upper } } 2 < .1 2.wrap =
|
2.CUR.stdWrap.wrap = | }
All of the properties used here are already familiar to you. Pay particular attention to the structure of the
and the
tags. The first menu level is enclosed in the
tag with wrap =
|
.
GMENU_FOLDOUT
The foldout menu is a combination of a graphical menu and a JavaScript menu. When the top menu level is clicked, the second level slowly unfolds downwards. Do not use this type of menu if you want to make your site accessible to older browsers; but with new browsers it looks great. GMENU_FOLDOUT menus work with Opera 5, Netscape 4, and Internet Explorer from version 4 onwards.
[ 165 ]
Menus
The first level has to be a GMENU. The second level can either be a GMENU or a TMENU. The following somewhat bulkier script generates the menu shown in the figure on the previous page. An explanation of each of the properties is given after the script. includeLibs.gmenu_foldout = media/scripts/gmenu_foldout.php page.10.marks.MENU = HMENU page.10.marks.MENU.1 = GMENU_FOLDOUT page.10.marks.MENU.1.expAll=1 page.10.marks.MENU.1.NO { backColor = #ffffff XY = 200, 20 10 = TEXT 10.text.field = title 10.fontFace = fileadmin/verdana.ttf 10.fontSize = 12 10.offset = 5,15 wrap = | } page.10.marks.MENU.2 = TMENU page.10.marks.MENU.2.NO { linkWrap = } page.10.marks.MENU.1 { dontLinkIfSubmenu = 1 stayFolded=1 foldSpeed = 6 subMenuOffset = 10,18 menuOffset = 200,20 menuBackColor = #000000 bottomBackColor = #cccccc menuWidth = 200 arrowNO = media/bullets/arrow_no.gif arrowACT = media/bullets/arrow_act.gif arrowImgParams = hspace=4 align=top bottomContent = TEXT bottomContent.value = This text is displayed under the menu }
The GMENU_FOLDOUT.php class library has to be installed so that you are able to use GMENU_FOLDOUT. This is followed by the definition of the two menu levels. The first level in this example is a graphical menu and the second one is a normal TMENU. [ 166 ]
Chapter 7
And now, the appropriate properties of GMENU_FOLDOUT are defined and it is set up for output. Property dontLinkIfSubmenu
Description
stayFolded
This property specifies that the menu remains folded if another link of the first level is clicked.
foldSpeed
Specifies the speed with which sub-menus open. 1 means no animation.
subMenuOffset
Positions the sub-menus in the browser window.
menuOffset
Positions the sub-menus from the top left corner in the browser window.
menuBackColor
Background color.
bottomBackColor
Color below the menu.
menuWidth
Menu width.
arrowNO
Image displayed in the normal state.
arrowACT
Image to be displayed when enabled.
arrowImgParams
Additional parameters can be assigned to the tags of the images with this.
This property ensures that menu elements with a sub-entry are not linked.
Layer Menus
Menus based on DHTML layers and JavaScript can be created with the objects TMENU_LAYERS and GMENU_LAYERS. You don't have to know these technologies to do this. Even if you have no experience with this rather complex subject, you can create functional DHTML applications. The two objects are based on TMENU and GMENU respectively and extend their properties. Before you use these menus, keep in mind that older browsers will have problems displaying them. This is due to their imperfect support of the Document Object Model (DOM). But even current browsers like Opera 7 have their problems with these menus since these browsers work with a newer version of DOM. If you want to use these menus in these browsers in spite of that, you have to modify the layer functions. Search for the following code in the \media\scripts\jsfunc. layermenu.js file: this.x= (bw.ns4||bw.op)?this.css.left:this.el.offsetLeft; this.y= (bw.ns4||bw.op)?this.css.top:this.el.offsetTop; this.height=(bw.ie4||bw.ie5||bw.ns6)?this.el.offsetHeight:bw.ns4?this. ref.height:bw.op? this.css.pixelHeight:0; [ 167 ]
This code has to be replaced with the following lines: this.x= (bw.ns4)?this.css.left:this.el.offsetLeft; this.y= (bw.ns4)?this.css.top:this.el.offsetTop; this.height=(bw.ie4||bw.dom)?this.el.offsetHeight:bw.ns4?this.ref. height:0; this.width= (bw.ie4||bw.dom)?this.el.offsetWidth:bw.ns4?this.ref. width:0;
This is all you need to do to make the TMENU_LAYERS and GMENU_LAYERS menu versions work in the current version of the Opera browser. Let's illustrate the creation of a layer menu with the help of the GMENU_LAYER object. First you create a two stage layer menu. The PHP library for layer menus has to be installed for the layer menu to work. With GMENU_LAYERS, integrate the GMENU_ LAYERS.php file using the includeLibs property: page.includeLibs.gmenu_layers = media/scripts/gmenu_layers.php page.10.marks.MENU = HMENU page.10.marks.MENU.1 = GMENU_LAYERS page.10.marks.MENU.1 { layerStyle = position:absolute;left:0px;top:20px;width:10px;visibility:hidden; xPosOffset =20 yPosOffset =-20 lockPosition = x expAll=1 NO { backColor =#000080 XY = 200, 20 10 = TEXT 10.text.field = title 10.fontFace = fileadmin/verdana.ttf 10.fontSize = 12 10.offset = 10,18 10.fontColor = #ffffff } } page.10.marks.MENU.2 = GMENU page.10.marks.MENU.2.NO { backColor = #0000ff [ 168 ]
This example illustrates how little effort is required to create attractive menus.
This is all the more true if you keep in mind the amount of time that would be required to create such a menu manually with JavaScript and DHTML. There are a number of new elements in the example that warrant closer examination: Statement
Description
page.10.marks.MENU.1 = GMENU_LAYERS
Defines the first menu layer as GMENU_LAYER. This determines that the menu is folded from the first layer onwards.
The layer properties are set here. The syntax is the same as with HTML and/or CSS.
xPosOffset =30
Specifies the number of pixels by which the folded layer is to be shifted to the left or the right on the x-axis. In this case, the layer is shifted 30 pixels to the right. For an offset to the left, you have to use a negative value.
[ 169 ]
Menus
Statement
Description
lockPosition = x
Specifies how the menu is to be fixed. Possible values here are x, y or the property is not used. A vertically opening menu is set with x. To create a horizontal menu, set the value y. If no value is used, the folding layer appears at the position where the menu is activated.
expAll=1
For the menu to fold at all, the property expAll must be set to 1.
page.10.marks.MENU.2 = GMENU
This defines the second menu layer. A GMENU is used here. The definition of this menu has no special features. Only a different font size has been chosen for visual reasons.
To enable you to reproduce the following example with the help of the familiar page tree, this tree has to be extended by one level. The example assumes that the three additional pages Spots, Jingle, and Interview have been created under Customers/Radio. The menu is extended by a third level in this example. The strengths of layer menus are illustrated with the example—even the most extensive of menus can be displayed in a space-saving manner. The complete source text responsible for this example is reproduced below: page.includeLibs.gmenu_layers = media/scripts/gmenu_layers.php page.10.marks.MENU = HMENU page.10.marks.MENU.1 = GMENU_LAYERS page.10.marks.MENU.1 { layerStyle = position:absolute;left:0px;top:20px; width:10px;visibility:hidden; xPosOffset = 20 xPosOffset = -20 lockPosition = x expAll=1 NO { backColor = #0000ff XY = [10.w]+30, 20 10 = TEXT 10.text.field = title 10.fontFace = fileadmin/verdana.ttf 10.fontSize = 12 10.offset = 10,18 [ 170 ]
You can see that the creation of this menu requires more extensive source text. However, this is nothing when compared with menus that are programmed with DHTML and JavaScript.
Formatting the Menu
Although the menu works, it is still not particularly attractive. The following example illustrates how layer menus can be formatted. You already know most of the properties that are used for formatting. The example can serve as the base for your own layer menu. [ 171 ]
With 30 < .20 a copy is made of position 20, which now represents the right edge of the menu. 40 = BOX || 40.dimensions = 0,0,140,2 40.color = #000080 50 = |*||*| || BOX 50.dimensions = 0,0,140,2 50.color = #000080 50.align = ,b }
With |*||*| || BOX, you specify that the BOX will form to the upper and lower edge of the menu. page.10.marks.MENU.3 = GMENU page.10.marks.MENU.3.NO { backColor = |*| #0000ff || #aaaaaa |*| XY = 100, 20 10 = TEXT 10.text.field = title 10.fontFace = fileadmin/verdana.ttf 10.fontSize = 10 10.fontColor = |*| #ffffff|| #000000|*| 10.offset = 10,18 20 = BOX 20.dimensions = 0,0,2,20 20.color = #000080 30 < .20 30.align = r 40 = BOX || 40.dimensions = 0,0,120,2 40.color = #000080 50 = |*||*| || BOX 50.dimensions = 0,0,120,2 50.color = #000080 50.align = ,b }
This script resolves the output with rectangles that are generated with BOX. The expected values are the start positions of top and left as well the width and the height. The third level can be formatted more or less the same way as the second. If you want to, you can also play around with colors.
[ 173 ]
Menus
Text Menus in Layer Form
As we mentioned earlier, text menus can also be endowed with a layer function. The principle of this is identical to that of GMENU. A precondition for TMENU_LAYERS is the installation of the appropriate library. page.includeLibs.tmenu_layers = media/scripts/tmenu_layers.php
After that, you can create the menu. An interesting feature in this is layerStyle, using which CSS controls the look of the menu.
ImageMaps
Another interesting menu version is IMGMENU. You can create image maps with this. In this type, menu background and menu entries are combined together into one graphic. The appropriate linking is done via the <area> tag. These menus can also be explained best with the help of an example: page.10.marks.MENU = HMENU page.10.marks.MENU.special = list page.10.marks.MENU.special.value = 9,8,7,6,5,4 page.10.marks.MENU.1 = IMGMENU page.10.marks.MENU.1 { main.XY = 420,20 main.10 ��������������� = IMAGE main.10.file = fileadmin/_temp_/logo.gif dWorkArea = 14,00 NO { distrib = textX+13,00 5 = TEXT 5.text.field = title 5.fontColor = #ffffff 5.fontSize = 14 5.offset = 0,13 5.text.case = upper } }
To start, specify the entry level and menu type; in this case IMGMENU. Then the menu is defined. The main property determines the graphic for the Image Map. The following table shows all of the relevant properties:
[ 174 ]
Chapter 7
Property XY
Description
reduceColors
Due to the higher loading time caused by the ImageMap, the image should be kept as small as possible. Reducing it to 16 colors helps with this effort.
dWorkArea
This specifies the start point of the menu on the entire image. The values here are measured from the upper left corner of the image.
distrib
Each individual menu item can be positioned exactly using the distrib property. Since the spacing remains the same even for menu entries of variable length, the width of the menu items should be picked with textX and then be increased by a suitable value. To make sure the menu items do not shift vertically, the value of Y is set to 0.
Specifies the width and the height of the image. Since the size of the ImageMap normally corresponds to the size of the background image, width and height can be read in from [10.w] , [10.h].
In the subsequent steps, the page titles are imported and formatted. At the end you decide with IMGMap.explode how far the ImageMap areas should extend beyond the menu entries.
Special Menus
So far the menus have reflected the actual page structures. Although menu items could be explicitly excluded, the structure was always retained. With the special property of HMENU you can also create other menu forms. You will learn about these in the next few pages. Since these menus are used only rarely, they are only discussed briefly here.
Next Page (Browse Menu)
If you really want your visitor to look at all of your pages, use the browse type of menu. This type of menu takes the visitor to either the next or the previous page. This menu has the following properties: Property first/last
Description
index
Refers to the root page.
next / prev
Refers to the next/previous page.
nextsection / prevsection up
Refers to the next/previous section.
Refers to the first/last page of the current level.
Link to one level higher. [ 175 ]
Menus
An example is: page.10.marks.MENU = HMENU page.10.marks.MENU.special = browse page.10.marks.MENU.special{ items = prev | next prev.fields.title = « back next.fields.title = next» } page.10.marks.MENU.1 = TMENU page.10.marks.MENU.1.NO { linkWrap = | }
The browse menu can be expanded further. Functions can be included that not only take the visitor forward or backward one page at a time, but also back a whole level or directly back to the index page. page.10.marks.MENU = HMENU page.10.marks.MENU { special = browse special { items = index|up|prev|next items.prevnextToSection = 0 index.fields.title = INDEX index.uid = 5 } 1 = TMENU 1.NO { allWrap = | Current page
Modify this function whichever way you want. As already mentioned, you can completely deactivate it. Just comment out the line //$this->tempPageCacheContent();
TYPO3 and Search Engines
Sooner or later, the question of how search-engine friendly this TYPO3 CMS really is will have to be asked. It doesn't matter how beautiful a website is if nobody can find it. Traditionally search engines have had problems with the type of dynamically generated pages that are created with TYPO3 and other CM systems. In the next few pages you will learn how to optimize TYPO3 so that the output is search-engine friendly.
[ 322 ]
Chapter 13
Inserting Meta Tags
Even though meta tags are no longer as important in the ranking of search engines as they were years ago, you should put them in. Meta tags can be easily integrated into your pages with the Meta tags (extended) extension. With the Constant Editor, you will find an appropriate template in the Template module that will let you define the meta tags. Select the PLUGIN.META entry under Category.
Mark the checkboxes of the meta tags that should subsequently appear in your page in the input template. The meta tags that you have selected are then displayed in the Constants field of the template by clicking on Update. You can customize the value there or in the input template. But make sure that only those metatags that have a value assigned to them are inserted in the page. A complete meta tag statement could look like this:
The dynamic URLs that are created by default are quite cryptic and are an exasperating topic with most CM systems. The usual URLs follow the pattern of http://www.myhost.de/index.php?id=18. But this type of an address doesn't give an indication about the content of that page. The URLs generated when passing parameters get terribly long. Search engines are allergic to this, since it is easy to juggle things with appended values to URLs that makes it look as if the page had numerous sub-pages with similar contents. The result of this is that search engines simply truncate addresses after the question mark and thereby only the main page of the web presence is listed in the search machine. To circumvent this problem, TYPO3 lets you simulate static HTML pages. The address http://www.myhost.de/index.php?id=18 is transformed to http://www.myhost.de/Jobs.4.5.html. To change the address in this way, the Apache server uses the mod_rewrite module. You can get complete information about this module in the Apache handbook (http://httpd.apache.org/docs/2.0/de/mod/ mod_rewrite.html). In addition, enter the following code into Setup: config.simulateStaticDocuments = 1 config.simulateStaticDocuments_pEnc = md5 config.simulateStaticDocuments_addTitle = 40
[ 324 ]
Chapter 13
The first property enables the simulation of static HTML pages. The second property sets the encryption mode to Md5. simulateStaticDocuments_addTitle and the third defines that the URLs will contain the page titles, although limited to the first 40 characters. Now we come to the most important part, customizing Apache. For this, set up the .htaccess file in the main directory of the TYPO3 installation and insert the following lines: RewriteEngine on RewriteCond %{REQUEST_FILENAME} !-f RewriteBase /typo3site RewriteRule ^[^/]*\.html$ /index.php RewriteRule ^typo3$ typo3/index_re.php RewriteRule ^([0-9]+)[.]([0-9]+).html$ index.php?id=$1&type=$2
RealURL
RealURL follows a similar path. You can easily implement meaningful URLs with this extension. You can get complete information about this at http://typo3.org/ documentation/document-library/extension-manuals/realurl/current/. After the installation, you have to customize the .htaccess file. In order for RealURL to function, several prerequisites must be taken care of: You must have an Apache server running with mod_rewrite enabled and an .htaccess file with the following lines appended: RewriteEngine On RewriteRule ^typo3$ - [L] RewriteRule ^typo3/.*$ - [L] RewriteBase / RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_FILENAME} !-l RewriteRule .* index.php
You may face problems under Windows when trying to set up an .htaccess file. To circumvent these, either use an appropriate text editor or create a normal *.txt file, which you then rename with FTP. You can also set up an htaccess.txt file (without the period, but with the txt ending). Subsequently open http.conf and customize the following directive: AccessFilename htaccess.txt
After rebooting the server, Apache will work with the .txt file.
[ 325 ]
Fine Tuning
Extend the Setup field with the following entries: config.simulateStaticDocuments = 0 config.baseURL = 1 config.tx_realurl_enable = 1 config.prefixLocalAnchors = all
SimulateStatic is thereby disabled, the extension is enabled, and the link anchors (my. html#news) are interpreted correctly. And finally you have to adjust the typo3conf/ localconf.php file. The following example illustrates what that file could look like: $TYPO3_CONF_VARS['EXTCONF']['realurl']['_DEFAULT'] = array( 'preVars' => array( array( 'GETvar' => 'L', 'valueMap' => array( 'dk' => '1', ), 'noMatch' => 'bypass', ), ), 'fileName' => array ( 'index' => array( 'page.html' => array( 'keyValues' => array ( 'type' => 1, ) ), '_DEFAULT' => array( 'keyValues' => array( ) ), ), ), 'postVarSets' => array( '_DEFAULT' => array ( 'news' => array( array( 'GETvar' => 'tx_mininews[mode]', 'valueMap' => array( 'list' => 1, 'details' => 2, ) ), array( [ 326 ]
You can get the full explanation for this at http://www.typo3.org.
Protection from Email Spam
If you publish your email address on your Internet site without encrypting it, you can be sure that you will be flooded with spam in no time at all. Professional spammers work with tools that automatically harvest websites for email addresses. There are a number of options that you can use to make sure that your email address isn't one of them. The most effective, but also the most complicated way to do this is to display your email address as a graphic. Alternatively, you can encrypt your email address with the following code in the template setup: config.spamProtectEmailAddresses = 2 config.spamProtectEmailAddresses_atSubst = (at)
This integrates encryption for email addresses. The address [email protected] becomes: contact(at)myhost.de
With spamProtectEmailAddresses = 2 you define that the ASCII value of every character of the tag content is changed by 2. Permitted values are -5 to 5. This means that the value of the href attribute of the tag is secured. The email address continues being displayed on the website the same way as before. The email address can also be changed with spamProtectEmailAddresses_atSubst = (at); now [email protected] is changed to contact(at)myhost.de.
Customizing the Page Header
This topic doesn't necessarily have anything to do with search engines, but we should still discuss it here. If you take a look at a page created with TYPO3, you will first see a voluminous annotation. <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
This information makes perfect sense; we are, after all, interested in introducing TYPO3 to a wider general public. If you want, you can expand this annotation or even remove it completely. To expand it by additional entries, enter the following in Setup: page.config { headerComment ( This is where your annotation is displayed. ) }
Enter the annotation of your choice at the marked spot. The source text will look as follows in the front end: <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> Chapter 13 created by Kasper Skaarhoj and licensed under GNU/GPL. TYPO3 is copyright 1998-2006 of Kasper Skaarhoj. Extensions are copyright of their respective owners. Information and contribution at http://typo3.com/ and http://typo3.org/ --> ...
This is probably the most elegant methodology. The original commentary is preserved that way, but you can still call attention to your accomplishments. If you want to remove the annotation completely, you can of course do that as well. In a way this is against to the basic idea of the Open Source movement, but we might as well show it to you. You can find the entry in the typo3/sysext/cms/tslibclass.tslib_pagegen.php file from (about) line 479 on. You can see the annotation there and you can delete it. $GLOBALS['TSFE']->content.=' <select name="SET[function]" onchange="jumpToUrl('index. php?&id=5& SET[function]='+this.options[this.selectedIndex].value,this);"> Page tree overview Translation overview Log TSconfig Pages
The key of the menu entry, which is called tx_infopagetsconfig_webinfo in this example, is interesting. If, for instance, you also want to hide the entry Log, you would customize the TSConfig field in the following way: mod.web_info.menu.function { tx_infopagetsconfig_webinfo = 0 tx_belog_webinfo = 0 }
Be aware that menu items are only hidden in this example and not disabled. Experienced users with the right knowledge can still access them. All they have to do is call up the appropriate URL. This is what it looks like for the TSConfig field, for example: http://localhost/typo3/typo3/mod/web/info/index.php?&id=6&SET[function ]=tx_infopagetsconfig_webinfo
Primarily, the capabilities of mod should only be employed to save inexperienced users from having too many options in list boxes. [ 333 ]
Customizing the Back End with TSConfig
Customizing Editing Forms with TCEFORM
You can customize back-end forms with TCEFORM. Among other things, you can hide entry fields or rename them. An example will clarify how easy this is. You normally have the option of entering the page title when you create or edit a page.
The page title in this example is controlled by the field of the same name. If you want to prevent an editor from changing the page title using this field, customize the TSConfig field in the following manner: TCEFORM.pages.title { disabled = 1 }
Another look at the back end confirms that the Pagetitle field is now hidden.
[ 334 ]
Chapter 14
TCEFORM can also be used to determine what pages can be created by a user. If you
want to prevent a user from creating a search form, you would use this syntax: TCEFORM.tt_content.CType.removeItems = search
Now you will notice that the Search form option is no longer displayed on the Create page contents page. The following table itemizes all of the elements for that purpose: Element Image HTML Divider Header Text Text with image Links to files Multimedia Insert datasets Insert Plugin Script Menu/Sitemap Table List Form Search Login Textbox
TS key image html div header text textpic uploads multimedia shortcut list script menu table bullets mailform search login splash [ 335 ]
Customizing the Back End with TSConfig
Configuring System Tables with TCEMAIN
You can define options for system tables with TCEMAIN. One of these is the option to predefine the rights to create new pages for a page tree depending on user settings. The following syntax illustrates a typical example: TCEMAIN.permissions.groupid = 5 TCEMAIN.permissions.user = show, editcontent, new, edit, delete TCEMAIN.permissions.group = show, editcontent, new, edit, delete TCEMAIN.permissions.everybody = show, edit, delete
With this syntax, all newly created pages are automatically assigned to the user group that has the ID 5. The available values are show (view in the back end), editcontent, new (create new pages), edit (edit page headers), and delete. In the current example, the user group with the ID 5, and its members have the following rights: •
View pages
•
Delete pages
•
Create new pages
•
Edit page contents
All other users can only: •
View pages
•
Edit pages
Another example for TCEMAIN has to do with a typical (and often annoying) TYPO3 phenomenon: If you copy a page and insert it, it automatically gets a copy suffix. For example, About us becomes About us (copy). This can easily prevented with: TCEMAIN.defaul.disablePrependAtCopy = 0
User TSConfig
User TSConfig can be defined for individual users as well as for user groups. The configuration for individual users is based on the configuration of the respective user group(s) the user belongs to. This configuration can be overwritten with the appropriate entries in the user's profile. To look at the configuration of a particular user, call up the Tools | User Admin module and click on that user's name.
[ 336 ]
Chapter 14
Setup, admPanel, and options arrays are listed in the User-TSConfig tree (you will find out what these signify in the following pages). You can see the respective TypoScript commands with comments below this tree.
Setup
You can customize all the properties found in the User | Setup module. These include the maximum title length, help functions, and whether or not to display the RTE.
You have the option of defining default properties (setup.default) that will be applied to every new user. If a user clicks on the option to recreate the standard configuration, the values that you set here are loaded.
[ 337 ]
Customizing the Back End with TSConfig
With the override parameter, you can overwrite previous settings. The settings that were defined by setup.override cannot be removed by the user by simply deleting the respective entries. The value must either be overwritten again or cleared with an empty string. If, for instance, you want to deny a user the display of the RTE, customize the TSConfig field the following way: setup.default.edit.RTE = 0
admPanel
By now you are thoroughly familiar with the administrator panel. Use the top-level object admPanel to customize it. admPanel.enable lets you hide individual parts of the User Admin panel. If you
want to make sure that the Info module is not displayed in the front end, use the following syntax: admPanel.enable.info = 0
In addition to the Info module, all of the following can be hidden: •
all
•
preview
•
cache
•
publish
•
edit
•
tsdebug
•
info
Note that the default setting for administrators for all modules is 1. Be aware that all the settings related to the User Admin panel are only effective if it is actually shown in the front end. Therefore, the template of the User Admin panel must be enabled in the Setup with config.admPanel = 1.
options
TLO options is used to define global settings for the back end. You can, for instance, show or hide RTE buttons for users or define the duration for the display of the click menu. [ 338 ]
Chapter 14
For example, the following syntax gives an editor the right to set up directories in the element browser. options.createFoldersInEB = 1
Summary
This chapter discussed the back-end configuration of TYPO3 on two levels—the page level and the user level. Individual pages of the website can be configured using Page TSConfig and site-wide configuration for users or groups of users can be achieved using User TSConfig.
[ 339 ]
TypoScript Reference This TypoScript reference includes all the important elements that you will need in your day-to-day work. If you cannot find something you are looking for in here, go to http://typo3.org/documentation/document-library/doc_core_tsref/ for the complete TypoScript reference (TSref).
Functions Date and Time Functions date
Formats the entered date to the desired format. You can get a list of the options at http://www.php.net/manual/de/function.date.php. Syntax:
date = string
Example:
date = j, n, Y
strftime
Formats an entered date according to the local settings. You can use all of the allowed conversion specifiers in the strftime()PHP function. For a complete description of the PHP function go to http://www.php.net/manual/en/function. strftime.php. Syntax:
strftime = string
Example:
strftime = %A, %d. %B %Y
TypoScript Reference
if directReturn
If this property is set, a true/false value is automatically returned. Syntax:
directReturn = string
Example:
directReturn = true
equals
Returns true if the content is identical to the value of equals.value. Syntax:
equals = string
Example:
if { value.data = leveluid:1 equals.field = uid }
isFalse
If the content is false, isFalse will be used no matter what is below. Syntax:
Returns true if the content is greater than the value of isGreaterThan.value. Syntax:
isGreaterThan = string
Example:
isGreaterThan.numRows.table < subparts.LEFT.table
isLessThan
Returns true if the content is less than isLessThan.value. Syntax:
isLessThan = string
Example:
if.isLessThan.field = imageorient
[ 342 ]
Appendix A
isInList
Returns false if the content does not occur in the list defined by isInList.value. Syntax:
isInList = string
Example:
if.isInList.data = field:uid
isPositive
If the content is a positive number, true is returned. Syntax:
isPositive = string
Example:
isPositive = 2
isTrue
Returns true if the content is true. Syntax:
isTrue = string
Example:
if.isTrue.numRows < styles.content.getRight
negate
The returned result is negated. Syntax:
negate = boolean
Example:
negate = 1
value
Specifies the standard value. Syntax:
value = string
Example:
value = 10
imageLinkWrap
This object encloses an image with a link to the showpic.php script. You can specify width, height, background color, and other parameters of the new window.
bodyTag
Defines the tag of the new window. [ 343 ]
TypoScript Reference
Syntax:
bodyTag = string
Example:
bodyTag =
effect
Defines the effect to be used. You can use any of the possible GIFBUILDER values. Syntax:
effect = see GIFBUILDER
Example:
effect = gamma=1.3
enable
The image is only used if this property is set to 1. Syntax:
enable = boolean
Example:
enable = 1
height
Defines the height of the image. If m is appended to the value, the proportions of the image are maintained, with height then representing the maximum height. Syntax:
height = int (1-1000)
Example:
height = 200
JSWindow
The image is opened in a new window that has the same dimensions as the image. Syntax:
JSWindow = boolean
Example:
JSWindow = 1
JSWindow.altURL
The window is normally displayed by the showpic.php file, but you can assign a different script to the JSWindow.altURL property. Syntax:
JSWindow.altURL = string
Example:
JSWindow.altURL = mypic.php
[ 344 ]
Appendix A
JSWindow.expand
The dimensions of the new window can be increased to be larger than the image by the values x and y. Syntax:
JSWindow.expand = x,y
Example:
JSWindow.expand = 20,40
JSWindow.newWindow
Each image is displayed in a new window. Syntax:
JSWindow.newWindow = boolean
Example:
JSWindow.newWindow = 1
target
The target attribute with the respective value is assigned to the tag. Syntax:
target = string
Example:
target = _blank
title
A page title is assigned to the new window. Syntax:
title = string
Example:
title = My new window
width
Defines the width of the image. If m is appended to the value, the proportions of the image are maintained, with width then representing the maximum width. Syntax:
width = int (1-1000)
Example:
width = 100
wrap
Wraps the image defined within the tag into the specified HTML syntax. Syntax:
wrap = wrap
Example:
wrap =
|
[ 345 ]
TypoScript Reference
parseFunc
This function is used to parse content with special TYPO3 tags.
allowTags
A list of tags that are permitted in the code. Syntax:
allowTags = string
Example:
allowTags = b,i,img
constants
The constants in the text that are defined at the top level are replaced by the specified value. In the following example, every occurrence of ###EMAIL### is replaced by the specified email address. Syntax:
HTML tags that are not allowed in the code can be specified in a comma-separated list. Syntax:
denyTags = string
Example:
denyTags = font, div
makelinks
If this property is set to 1, any content that is prepended with http:// or mailto: is transformed to a hyperlink. Syntax:
makelinks = boolean
Example:
makelinks = 1
short
You can define abbreviations with this. In the following example, every occurrence of the word Claim is replaced with A beautiful day. Whenever a Link appears, a hyperlink is defined.
[ 346 ]
Appendix A
Syntax:
value = string
Example:
short { Claim = A beautiful day Link = Page }
tags
Allows you to define your own HTML tag. Syntax:
tags = string
Example:
parseFunc.tags.myTag = TEXT parseFunc.tags.myTag. { current = 1 wrap = | }
select
This object creates an SQL query with which you can determine what datasets will be read out from the database.
andWhere
Extends a WHERE clause that is defined under where by one more condition. Syntax:
string (SQL:Where / wrap)
Example:
andWhere.wrap = sys_language_uid = |
begin
The SQL query will start at the dataset specified here. Syntax:
begin = integer
Example:
begin = 5
join, leftjoin, rightjoin
Defines a respective table name for JOIN, LEFT OUTER JOIN, and RIGHT OUTER JOIN. Syntax:
join = string
Example:
join = tt_content ON tx_news_rt.pid=tt_content.pid
[ 347 ]
TypoScript Reference
languageField
This property is used with multilingual pages. When it is set, it points to the field in the dataset that represents a reference to a dataset in the sys_language table. Syntax:
languageField = string
Example:
languageField = sys_language_uid
max
Only the specified maximum number of datasets will be output. Syntax:
msx = integer
Example:
max = 3
orderBy
Corresponds to the SQL statement Order by and sorts the datasets according to the specified field. Syntax:
orderBy = string
Example:
orderBy = sorting, title
pidInList
A comma-separated list of parent IDs is specified with this. Syntax:
pidInList = string/int
Example:
pidInList = 120,86
selectFields
This property specifies the fields to be selected. Syntax:
selectFields = string
Example:
selectFields = media
uidInList
This specifies a list of unique IDs. Syntax:
uidInList = string
Example:
uidInList = 12,97 [ 348 ]
Appendix A
where
The WHERE clause can be extended by one more condition with this property in order to get more accurate queries. Syntax:
where = string
Example:
where = colPos = 0 AMD CType='text'
tableStyle
Use this function to create tables. The statements extend the
tag by the respective HTML attributes.
align
Alignment of the table. Syntax:
align = string
Example�:
align = My Company
border
Defines the table's border width. Syntax:
border = int
Example�:
border = 2
cellspacing
Defines the spacing between individual cells. Syntax:
cellspacing = int
Example:
cellspacing = 3
cellpadding
Defines the inside spacing of individual cells. Syntax:
cellpadding = int
Example:
cellpadding = 4
[ 349 ]
TypoScript Reference
params
Allows you to assign additional attributes with appropriate values to the
tag. Syntax:
params =
-Attribute
Example:
params = width=100%
Conditions
Conditions will let you create conditioned queries similar to the if structures of other languages.
Browsers Identifier acrobat
Browser
avantgo
AvantGo
ibrowse
IBrowse
lynx
Lynx
msie
Microsoft Internet Explorer
netscape
Netscape Communicator
opera
Opera
php
PHP fopen
teleport
Teleport Pro
unknown
other
Syntax:
[browser= string]
Example�:
[browser = netscape]
Adobe Acrobat
Browser-Version Operator Blank
Function
=
The value has to be exactly the same.
>
The browser has to be more recent than the specified value.
4]
Operating System Identification amiga
Operating system
unix_hp
HP-UX
linux
Linux
unix_sgi
SGI/IRIX
mac
Macintosh
unix_sun
SunOS
win311
Windows3.11
win95
Windows 95
win98
Windows 98
winNT
Windows NT
Amiga
Syntax:
[system = string]
Example�:
[system = mac, win]
Device Identification grabber
Equipment
pda
PDAs
robot
indexing robot
wap
WAP-capable cell phone
Grabber
Syntax:
[device = string]
Example�:
[device = wap, pda]
[ 351 ]
TypoScript Reference
Language Syntax: Example�:
[language = string] [language = de]
Other Options Condition [dayofmonth...] [dayofweek...] [hostname...]
Description Day of the month (1-31) Day of the week (Sunday = 0, Saturday = 6)
Same value as with getenv("REMOTE_ADDR") in PHP. The value as floating-point number is compared with the server time. Possible values are >,
