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!
TYPO3 Enterprise Content Management Leaders of the TYPO3 community guide you through this powerful, enterprise-level, open source content management system
Credits Authors Werner Altmann René Fritz Daniel Hinderink Commissioning Editor Louay Fatoohi Technical Editor Ashutosh Pande
Layout Ashutosh Pande Niranjan Jahagirdar Proofreader Chris Smith Translator Steve Tomlin Cover Designer Helen Wood
About the Authors Werner Altmann is the author of the original German handbook for editors, and a member of the TYPO3 documentation team. As the technical project manager, he is in charge of planning and implementing major TYPO3-based projects.
René Fritz has created parts of the TYPO3 core and has programmed various extensions to the system, including the digital asset management system. He was also among the first TYPO3 users. He works as a freelance technical consultant and developer, and continues to be part of the core developer team for TYPO3. He is also an active member of the TYPO3 Association.
Daniel Hinderink is a managing partner with a consulting company specializing in webtechnology-based information systems for medium to large companies. He has been associated with the TYPO3 project for a long time, and has provided strategic advice and practical work in research and planning, as well as marketing. He is also an active member and currently the vice-chairman of the TYPO3 Association.
Table of Contents Chapter 1: Introduction
1
1.1 History
1
1.2 What is a CMS? 1.2.1 Separation of Content from Layout 1.2.2 Content Lifecycle Functionality 1.2.3 Modularity 1.2.4 Target Group 1.2.5 TYPO3 References
2 3 3 4 4 5
The GPL: GNU General Public License
5
1.3 The TYPO3 Community
6
1.4 The TYPO3 Association 1.4.1 Goals and Objectives 1.4.2 Membership and Application
7 8 8
Active Members Supporting Members Bodies and Practical Work
Chapter 2: Installation 2.1 Criteria for System and Package Selection 2.1.1 Hardware
8 8 9
11 11 12
Type of Usage Expected Capacity
12 12
2.1.2 Web Server 2.1.3 Database 2.1.4 Other Software
16 16 17
QuickStart Test Site Dummy TYPO3 Source
2.2 Installing a Test and Training Installation 2.2.1 The WAMP Windows Installer 2.2.2 Linux (et al.) Quick Install 2.3 Installation for Productive Use 2.3.1 LAMP Installation 2.3.2 WAMP Installation 2.3.3 WIIS Installation
19 19 19 19
20 20 21 22 22 25 26
Table of Contents 2.4 The Installation Tool 2.4.1 Basic Configuration 2.4.2 Database Analyzer 2.4.3 Image Processing 2.4.4 All Configuration 2.4.5 typo3temp/ 2.4.6 phpinfo() 2.4.7 Edit Files in typo3conf/ 2.4.8 About 2.5 Configuration Options in TYPO3_CONF_VARS 2.5.1 [GFX]:$TYPO3_CONF_VARS 2.5.2 [SYS]:$TYPO3_CONF_VARS["SYS"] 2.5.3 [EXT]: $TYPO3_CONF_VARS["EXT"] 2.5.4 [BE]: $TYPO3_CONF_VARS["BE"] 2.5.5 [FE]: $TYPO3_CONF_VARS["FE"] 2.5.6 Other Options 2.6 Separation of Production Server/Live Server 2.6.1 Static Pages 2.7 Backup
Chapter 3: TYPO3 for Editors 3.1 The Role of the Editor
62
3.2 Logging in to the System 3.2.1 The Correct Browser Settings 3.2.2 Login 3.3 User Interface and Module 3.3.1 Areas of the User Interface
63 63 63 64 65
Module Bar Navigation Area Details View
3.3.2 Main Modules and Submodules—An Overview Web Pages View List Info Access Functions
File Filelist ii
61
65 66 67
67 67 67 68 68 68 69 70
70 70
Table of Contents Images
71
Document User
71 71
Task Center Setup
Help 3.4 The User | Task Center as a Communication Center 3.4.1 Quick Note 3.4.2 Recent Pages 3.4.3 Actions 3.4.4 Messages 3.4.5 Tasks 3.5 Pages as Containers for Contents 3.5.1 Site Structure, Page Tree, and Contents 3.5.2 Creating and Editing New Pages Type Pagetitle Localization Settings
3.5.2 Different Page Types Standard Advanced External URL Shortcut Not in Menu Backend User Section Mount Point Spacer SysFolder
3.6 Content Input with TYPO3 3.6.1 Creating and Editing New Content Type Header General Options
3.6.2 The Different Content Types Header Text Image Text with Image Bullet List Table Filelinks Multimedia Form Search Login
71 72
72 73 73 74 74 75 76 77 77 79 81 81 81
82 82 82 84 84 85 86 86 86 86
87 89 91 92 92
92 93 93 93 95 95 96 97 98 99 101 102 iii
Table of Contents Menu/Sitemap Insert Records Insert Plugin Script Divider HTML
103 105 105 105 106 106
3.7 Assets in TYPO3 3.7.1 Managing Assets in the File Structure 3.7.2 Inserting Assets into an Application 3.8 Front-End Editing
106 106 108 109
3.9 The Rich Text Editor
111
Insert Link Insert Picture Inserting a Table
3.10 Working Efficiently with TYPO3 3.10.1 Scenario 3.10.2 Creating Page Structures 3.10.3 Serial Editing with the Buffer Example
3.10.4 Editing Selected Fields Example
3.10.5 Shortcuts User | Task Center: Recent Pages User | Task Center: Edit Records Shortcuts in the Footer
3.10.6 Help on the Content Level Word Processing with the Extension Text Tools Integrating Office Documents
3.10.7 Restore/Editing History 3.10.8 Multi-language Capability
Chapter 4: TYPO3 for Administrators
114 115 115
116 116 117 118 120
121 122
122 123 123 123
124 124 125
127 128
129
4.1 Tasks and Targets of Administration
129
4.2 Planning and Implementing the Content Management Environment
131
4.3 Principles of Organizing Permissions in TYPO3 4.3.1 Example Concept 4.3.2 Implementation Steps 4.4 Back-End User Administration 4.4.1 Setting up User Groups 4.4.2 Setting up Users
133 134 135 136 136 142
Example
144
4.5 Administration of Users with the Tools | User Admin Module145 iv
Table of Contents 4.6 Access Permissions on the Page Level Example
147 147
4.7 Front-End Editing for Backend Users
148
4.8 TSconfig—Options and Interface Control 4.8.1 TSConfig Wizard: TypoScript Property Lookup 4.8.2 User TSConfig
4.8.4 Adjusting the Rich Text Editor Restrictive RTE Configuration Extensive Configuration Alternatives
4.8.5 The Web | Info | Pages TSConfig Module 4.9 Setting up Simple Workflows 4.9.1 Workflow Configuration 4.9.2 Example: News Workflow 4.10 Defined Procedures with Actions 4.10.1 Action Types 4.10.2 Example: Action for Setting up Users 4.11 Front-End User Administration 4.11.1 Setting up User Groups 4.11.2 Setting up Users 4.11.3 Login 4.11.4 Assigning Pages and Content Example
4.11.5 Prospects 4.12 Statistics and Logs 4.12.1 The Web Info Module 4.12.2 Integrating AWStats 4.12.3 Logfile Evaluation 4.12.4 Front-end Logs 4.12.5 The DB Checking Module 4.13 TYPO3 and Caching
176 176 176 177 178 179 179 182
4.14 Digital Asset Management 4.14.1 Tasks and Aims of DAM 4.14.2 Integration into TYPO3
183 183 184
The Media | List Module The Indexing Module DAM Categories
4.14.3 Prospects
185 187 191
191 v
Table of Contents 4.15 Administration: The Future
Chapter 5: TypoScript 5.1 The Role of the Developer 5.1.1 The Production Process 5.1.2 Requirements and Overview 5.2 TypoScript—Basic Principles 5.2.1 What is TypoScript? 5.2.2 TSref 5.2.3 Digression: TypoScript and PHP Example: HRULER
5.2.4 TypoScript Templates 5.2.5 Hello World!—The First TypoScript Template 5.2.6 Cascading Templates 5.2.7 Template Records 5.2.8 Constants and Setup 5.2.9 Elements and Concepts 5.2.10 The Syntax Constants Values Comments and Comment Blocks Operators Conditions Includes
5.2.11 Order of processing 5.2.12 Nesting of Objects 5.3 TS Objects, Functions, and Data Types 5.3.1 Data Types 5.3.2 The Wrap Concept 5.3.3 Functions 5.3.4 Content Objects (cObject) Example: cObject FILE An Overview of cObjects
5.3.5 Top Level Objects Examples temp and styles
5.4 Development Tools 5.4.1 Info/Modify 5.4.2 TS Wizard 5.4.3 TypoScript Object Browser 5.4.4 Template Analyzer Checking the Syntax
5.9.1 TypoScript and HTML Templates The HTML Template Subparts Marker Preparing the HTML Template Creating the Template Record cObject Template Addressing Subparts and Marks Inserting Dynamic Content Stages of Construction with Cascading Templates
5.9.2 The Template Auto-Parser The HTML Template Configuring the Template Auto-Parser Creating the Page Stages of Construction with Cascading Templates
284
286 286 287 287 288 291 292 292 294 296
300 301 301 303 305 vii
Table of Contents 5.9.3 Pure TypoScript Templates Working with Wrap Working with CTABLE
5.10 Menus Level The Rootline
5.10.1 cObject HMENU—Common Properties of Menus 5.10.2 Text Menus (TMENU) Example: "B2C" Main Navigation Example: "B2B/B2E" Main Navigation Example: "B2C" Subnavigation
5.10.4 Layer-Based Menus (TMENU_LAYERS/ GMENU_LAYERS) 327 Example: "B2C" Main Navigation
5.10.5 GMENU_FOLDOUT Example: "B2C" Subnavigation
331
5.10.6 ImageMaps (IMGMENU)
334
Example: "B2C" Main Navigation
5.10.7 JavaScript Menus (JSMENU) Example: "B2B" Main Navigation
335
337 337
5.10.8 .special Menus
338
Example: Directory Example: Rootline
339 341
5.11 TypoScript in Detail 5.11.1 The optionSplit Function Syntax Example: COLUMNS
5.11.2 Working with Images and the GIFBUILDER GIFBUILDER Objects (GifBuilderObj) +calc .niceText Example: The Image in the Header
5.11.3 The stdWrap Function Get data Override/Conditions Parse data Get data and Parse data field data Example: Print Version Override/Conditions listNum ifEmpty Example: Using Two Columns viii
328
331
343 343 343 344
347 347 349 349 350
354 354 356 357 357 357 357 358 360 360 361 361
Table of Contents 5.11.4 Conditions Overview Example: Extending the Print Version
Example: Language Selection 5.12 Working with Frames 5.12.1 Creating Frames Constants Setup
5.12.2 The Example Site with Frames Constants Setup Constants
5.13 Future and Prospects 5.13.1 XHTML and Accessibility 5.13.2 Accessibility Missing Adjustments in the TYPO3 Core Visual Template Mapping Data Structures (DS) and Template Objects (TO) Template Selection and Rendering Assigning Content to Pages Flexforms Flexible Content Restrictive Content Content Areas Instead of Columns Using TemplaVoila
6.2 The Extension System 6.2.1 The Structure of Extensions 6.2.2 Extension Key 6.2.3 Extension Components 6.2.4 Extension Categories 6.2.5 Installation: System, Global, and Local 6.2.6 Extension Repository 6.2.7 Documentation 6.3 Extension Manager 6.3.1 Listing of Available Extensions 6.3.2 Importing Extensions from the Repository
396 396 397 397 398 399 400 401 402 403 404
Details View and Options
405
6.3.3 Extension Kickstarter
407
Chapter 7: Extension Development 7.1 A Visitor Counter in 20 Minutes
409 410 ix
Table of Contents 7.2 Extension Wizard: Kickstarter 7.2.1 Defining an Extension Key 7.2.2 Kickstarter Components 7.2.3 Extension Structure 7.2.4 Basic Rules of Extension Development Components Documentation Categories Publishing
7.3 Extension Management for Developers 7.3.1 Functions of the Extension Manager 7.3.2 TER Account 7.3.3 Transferring an Extension to the TER 7.3.4 TER Extension Management Members Only
7.4.4 Libraries The Basic API Base Classes Miscellaneous Tree View, Page Tree, Directory Tree TCEForms Authentication TypoScript E-mail HTML Others t3lib_div
425 425 426 426
427 427 429 430 431 432
433 434 435 437 438 438 439 439
441 442 442 443 443 443 444 444 444 445 445 445
7.4.5 Extension API 7.4.6 Database Structure
445 447
Page Tree and Contents Tables and Fields
449 450
7.4.7 Database, TCA, and TCEForms 7.4.8 Flexforms 7.4.9 TYPO3 Core Engine (TCE) Commands (cmdmap) Data (datamap) tce_db.php x
419 419 420 423 425
451 457 460 461 463 464
Table of Contents 7.4.10 SQL and TCA-Defined Tables 7.4.11 Users, Sessions, and Authentication Front End Back End
7.4.12 Platform-Independent Programming Server and Environment Variables General Information GET and POST Files
7.4.13 Multi-Language Capability 7.4.14 Character Encoding Principles of Character Encoding Different Character Enodings with TYPO3
7.5 Front-End Programming: Principles 7.5.1 Front-End Rendering Process 7.5.2 Front-End API 7.5.3 TypoScript Front End (TSFE) 7.5.4 cObject, tslib_cObj 7.5.5 Rendering cObjects with PHP 7.5.6 tslib_pibase 7.5.7 Links and Parameters in Plugins 7.5.8 USER, USER_INT, Caching, and Parameters 7.6 Front-End Programming: Examples 7.6.1 Content Borders 7.6.2 The Countdown TypoTag 7.6.3 Countdown Tag with JavaScript 7.6.4 Integrating External PHP Scripts Converting PHP Script
Table of Contents 7.8.1 Tools | Recent Changes 7.8.2 The Web | Functions | Wizards Submodule Function 7.8.3 Context Menu Entry 7.8.4 Skins—Changing the Backend Appearance ext_tables.php stylesheet_post.css
565 566
7.9 Services 7.9.1 Applying Services
566 567
Subtypes Services as a Chain Calling Specific Services
568 569 569
7.9.2 Implementing Services 7.9.3 Configuration 7.9.4 Introducing a New Service Type 7.10 Modifying and Extending XCLASS Class
570 576 577 577
7.11 TYPO3 and Other Programming Languages
580
7.12 Tools for the Developer 7.12.1 ExtDevEval 7.12.2 Debugging with debug()
580 580 581
Debug Extension
7.12.3 Debugging with t3lib_div::devLog() DevLog Extension
7.12.4 FE Debug/Info output and BE Env Info 7.12.5 PHP Development Environments
Index
xii
534 548 559 564
583
583 584
586 587
589
Foreword by Kasper Skårhøj There is a picture of a child standing on the shelf next to me here in my office. It was in my grandmother's possession until she moved to an old people's home. The boy in the image holds an object in his hand while looking at the camera, interrupted from his investigations by the photographer. I don't have kids yet myself; the boy is me as a three-year old. The picture fascinates me because it helps me to understand myself and God's design of our creative souls. It rips me out of TypoScript, PHP variables, and for...each loops for a moment and puts a smile on my face. The picture captures the essence of my personality, which has always been curious and creative—from building playhouses on my uncle's farm, shooting VHS-movies as a teenager, wiring up a house automation system to, well, accidentally programming a "little" CMS tool which I needed in the early days of the passion we all share, the modern Internet.
Opening the Playground Creativity defines a lot of who I am. TYPO3 has been the output valve of this energy. It is the "Very best of" album from my life until now, even with all the quirks it has. I love TYPO3 because I know it is an authentic expression of my creative pulse. But how did it ever come this far? Let's turn back the clock to 1997 when I began to study at the Technical University of Denmark. I think after 5 minutes at the introduction course I had spotted another restless soul in the class for whom Taylor polynomials had no significance for the greater meaning in life. We teamed up; I created my own little company (Curby Soft Multimedia) and college was where I slept the extra hours I missed at night. Back then I was extremely inspired by David Siegel's visions for web design (www.killersites.com). In fact, my "creativity valve" pointed in the visual direction back then; my teammate handled the Linux-stuff, I just juggled around with the colors.
The Binary Brainwash The CMS mantra of "separating content from code" was not the brilliant idea of any one individual, but what happened to all of us at that time; everyone realized that customers needed a CMS tool to maintain their websites. In late 1997 we began the first prototypes of what some years later became TYPO3. Unfortunately, my teammate didn't deliver the technical work and my proactive gene autoresponded by closing down Photoshop and starting up Homesite, a web browser pointed at www.php.net and the installation of a RedHat 6.2 server; one week later, I had the minimum knowledge required to make lookups in MySQL and present the content in an HTML page. And I hated it. At the time in 1998 I met another guy with a lot more marketing experience than myself. He wanted to commercialize the early version of TYPO3. So we set up the "Superfish.com" company together, hired employees, and even managed to team up with Saatchi & Saatchi in Copenhagen. But I had one condition; that I would be relieved from my role as the programmer behind the CMS as fast as possible! It was "Too much work and no fun makes Jack a dull boy" for
me and my inside was a desert. I was crying out for colors, poetry, and visual universes to explore. I hated programming; it dried me out and I had accepted it only as a temporary necessity. Maybe this should scare me, but guess what; now the pain of programming is gone! Slowly I was swallowed by PHP until the influence of booleans and arrays made me forget my visual gold age; the "re-coding" of a designer into a programmer was successfully complete. But even now, the spring of creativity couldn't be suppressed. Rather than being expressed in visual terms it permeated the making of TYPO3; programming is an art! Programming contains love and passion for beauty just as much as photography or oil painting does.
Goodbye World, Hello GPL When I realized that running a company like Superfish was not my cup of tea, nothing mattered more than my creation, TYPO3. I left the company with the rights to the code, my partner kept the rest. I felt I had passed some kind of "Point of no Return" and all I wanted was to finish my work. For what purpose? That question wasn't even asked at the time. I agreed with myself to do just enough freelance work to live and put the rest of my time into finishing TYPO3 over the next six months (it's funny to look back at the repeatedly naive time-estimates I have made in the past— and still do :-). During my short flirtation with the commercial production of TYPO3, I realized that commercial pressures tend to corrupt the quality of the product; ready or not, it has to go on the shelf to generate income. That was one thing I couldn't accept as an artist; I believed in quality, and compromise in this area was no option to me. On the other hand, with no company behind I could probably sell my CMS solution to only a handful of local companies. Compared to the perspectives of sharing TYPO3 with a whole world and thereby helping thousands of people, the latter would far outweigh the joy of making a bit of money locally in Denmark—even if I never saw a single Euro coming back. So I chose the GPL way.
Living Waters Giving away TYPO3 for free also has a strong root in my faith in Jesus. I have been raised in a Christian family and always believed in God. But passionate faith can't be inherited and my most recent "conversion" happened after having worked 16 hours a day for a long time. I think many of you reading this book know the situation and how passion can drive you into intense work. It can be fun and rewarding. But in the long run it dries you out inside, and eventually you ask yourself, "What is the point; what am I living for?" This is where some people burn out and get depressed. For me it triggered the logical question; if I really believe in the Bible, why not open it and read about what a balanced life should be like? This had a dramatic effect on my life. I began to take my faith seriously and re-align my actions with my beliefs. I met my wife, Rie. And I discovered my identity and some personal gifts, so I could understand my "mission" in life. I also thought about how to live in a Christian way in the modern world. I read "feed the hungry" and found that a useful tool like TYPO3 would be just that. I read "love your neighbor" and found that sharing TYPO3 as the best I had would be an act of love. I read "seek and you shall find" and thought that TYPO3 could be just such a reward for those who dare to search for alternatives. I read "you got it for nothing, give it for nothing" and thought that TYPO3 was possible through a talent I could only attribute to God, so what would be lost by giving it away?
Reasons to Believe Mixing TYPO3 with Jesus must seem strange to most of you. Why would an apparently intelligent guy believe in something fuzzy like God? But in fact I think programmers have nothing but good reasons to conclude that some kind of higher intelligence must exist. Every day I spend hours writing characters carefully combined into a computer program. I know that a single misplaced byte will make TYPO3 fail to run. I also know that sometimes I need to make an internal redesign that does not add new functionality to TYPO3, but merely opens the possibility of further development. And who would believe me if I claimed to have created TYPO3 by repeatedly combining random bytes and trying to execute them until something useful came out—even if doing this a trillion times? TYPO3 required conscious, intelligent design! I have to admit that the complexity of life points to something outside the universe itself. It doesn't put a name tag on who is behind it all, but there are good reasons for believing in a mastermind. I declare that I am not a perfectionist. Perfection is not obtainable for humans, it is an ideal. And although the ideal of perfection is our beacon of light, we have to settle for less. What is obtainable is completeness. Completing what you have started is what gives the first step you took a meaning. TYPO3 is my baby, it takes enormous amounts of my time and often it consumes most of my awareness. When people ask me about TYPO3 and my own working life, I ask them to think about how it was preparing for exams or writing a large thesis at university. I believe that captures the intensity of how my life has been for the last four years, while TYPO3 has been a public project. It has been a privilege, fun, and challenging all along, but it has also worn me out. The most precise way to describe this state is to compare me with a fragile ecosystem. Even small changes in the environment can have great impacts on stability. Luckily, I have developed an equally good understanding of my inner self and daily I try to walk the roads that motivate, rather than those which lead to despair. I have learned to focus on single issues, and suppress the view from the top of the mountain, which can be overwhelming. I have had to trust myself to be right many times, when it would have been fair to have doubts. And I have learned to strive for perfection but settle for something complete, and sometimes less. It's a strategy of survival, and without it the wave you are surfing will swallow you.
Growing a Community It's easy for me to remember for how long I have been married to Rie; I just think about when TYPO3 was first released to the public—that was also in August 2000 :-). Anyhow, the launch of TYPO3 to the public was supposed to be the end of the line but it became a whole new beginning! At the time, I was exhausted after developing for a year on my own with no external response. I remember how lonely I felt. Publishing TYPO3 under GPL changed all this and the growing community became a solid source of power that changed the whole perspective of the project; suddenly my work mattered to someone! This was a fulfilment of my personal "prophecy" that giving TYPO3 away for free would be much more valuable than selling licenses to local customers in Denmark. In addition, the new situation greatly compensated for the loneliness in the office, since I now had virtual colleagues all around the globe! As an Open Source project, a small community quickly grew up around TYPO3, including René Fritz (co-author of this book) as one of the very first personalities on the scene. People contributed by
setting up mailing lists, archives, providing support to others, creating small plugins, offering help to port TYPO3 to Windows, and most significantly, translating TYPO3 into their native languages. In April 2001, Rie and I conceived the idea of arranging a snowboard tour for the community, and the next winter, we did it! 25 people showed up and suddenly e-mail addresses had faces. The first snowboard tour was an amazing event and Jan-Hendrik Heuing would still quote me for saying "I'm starting to believe in it" back then. The year after we were 50 people snowboarding on the slopes of Splügen, the next year we were more than 80 gathered in Kitzbühel. More than anything else, the annual snowboard event has become the identity of the TYPO3 community.
Life in the Bazaar The community of TYPO3 has grown at an exponential rate ever since. From being a small village where everyone knew each other on the mailing lists, it is now a big city with all that entails. The manpower to help is far greater but the risk of getting impersonal is equally high. I often receive e-mails from people asking me support questions. I have to delete them flatly. Even answering back that they should use the mailing list can become stressful to me and it really breaks my heart, because on the other hand I hold the ideal to be personal to everyone. But today I have to trust that the community will take good care of the newbie asking for guidance, while I optimize my time for general development, which helps thousands, rather than a single person. The growth of the community also holds great developmental potential. Centered on code contributions via the Extension Repository, it is directly possible for anyone to contribute quality code to the system in a safe way, which protects the integrity of everyone's work, as well as their motivation for contributing. My greatest vision for TYPO3 is extensions. I strongly believe they are the perfect vehicle for bringing broad innovation to the project and offering maximum freedom for every developer to demonstrate his or her personal love for the art and beauty of coding web applications. This is the democracy of our community and everyone has equal chances. The challenge we face, as I see it, is to maintain the friendly atmosphere for which we have traditionally been known. We also have to maintain an effective framework for contributions from the growing number of code authors and apply more quality assurance to contributions of all kinds. In another field, we have realized the need to enforce the GPL license, as TYPO3 has become a popular software that obviously would be nice to re-brand and sell as one's own work. And finally, we have to fight the prejudiced minds that think Open Source has nothing to offer, since there is no fee to pay.
Credits So many people truly deserve to be mentioned here. Unfortunately, any attempt to list some names would exclude others equally merited. It is like inviting people to your wedding; it's not hard to invite your best friend, but it is hard to find the criteria to decide whom you will exclude, since there is not room for everyone. However, it will be safe to mention my wife, Rie. She is my best friend; she loves me and challenges me. She prays for me and we share faith in God. She has followed TYPO3 all the way and supported every bit of it, often with personal sacrifice when I was stressed out and mentally absent. She has accepted that she is second choice at times, and we all owe her big time for that.
I want to mention Christian Jul Jensen (Denmark) who has been my good friend and mental support through the years, and also my right hand in professional matters. Christian has been my personal proxy for a while, taking the load from my shoulders as times changed and TYPO3 needed more of my dedication, rather than me helping old customers. His help has been priceless. Daniel Hinderink is another cornerstone in the history of TYPO3. Daniel is professional and very skilled. In addition to this, he has been a showcase of proactivity to me. Daniel has taken the initiative and become the solution to problems, rather than a part of them. As the coordinator of marketing efforts for TYPO3, he carries a lot of the responsibility for the marketing success TYPO3 has had. But his initiatives have borne even more fruit in areas such as initiating innovation, team building, and project organization. I am impressed and thankful! Now the list of names would explode if I wanted to thank everyone who has contributed to TYPO3 with code, support or has otherwise been active in the community. Money is good but sharing your talents in the community is worth even more! Thank you so much everyone. I hope you can recognize the value of sharing the best you have got with the world, as my experience described in this preface has been, and I encourage you hang on in there! I have received an increasing amount of money donations during the time TYPO3 has been public. To everyone who has sent money I also want to say thanks from my heart. You have enabled me to spend more and more time on TYPO3 rather than doing irrelevant freelance work. Your donations prove how many small streams make one large flood that eventually can power an Open Source project into stable and continual development. I encourage you to stay true to your promises of financial support so we can employ more people developing TYPO3 in the future! I also want to mention Dassault Systemes web department in Paris for their generosity and the inspiring friendship we have shared during my times in Paris. Through their belief in TYPO3, they have supported the development in countless ways. Finally, I want to say "Hello" to all my future friends in the community! TYPO3 and the snowboard tours are a social pit-stop for me. These relations somehow make the hours behind the screen less lonely and in some cases spark real-world friendships like the one I have been so lucky to establish with Robert Lemke from Luneburg.
Three Men in Blue Overalls To me the third snowboard tour in 2004 was a fantastic experience. I saw old friends again, I got my own snowboard this time, and I met many new and inspiring people. And finally it demonstrated the powerful initiative of the "self-ignited fireworks" that has popped up in the community. The men in the mirror finally jumped into their blue overalls and began work. Even though the history and status of TYPO3 is more than I could ever ask for, I always joked about the day when there would be a book about TYPO3 on the shelves in my local bookstore. Three talented community members have now made this dream come true. They asked for a book and found the answer to its creation in their own mirror reflections. I am thrilled about the outcome and thankful for your contribution to the big picture of completeness we are striving for. Enjoy the book and welcome to the TYPO3 corner of cyberspace! — Kasper
Authors' Introduction TYPO3 is an extremely successful Open Source Content Management System, with a reputation for being very powerful but also complex. With this book we have tried to draw an overall picture of TYPO3, providing an insight into how it can be used by users, administrators, and developers. In view of the numerous references and a number of tutorials, the question was raised as to what this book can achieve. The flood of questions in mailing lists has apparently not been dammed by the existing documentation. After considerable observation of the problems and typical questions, we decided to write a book that attempts to illustrate the principles of TYPO3 and demonstrate its practical application through examples. This book should not be seen as a replacement for the references and tutorials on TYPO3.org; it should rather be a connecting link for developing a coherent picture of TYPO3 for beginners, users, and developers, allowing them to navigate on their own through the flood of information. The TYPO3 project attempts to divide all layers of documentation and communication into three groups, to simplify navigation. This book will do the same: 1.
Editing: Provides the means of the system for production and describes methods for their effective use. 2. Administration: Involves the organizational tasks that are necessary to implement content management using TYPO3. 3. Development: Describes the creation of a website and its graphical interface using templates, as well as programming your own applications in the TYPO3 framework. For decision makers who are not yet familiar with the topic of Content Management, and in particular with Enterprise Content Management, we provide an Introduction at the beginning of this book; during the course of the book we regularly return to relevant issues, in terms of the various task areas in the company process. Chapter 1 and Chapter 2 primarily deal with the theoretical basis of content management. With this background, the advantages of TYPO3 become clear, and from this we can form the basis for decisions on its strategic use. In addition, these introductory chapters take readers who have no previous knowledge on an excursion through the subject, presenting the most important terms and concepts. This is followed by installation and configuration of TYPO3 in detail. In Chapter 3 we demonstrate the system using practical situations of content production. A complex tool must prove its value in a particular way, through the user-friendliness of its interface. After presenting the TYPO3 options and their functions, the section closes with a practical example on working effectively with TYPO3. Chapter 4 deals with the administration of the system, and then with adjustments to conditions and processes that are defined by producers in their work with the system. In doing so, we show, using examples, how the means available intertwine, and how they are used in practice. Chapter 5 describes the production of websites using TYPO3. Starting with the installation, we discuss the programming of templates with TypoScript and see the different methods available.
In Chapter 6 and 7 we introduce the extension interface of TYPO3, the Extension System, describing the basics and ways to develop your own functional extensions in the TYPO3 framework. Here we can observe, from a developer perspective, the integration with core functions and the different parts of the TYPO3 architecture that can be extended. The entire text is annotated with footnotes and so-called "softlinks". The footnotes are aimed at encouraging further reading in areas not directly involved with technical aspects of TYPO3. The softlinks connect the book to TYPO3.org and other resources. By entering the number code on the TYPO3.org website (http://www.typo3.org/book/) you will be taken to the corresponding topic in the online documentation, or to sources going into more detail. In this way, technical references and documentation are included, which are as up-to-date as possible, but the reader is also introduced to the thematic structural online resources, providing him or her with a sense of orientation in an ever-growing profusion of information.
About This Book What You Need for Using This Book You will require TYPO3 installed on a web server that has PHP4 and MySQL installed. Some extras you may need are ImageMagick, GDLib/Freetype, zlib, and a PHP accelerator, such as Zend.
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 listings. Code words within text are shown as follows: "If we want to change the background color to a nice gray, we can go into the plone_styles layer and customize base_properties." If we have a block of code, it will be set as follows: $result = $this->query($query); $row = $this->fetch_array($result); $result = $GLOBALS['TYPO3_DB']->sql_query($query); $row = $GLOBALS['TYPO3_DB']->sql_fetch_assoc($result);
When we wish to draw your attention to a particular part of a code block, the relevant lines or part will be made bold: headerimagetext
New terms and important words are introduced in an italic-type font. Words that you see on the screen—in menus or dialog boxes, for example—appear in the text as follows: "Clicking the Next button moves you to the next screen". Any command-line input and output is written as follows: mysql> create table books (name char(100), author char(50)); Query OK, 0 rows affected (0.03 sec)
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 e-mail 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 e-mail [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 code 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 also 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 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.
1 Introduction This book is based on the original German version, which has seen several updates for various sections. This is mostly because of changes to the TYPO3 core in the last two versions (3.7.0 and 3.8.0). A certain amount of other differences stem either from errors that have been corrected in the English version, or from structural changes due to the circumstances in the UK and US markets. The authors would like to thank all German readers for the many helpful comments and hints and of course the considerable success that the book has been. More thanks are in order for the community that supports us, starting topdown with Kasper Skårhøj, the members of the TYPO3 association, and all the people in user groups, mailing lists, and supporting consultancies.
1.1 History Kasper Skårhøj, born in 1976, had already been working since the end of 1997 for the Copenhagen start-up company "Superfish" on one of the very first content management systems. Two years of development, a trip to the Seybold trade fair in San Francisco, a number of practical projects, and several meetings (with Internet-Guru David Siegel) later, he realized that "Superfish" was not really the right or ideal environment to continue developing TYPO3. On the one hand this was because "Superfish" was moving in a new direction in the type of services that it provided, but more important was a reason that is all too familiar to many software developers: the pressure of deadlines to get new versions ready for the next trade fair, and the general tendency to give more importance to the visible parts and neglect
1 Introduction
the invisible ones, which in the long-term are more important as far as quality is concerned. The consequences that Kasper drew from this situation are by no means the standard ones: while most Open Source developers of the first generation grew up in a university environment -- Linus Torvalds being a prime example -- Kasper decided to give up the security of a flourishing company, in which he also had a partnership, to work full-time on his vision of a content management system. A year later, having done nothing except work on the implementation of this vision, version 1.5 appeared. That was in July 2000. The development of TYPO3 remained a one-man show until July 2002, with the crucial advantage that quality and consistency remained on a very high level. One disadvantage lay in the fact that further development and a number of features had, in this respect, to pass through "the eye of Kasper's needle". After a number of discussions on the mailing list, followed by a phase of frantic work, Kasper published a new version in 2002, version 3.5b1, which, with its new Extension Manager, immediately transformed TYPO3 into a modular system. Since then the community has continuously published new extensions, allowing the range of functions for TYPO3 to increase rapidly. Softlink 314624
As a consequence, project groups have been formed which are working on all areas of TYPO3. At the core of the project, Kasper Skårhøj is still responsible for releases, and works personally on solving quite a number of problems. It should not be forgotten that his commitment essentially depends on whether it is economically viable for him to concentrate on these topics. This is why contributions and consultation work on large commercial projects are crucial for the TYPO3 project so that it can continue to be able to afford its most important specialists.
1.2 What is a CMS? Content management systems have become the standard for creating and deploying mission-critical content on the World Wide Web and intranets. Software systems with this scope are usually referred to as Web Content Management Systems (WCMS), or Content Management Systems (CMS) in short. When aiming for an integrated end-to-end approach on content, reaching from document management to web but also print output, such systems are named Enterprise Content Management Systems. 2
1.2 What is a CMS?
1.2.1 Separation of Content from Layout An important basic principle is the division of content and layout. In practice this means that the definition of layout is stored independently of the actual content, be it text, images of other formats. This principle has many advantages when it comes to changing the layout, or protecting the layout from eager content authors. While the content can be edited by authors, without any influence on the details of display, the layout definition can be edited independently, thus effectively enabling design changes across even very large websites.
1.2.2 Content Lifecycle Functionality Content Management Systems support the Content Lifecycle depicted below through all it’s stages, from creation of contents with Editors to organizing content snippets (assets) to actual deployment when published and finally archiving content elements.
Figure 1.1: Content life cycle
Activities in the creation phase have the acquisition and design of information as their goal. After planning, relevant information is written, structured where applicable, and made available as components. This phase also includes editing and didactic refinements added by authors.
3
1 Introduction
The organization or preparation stage involves administration and storage of content in a scheme suitable for information products and sources, as well as making available and assigning user permissions. Publication refers to distribution and presentation, that is, the output as an information commodity. This can be implemented as a website, a printed product or in another output format. The archiving stores the content in a manner which best serves the purposes of research, statistical evaluation, and ultimately re-use.
1.2.3 Modularity TYPO3 is one of the systems that have modularized the functionality in several layers. From storage to deployment, these layers describe classes of modules. The storage level contains an API for connecting TYPO3 to different Databases or enables storage in XML-files via so-called handlers using the database abstraction layer. On the other end TYPO3 established an API for extending the core software, aptly named the “extension” system. These extensions connect to TYPO3 through the TYPO3 extension manager, which also serves as an IDE. Extensions can add functionality to all levels and interfaces of the software, without changing the core and thus ensuring easy updates and a stable code base. All serious vendors of content management software have adopted this modular approach, and so have Open Source systems like TYPO3, albeit pursuing different technical concepts considering the individual API.
1.2.4 Target Group In a relatively short time, TYPO3 has expanded very quickly, very far. In terms of numbers, the strongest user group is small and medium-sized companies, of course, because TYPO3 is often still too powerful for private use, and it is also difficult to learn. Softlink 027059
Companies that can buy entry into the TYPO3 world through the services of suitably qualified specialists can, however, appreciate the advantages of Open Source software in general, and TYPO3 in particular. The reasons most mentioned include the license (GPL), quality, the extensive documentation, the rapidly growing community and the many references from renowned companies and organizations. A selection of these is published on TYPO3.com, under the soft link shown here. Among the approx. 122,000 installations that have logged in to the TYPO3 Extension Repository between July 2002 and the beginning of 2005, there is
4
1.2 What is a CMS? a large number of well-known names and famous brands who have put their faith in TYPO3, proving the validity of Open Source enterprise systems by using them in intranets and other critical areas.
1.2.5 TYPO3 References The list of reference entries at TYPO3.org represents a cross-section of all the TYPO3-based projects entered there.
Softlink 589606
Among the agents providing services, there are a number of leading names from Germany and the rest of Europe, but also many small and medium-sized companies that see an opportunity to compete on a technical level with larger providers, offering attractive prices and project turnaround times.
The GPL: GNU General Public License The GNU General Public License is the most widely used Open Source license. Its seemingly simple content, however, continues to cause contradiction in different countries, and with different legal systems. One legal opinion follows the next, and because the software is handed over free of charge, issues are raised concerning consumer protection, warranty regulations and the interests of programmers, which can be of significance, depending on the field of application and how critical the use of the software is to a company. So it is advisable to find out about the contents of the GPL, and its legal consequences, in the country where it is to be used. Where appropriate, claims of warranty towards an agency or a technical service provider who takes over or works on the implementation, must be regulated. The extensions take on a special role, and as long as they cannot be operated as an independent application, they are also subject to the GPL. A function that is deeply anchored in the TYPO3 framework, that is normally set up as an extension, and that is not just a wrapper or script around an existing program, will equally be subject to the conditions of the GPL, and is Open Source. This means that the author is not obliged to publish, but also cannot prevent publication once it has been passed on, perhaps to a customer. Neither can the author restrict modifications or further modification by others, once they have come into possession of the code. As far as economic interests are concerned, problems may arise in terms of utilization for some producers who are used to thinking in terms of commercially viable products. 5
1 Introduction
But one should bear in mind that TYPO3 has been provided as a basis for such developments, in just the same way, license-free and cost-free. De facto, the community in our case reacts in two different ways: Many extensions are not published; of the registered extension keys that are necessary for exchange via TYPO3.org, only about a fifth are published extensions. This does not include many unregistered extensions, but does include many unfinished extensions, and ones too specialized to justify publication. It is certainly very unlikely that customers will themselves publish extensions that they have obtained from an agency. Many TYPO3 specialists use several different projects to create and further develop an extension, until their investment in time and knowledge has been returned, and only then publish their work when it may also create promotional value.
1.3 The TYPO3 Community The TYPO3 community is a rapidly growing and increasingly international community of TYPO3 enthusiasts and users. The core of the community is represented by mailing lists -- above all, the main english mailing list, which can also be subscribed to via newsgroup. Consult TYPO3.org for details on the mailing lists. The community ensures, as in most Open Source projects, that support is available, offering quick and practical help, even for more technically complicated problems, as long as the standard "rules of etiquette" and precise formulation of questions are observed. It is important to read the archive, FAQs, and beginners' help documents, so that you don't clog up the lists with questions that have already been answered many times, something which can annoy experienced users. Please remember that the help you are getting is voluntary and unpaid, and that you have no automatic rights to it. Softlink 139514
6
Anyone who needs higher availability, training material, or who has more complex questions should get in touch with one of the many service providers who can be found under TYPO3.com in the "Consultancies" area. The companies listed here represent a cross-section of the entries in TYPO3.org, which have been selected according to criteria of competence demonstrated in their projects.
1.4 The TYPO3 Association
Anybody who has already built up relevant TYPO3 know-how will perhaps want to be useful in further developing documentation, or contribute to the project in some other way. The project comes alive from such contributions at all levels, so that help and feedback are very welcome, and are discussed at length. If you want to do this, it is important to get a general impression beforehand of what topics have already been discussed, and with what results. For this purpose we recommend that you visit the archives of the mailing lists on TYPO3.org in the field of Documentation/Mailing-Lists/. Depending on the subject, you may need to look in the Developer lists, the Marketing list, or another mailing list.
Softlink 314623
Then you should make sure that a project with a similar, or overriding, objective does not already exist. Under TYPO3.org, in the Development/Projects area, you can find a list of all current projects and work areas, with the corresponding contact partners. A special feature of TYPO3 and the community is that many of the participants have already met up, most of them in the context of the annual meeting, the TYPO3! Snowboard Tour, which attracts more and more participants each year.
Softlink 424461
Apart from the discussions, work-intensive evenings and many questions which are answered, as well as projects launched here, the focus is also on getting to know the people behind the mail addresses, and not least on enjoying winter sports together. So whoever wants to combine intensive know-how with leisure time will hardly find a better opportunity than at this event. Due to the extensive use of TYPO3 in organisations and the very large community the first international conference was a question of time. It will take place in September 2005 in Karlsruhe/Germany and has been named TyCON3. For more Information, visit the following website: http://tycon3.typo3.org
1.4 The TYPO3 Association In November 2004 a group of people from the TYPO3 community including Kasper Skårhøj and other long-term contributors prepared and founded a non-profit organisation called the TYPO3 Association. The main goal is to support core development on a more steady basis and improve the transparency and efficiency of various aspects of the TYPO3 project.
7
1 Introduction
1.4.1 Goals and Objectives •
Organisation of events for the purpose of information and education of its members;
•
Communication with its members and the general public, to spread and further knowledge and proficiency for the usage of the TYPO3 software, especially by virtue of it’s project website;
•
Education and certification to ensure quality of service;
•
Fostering development of TYPO3;
•
Supporting the adaption of international software standards within TYPO3;
•
Representation of the members;
•
Public Relations and activities helping to spread knowledge and usage of the TYPO3 software.
1.4.2 Membership and Application The TYPO3 Association has two types of members:
Active Members Active members are people that have consistently worked for TYPO3 and are willing and able to attend general assemblies, where they have the exclusive right to vote and decide on the Associations future. Active members are appointed on a basis of merit and need to be recommended by two existing active members, or a fifth of the general assembly.
Supporting Members Softlink 394945
Supporting Membership is open to everyone, but requires formal application. The Association provides an online application form and payment method of membership fees at http://association.typo3.org. Members are either people or companies and are required to endorse the goals and objectives of the Association through their actions. All Members will be entitled to exclusively advertise their membership and thus support for TYPO3 following admission to membership.
8
1.4 The TYPO3 Association
Bodies and Practical Work The Association consists of the following bodies:
Board The board is the executive body taking care of daily administrative work and legal matters and accounting.
General Assembly The GA is the highest authority and elects the board, controls their work and generally decides on all matters of importance in its annual meeting. It is open to all members, but only active members have the right to vote.
Committees Committees are the groups that do the actual work when it comes to discussing the usage of funds, community communication, education, events, and so forth. Legally they are appointed by the board and the GA and make recommendations, which are then executed by the board.
9
2 Installation In this chapter we will introduce variations and the recommended fields of application for various installation types, and describe the necessary steps to implement them. With the many thousands of installations of TYPO3 already made, you would think that the installation hurdles are not actually set too high. However, the authors of this book can also tell a tale about "the first time" and of some of the problems that might throw the beginner off course. Finally you will find an overview of some resources available to you that are rich in content, to find answers to any problems you may have.
2.1 Criteria for System and Package Selection TYPO3 requires just a database and a web server that is PHP-capable; on this basis, details such as the hardware used, the operating system, the database system, and the web server can be selected using various criteria, the most important of which we will explain here. A basic decision you need to make concerns the operating system. TYPO3 can run on most UNIX-based variants, and on Windows systems. There is no difference in the scope of the two versions in terms of core functionality, although a number of extensions do require UNIX programs. Please consult the documentation for the relevant extension, so that such restrictions can be considered. 1 One technical advantage of using UNIX systems is that updates are
1 Indexed Search, for example, a powerful search engine in the TYPO3 framework,
requires UNIX software to index documents. Various services of the DAM also need this, as do the PDF converter extensions.
2 Installation
considerably faster, which is made possible by so-called "symbolic links".2 The dissemination of knowledge through the community is also important. The trend, certainly in terms of numbers, is dominated by the use of Linux systems, and to this extent support and operating system-dependent new development for extensions are much more widespread for this system. So if there are no compelling counter-arguments—such as a predefined Windows-based infrastructure, or your own (lack of) knowledge—the Linux variation makes the better choice, from a TYPO3 point of view. In the following sections you will find further information on hardware and software selection in terms of the web server, the database system, other useful software, and finally the package selection of TYPO3 itself.
2.1.1 Hardware As PHP-based software, TYPO3 at the minimum requires hardware equipment capable of running a web server. Even though this may still be possible with old 286 and 32 MB RAM machines, these cannot provide a useful platform for operating a TYPO3 system. The system should have 512 MB RAM or more in order to provide a solution with adequate performance. If you want to use your own server, consider the following factors when sizing your hardware:
Type of Usage The decisive factor is how the information provided on your website is to be used: will the website be mainly, or completely, static? Do you want to operate a portal and do you need dynamic content generation on the web server? Are you planning an application to be made available to normal visitors to your site, such as a shop, eCards, or forums? The following basic rule applies: More functions operated on the web server translate to increased hardware requirements and expense in separating the live system from the production system.
Expected Capacity A number of parameters can be expressed in numbers:
•
How many users will use the system at the same time?
2 This can now be remedied by the use of Junction, an additional software package,
see soft link 394 945.
12
2.1 Criteria for System and Package Selection
•
How fast (in seconds) should the server deliver a page?
•
How many pages per hour do you intend delivering?
•
How many page impressions do you expect per month?
•
How much data traffic, in MB or GB, do you expect per month?
If you do not know the appropriate values, you will find it difficult to make a well-based decision. If you have any doubts, try to make contact with operators of similar services to collect relevant information. We shall look at three very typical scenarios:
1. Small to Medium Performance Requirements These include sites that do not economically justify the costs of having their own server, expect no more than five to 10 users in parallel in the back end and 50 in the front end, a page delivery of up to 1.5 seconds, no more than 100 pages per hour, and less than 100,000 page impressions per month. In all, you expect data traffic of less than 5 GB per month. If your profile matches this in certain critical points, you should look around for a good and cheap hosting provider, who might even provide preinstalled TYPO3. If you decide on a solution without preinstalled TYPO3, clarify beforehand whether the necessary requirements for installation are fulfilled:
•
At least 100 MB free memory space
•
MySQL database
•
PHP from version 4.3.x with GDLib and Freetype
•
ImageMagick
•
Access via SSH
A few notes of warning at this point: for a long time now, miraculous abilities are no longer needed to hire out web space. Through cheap offers for dedicated servers, in principle anybody who has a few Euros and a month to spare can set up store as a reseller and hosting provider. Knowledge and ability are not mandatory requirements, and this can sometimes have dramatic consequences. The hosting business is subject to the same economic constraints as any other business, and low-level prices are almost certainly linked to one or more of the following: 1. Poor knowledge of the material, since someone with experience in this business knows that server downtime can cancel out the earnings of months 13
2 Installation
2. Low personal costs, since the commodity itself is purchased from one of the mass providers (with correspondingly little room for maneuver for your contract partner) 3. Size of provider—due to its large size, it is worth employing experts Of course, it is perfectly legitimate to search for as cheap an offer as possible. Just take into account the fact that at such low prices you cannot expect an optimal service and protection of values, with respect to installation and content in your CMS. To proceed carefully, and at least have a basic level of security (and a supplier who is in liquidity and from whom you can seek compensation), you should pay a fair price, probably not below 25 Euro per month. It is here that you may be able to benefit from smaller providers, who can offer an individual service and be a reliable partner with whom you can trust your work. Irrespective of the price class in which your project is located, a situation without an automatic backup must never occur—make this one of the fundamental criteria on which to base your decision.
2. Medium to Large-Sized Requirements and Intranet It is a good idea to have your own web server if your CMS application justifies the expense for operating and setting it up. In doing this, the price for renting such a server and/or for co-location or housing will constitute the least of the costs to be expected. Most studies yielded a ratio of 35% to 65% in the distribution of costs between purchase or rent on the one hand, and maintenance and other running costs on the other. In the intranet, you have no choice but to run your own server. The key question here is that of sizing. A sound calculation, which also takes into account growth through scaling (two servers are not just 10 percent more work than one server), is very advisable so that you can arrive at a balanced decision. The generally accepted formula of calculating overall costs during the lifecycle of an investment commodity, the so-called total cost of ownership, is (for this example) calculated as follows:
14
2.1 Criteria for System and Package Selection The TCO "Iceberg" visible costs + + + +
capital expenditure HW/SW purchase price installation implementation
+ + + + + +
system adoption support administration training maintenance degree of non-usage
invisible costs
____________________________________ = total cost of ownership
This calculation model has become very refined indeed 3, but for demonstration purposes and a rough assessment of the actual costs of an operation, the above list is normally sufficient. If your calculation indicates making a decision in favor of your own server, the following technical points should be clarified: performance capability of the hardware, its ability to be updated, availability of replacement parts, backup strategy, and security (access restrictions, etc.).
3. Heavy-Duty Operation In heavy-duty operation, above one million page impressions per month, the standard solution is to combine a number of servers into a cluster. The reason for this lies not only in the spread of the load, but also in its fault tolerance. Depending on the purpose it is used for, the maximum load the server has to cope with can be exceeded even with a small amount of traffic. Also, the task conditions of the application may not allow—for example in a management information system—any downtime. And yet web servers and database servers can also be operated separately and separately scaled, depending on the load to which they are subjected. Scenarios exist both with 10 Apache web servers, each with its own hardware and one MySQL server, as well as ones with 3 Apache servers and 5 MySQL servers. Whatever the case, special solutions are required here which require
3 Cf. Bensberg/Dewanto: "TCO VOFI for eLearning Platforms", http://www.campus-
source.de/org/opensource/docs/bensbergVor.doc.pdf
15
2 Installation
precise planning and implementation, as well as continual maintenance.
2.1.2 Web Server Softlink 504537
In theory, TYPO3 can be operated with Apache, IIS, or any other web server that can run PHP. The most common combination, according to numbers of installations, is Apache and PHP. Each particular version and installation type of PHP has, to some extent, an influence on TYPO3, which will be described in the "Server Compatibility" section on TYPO3.org.
2.1.3 Database The standard database for TYPO3 is MySQL, for a long time the only option. Because the database abstraction that has now been introduced uses MySQL-compatible SQL instead of a meta language, this combination still provides the highest performance, since database queries do not have to be transformed. In addition, many existing extensions use their own database queries, so checks need to be made in individual cases to see whether an extension is fully functional without having to make modifications to other databases. The decision to choose another RDBM system instead of MySQL should be considered very carefully; ultimately the costs of installation and updates will for the time being be greater than for the standard setup. An interesting variation on the use of other databases is to combine different systems, so that specific data is kept on your own database system, and this store is made available for use in a specific application in the TYPO3 framework. In this way data can be integrated directly from other database systems, and the disadvantages of replication or synchronization of data stores avoided. The database abstraction is not in the least restricted to RDBM systems—flat files such as XML data can also be addressed via SQL queries. Softlink 613803
16
Below we shall only cover the standard situation with MySQL, as more information for other scenarios is not yet available now. However, the documentation of the Database Abstraction Layer system (DBAL) does provide a number of hints (see soft link).
2.1 Criteria for System and Package Selection
2.1.4 Other Software Two software packages are necessary to be able to use the imageprocessing functions of TYPO3. These functions are entirely optional; TYPO3 still works without graphical processing and without these packages. The first package is GDLibrary, a PHPextension, which itself can be extended by Freetype with functions for representing typefaces. GDLibrary is already included in the standard PHP installation; it will not be discussed separately here. The second software package, used predominantly in the scaling and generation of image file previews, is ImageMagick. With TYPO3, using an older version of ImageMagick (Version 4.2.9) is recommended, as it has a number of advantages over later versions. 4
Softlink 353034
TYPO3 can be used with current versions of ImageMagick if the disadvantages in functions for masking, sharpening, and softening of images do not affect your website. The recommended version 4.2.9 is available for download on the TYPO3.org website under the soft link shown here. Current ImageMagick versions can either be installed with the packet manager of your Linux distribution or downloaded from the ImageMagick homepage. 5
Softlink 436028
Alternatively you could use GraphicsMagick, an offshoot of the ImageMagick project, which pledges to maintain a more strict line to the API development. 6
4 A corresponding question sent to the development team of ImageMagick, asking
why objective disimprovements had been introduced in some areas, yielded no satisfactory response. The e-mail communication, explaining individual disadvantages, can be found under the soft link shown above. 5 http://www.imagemagick.com/ 6 http://www.graphicsmagick.org/: In particular the changing story of the
ImageMagick API has stopped many developers from basing their development on this software. TYPO3 went along with this capricious behavior of recent years, and the configuration options reflect the changes made in the list of exceptions for individual ImageMagick versions.
17
2 Installation
2.1.5 TYPO3 Package Selection TYPO3 exists in various different packages, depending on the use to which it will be put. The main distinction is initially between the two different operating systems: All UNIX packages can be found as so-called "tarballs" 7 and have the file ending .tar.gz. Windows packages can be found as zip archives, and have the .zip file extension. There is no difference between the actual files contained in each version. The difference between the two versions lies in the fact that the tar.gzdistribution may be smaller, because it does not have double folders, since these are represented by symbolic links instead. In the zip-distribution these folders exist twice, as shown in the screen shot.
Figure 2.1: left: symbolic links with their relations to the original files in the src directory right: relations of symbolic links to the original directories within the src directory
The double use of directories (using symbolic links) is essentially due to historical factors. You must bear in mind that symbolic links cannot be set up via an FTP access. If your access to the web server is limited to FTP, choose a zip-distribution. Softlink 394945
For some time now it has also been possible, through utility software such as Junction, to set up links in the file system (similar to symbolic links) in NTFS-formatted partitions of Windows.
7 Tarball is the name given to archives generated with the tar program (and usually
compressed with gzip as well). Symbolic links are supported with this file format.
18
2.1 Criteria for System and Package Selection
The TYPO3 version is always the most up-to-date one for all packages; they differ only in the examples they contain. Generally all tar.gz-packages do not contain the actual core system, which needs to be downloaded additionally as typo3_src followed by the version number. All zip-distributions include the system core. In essence, the TYPO3 project offers the following different packages for download:
QuickStart This is the installation for beginners and includes the beginner's tutorial. You should choose this package if you want to make use of the tutorial, since it includes material and defaults for the examples. You can also find the tutorial in the German version under the soft link shown here.
Softlink 995697
Test Site The Test Site contains a number of examples of TypoScript templates, menu variations, and extensions such as Shop, address lists, and news. For tests, and to get to know the system on your own by means of examples, this rather old package can be used—as far as the examples are concerned.
Dummy The Dummy package differs from the Quickstart and Test Site only in its empty database and the absence of example material. It is the standard package for experienced developers who are starting a new project with a clean slate. The included database dump contains an administrator account, which can be called after installation with the user name admin and the password password.
TYPO3 Source The TYPO3 source is a tarball that contains all the directories needed for running the base system. Zip-distributions already contain this source package by default. With the help of symbolic links, a number of TYPO3 installations (websites) can be operated using a single source. Corresponding extensions can be stored in the global extension directory typo3/ext/ or in the corresponding typo3conf/ext/ directory valid for that instance. 19
2 Installation
2.2 Installing a Test and Training Installation Softlink 056013
TYPO3.org provides a whole range of complete packages for various systems. We shall now take a close look at the two classical distributions, the WAMP (Windows Apache MySQL PHP) Installer for Windows by Ingmar Schlecht and the Quickstart package for Linux. There are other packages and installation guides for BigApache, Mac OS X, Debian, Gentoo, Mandrake, and others. A look at the download page and at the documentation matrix at TYPO3.org may also help you to find new ideas for the purpose of your installation.
2.2.1 The WAMP Windows Installer You will find the WAMP installer under the installer packages on the download page of TYPO3.org. It is very simple to use: 1. Load the installer onto your computer. 2. Open the file by double-clicking on it. 3. After a short time you will see a dialog asking you to accept the GPL. The GPL is a comparatively short license, which you should now read if you want to know about your rights. If you do not agree, this is the temporary end of your TYPO3 career: there is no other license agreement for TYPO3 apart from this one, and you must adhere to its conditions if you do not want to lose the right to use it. 4. Then a message appears that the installer will write all the files to C:\apache. Accept this only if you do not have such a directory, or if you want to delete the data saved there, since all data stored at this location will be irretrievably lost. 5. The installation is now finished. You will now find a new TYPO3 entry in your start menu with these options:
20
•
Start Apache: Starts the Apache web server
•
Start MySQL: Starts the MySQL database server
•
Stop MySQL: Ends the MySQL database server
•
TYPO3 start servers before: Calls up the TYPO3 front end in a window of your default browser under http://localhost
2.2 Installing a Test and Training Installation
•
TYPO3 (Alternative URL): Calls up TYPO3 under http://127.0.0.1
If you now start Apache and MySQL and call up the TYPO3 start page, you will find all the information you need on the front end and back end. The WAMP installer has already carried out the other steps of the installation, and TYPO3 is now ready for tests, and for your own programming attempts.
2.2.2 Linux (et al.) Quick Install If you already have a web server available that supports MySQL and PHP, you will reach your destination very quickly under Linux and other comparable *NIX-flavours, like BSD, OS X, etc.
Softlink 056012
If you have SSH access to the web server, you should log in there and download the Quickinstall archive from TYPO3.org, using curl or wget. The addresses are mentioned on the download page of TYPO3.org. If you only have FTP access on your web server, use the zip-distribution. Transfer all the files onto the web server in the directory from which your website will be provided (typical directory names are .../htdocs/, .../html/, or .../www/). You must now change some permissions so that certain parts of TYPO3 can be edited. If you do not have any access via SSH, you need another way of changing permissions. Many web servers have graphical tools to edit files, such as Cpanel, Confixx, or Webmin. If in doubt, ask your administrator or provider. The permissions of the following files must be changed as shown below: chmod chmod chmod chmod chmod chmod chmod
Beware: by making all the files world-writeable, security of your system could be compromised by other users with access to your server. You can consult section 2.3.1 for more information on how to set up a safe environment. You can call up TYPO3 from http://www.yourdomain.de/index.php on your web server. If you do not have a file called index.html in the directory of your web 21
2 Installation
server, you can omit index.php. Otherwise we recommend that you rename the file index.html, perhaps to index_alt.html. You can delete it of course, providing you no longer need it. Before the Installation Tool is called up in the so-called "1-2-3 mode", you will see a warning, which asks you to change the Installation Tool password immediately. Now enter a user name and password for the MySQL database and send off the form. Then you either create a new database or select an existing one. Please remember that all data contained in it will be deleted! Import the file quickinstall.sql into the database. You can now log in to the back end with the user name admin and the password password, under http://www.yourdomain.de/typo3. You can log in to the Installation Tool with the password joh316.8 Please make sure you change the Installation Tool password on your first log in! The basic installation for test purposes is now finished.
2.3 Installation for Productive Use The installation for productive use is distinguished mainly by selecting the package that only contains the source, without the example data, and takes up a minimum amount of space. In addition, the Installation Tool contains considerably more options than are available in the simplified mode. Not only is it essential to know this to be able to configure the system optimally, the options also provide a number of insights into the structure of TYPO3.
2.3.1 LAMP Installation As the most widely used operating system for web servers, UNIX/Linux is also a very good choice for using TYPO3. Especially when performing updates, the Linux platform has a clear advantage; there are a number of supporting software packages that are only available under Linux, and that are required for certain additional modules of TYPO3. So it really is worth taking a look at the online documentation for an extension before downloading and installing it. Below, we will assume a standard installation with MySQL.
8 For the curious: Kasper Skårhøj refers here to the following verse of John the
Evangelist: "For God so loved the world that he gave his only begotten Son, that whosoever believeth in him should not perish but have everlasting life".
22
2.3 Installation for Productive Use
Depending on the Linux distribution, there may be differences in the installation of Apache/PHP and MySQL. For image scaling and processing, ImageMagick is required. Alternatively you could use GraphicsMagick, an offshoot of ImageMagick. Please consult the documentation of your system or the relevant package manager. Whatever the case, you should ensure that PHP has at least 16 MB of memory available (this is set in the php.ini file) and also allows uploads of sufficient size (configured in php.ini and Apache). For the installation of TYPO3 you first require an empty MySQL database with user name and password, as well as one of the above described packages from TYPO3.org. There you can download the source and the so-called dummy distribution, which contains symbolic links and a configuration directory, and which will save you a bit of typing work on the command line. The best way is to open the download page for the desired package in the browser. At the same time, open a command line application (bash, term, putty) and make a connection via SSH to the web server: user@linux:~> ssh [email protected]
Change to the directory of your web server, which lies one level above the website directory: user@domain:~> cd /srv/www
Download the current version of the dummy and the source package. The correct address and the name of the file can be found on the packages page at TYPO3.org (see soft link):
and user@domain:/srv/www>wget > http://typo3.sunsite.dk/unixarchives/3.7.0/typo3_src/typo3_src-3.7.0.tar.gz
Here, srv/www/ stands for the directory in which the directory of the website (in our example, htdocs/) will be located. If necessary, consult the configuration file for your web server to find out the correct path. After downloading to the /srv/www/ directory, unpack the archive with the commands: user@domain/srv/www> tar xzf typo3_src-3.7.0.tar.gz
23
2 Installation
and user@domain{/srv/www> tar xzf dummy-3.7.0.tar.gz
Now move the files in the dummy-3.7.0 directory, with the command user@domain/srv/www> mv dummy-3.7.0/* htdocs/
to the htdocs directory, or the directory from which your website should be issued. You can now delete the archive and the empty folder: user@domain/srv/www> rm -r dummy-3.7.0 user@domain/srv/www> rm dummy-3.7.0-3.tar.gz
After this, if you call your htdocs directory with user@domain/srv/www> ls -al htdocs/
it should appear as follows: total 648 drwxr-xr-x drwxr-xr-x -rw-------rw-------rw-------rw-------rw-r-----rw-r----drwxr-x--lrwxr-xr-x
group group group group group group group group group group
714 204 621 4815 608 8087 134 46 136 18
11 Mar 22:13 . 11 Mar 22:00 .. 24 Jul 2003 Changelog 24 Jul 2003 INSTALL.txt 24 Jul 2003 PACKAGE.txt 24 Jul 2003 README.txt 27 Sep 2003 _.htaccess 7 Sep 1999 clear.gif 12 Dec 2003 fileadmin 11 Mar 22:05 index.php -> tslib/index_ts.php user group 12 11 Mar 22:05 media -> tslib/media/ user group 17 11 Mar 22:05 showpic.php -> tslib/showpic.php user group 16 11 Mar 22:05 t3lib -> typo3_src/t3lib/ user group 16 11 Mar 22:05 tslib -> typo3_src/tslib/ user group 16 11 Mar 22:05 typo3 -> typo3_src/typo3/ user group 18 11 Mar 22:05 typo3_src -> ../typo3_src-3.7.0 user group 204 16 Feb 2003 typo3conf user group 68 12 Dec 2002 typo3temp user group 238 12 Dec 2002 uploads
2.3 Installation for Productive Use
Run the following commands one after another to make the directories writable for the web server: chmod chmod chmod chmod chmod chmod chmod
Assigning 777 permissions is not without risk, however, since this gives access to all users of the system. It would be better to set the permissions to 770, if the user can be set to the name of the webmaster, and if the group can be set to the group name under which the web server is running. But this depends on the administrative options and the permissions on the web server available to you; 777 functions in all cases. Now release the security lock in the Installation Tool by opening the following file in an editor (in our example, vi, available on most Linux platforms): user@domain/srv/www> vi typo3/install/index.php
At the beginning, change the following line: die("In the main source distribution of TYPO3, the install script is disabled by a die() function call. Open the file typo3/install/index.php and remove/out-comment the line that outputs this message!");}
If you are using vi (or vim), enter dd followed by ZZ. You have now deleted the line, saved the file and exited vi. Alternatively you can comment out the line by entering //, if you want to reactivate the lock later for reasons of security. To do this, enter i to reach insert mode. After entering // at the beginning of the line, exit the insert mode by pressing Esc, and then :wq!, to save your changes and close the editor. In the browser you can now call the Installation tool, by entering http://www.yourdomain.de/typo3/install/.
2.3.2 WAMP Installation The Windows installation of TYPO3 requires a running WAMP system with an installed Apache web server with the current PHP and MySQL distributions. You can find installers for Windows at http://www.php.net/ or http://www.bigapache.org/. After installing Apache, MySQL and PHP, you should install ImageMagick.
Softlink 892286
25
2 Installation
This is also Open Source software; under the soft link shown here you will find a corresponding version of ImageMagick, optimized for use with TYPO3. You need Windows binaries (also called executables) for the installation if you do not want to compile the software yourself. Install ImageMagick on your computer and then you can continue with the TYPO3 installation. For this, download the dummy package in the zip distribution from the download page of TYPO3.org to your computer. Unpack the zip archive in the directory from which Apache will publish the website. Normally this is the following directory: C:\Programs\apache\htdocs\
In the next step the user permissions for the web server must be set, so that the user under which Apache is running can read and edit all the necessary areas . You must be able to edit the following directories: typo3\temp\ typo3\ext\ typo3temp\ typo3conf\ typo3conf\ext\ uploads\ fileadmin\
In the file typo3\install\index.php the line die("In the main source distribution of TYPO3, the install script is disabled by a die() function call. Open the file typo3/install/index.php and remove/out-comment the line that outputs this message!");}
must be deleted or comment out by placing // at the beginning of the line. Let's move on to the Installation Tool.
2.3.3 WIIS Installation The Windows Internet Information Server installation consists of seven steps:
26
1.
System preparation: To prepare the system, you should set up a
2.
separate partition for the web server, so that the permissions you have to set do not influence the permissions on your system partition, which could otherwise potentially jeopardize your system. MySQL installation: Load a current MySQL version from
2.3 Installation for Productive Use http://www.mysql.com/ to your Windows server, unpack the installation file, and follow the instructions. When the installation is complete you will see a graphical interface with the program WinMySQLadmin, with which you can set up users and databases. Create an empty database and a user for this database.
3.
ImageMagick installation (optional): The ImageMagick software is
Softlink 892286
also Open Source; and under the soft link shown here you will find a version optimized for use with TYPO3. You need Windows binaries, also called executables, if you don't want to compile the software yourself. 4.
PHP installation: After the PHP installation you should check a
number of settings in the file php.ini and adjust them where necessary. The php.ini file contains the PHP configuration parameters. The most important setting for the operation of TYPO3 is: memory_limit=8M
This should be increased to at least 16M (16 MB). The Installation Tool checks a number of other parameters, but in general these have been correctly set in the default configuration. 5.
IIS configuration: The IIS configuration contains no special
features in terms of TYPO3; the settings can either be taken over automatically by the PHP installer or carried out manually, as described in the installation guide for PHP. For reasons of performance, it is generally highly recommended that you operate PHP in ISAPI mode. 6.
Unpack TYPO3: The selected zip package is unpacked in the
target directory, usually F:\inetpub\wwwroot\, although the drive name may vary, of course. 7.
Assign NTFS permissions: Finally, permissions must be given to
both users under whom IIS is operated. These users are called IUSR and IWAM, to which their server name is added. The user IUSR_MACHINENAME needs read permissions for the entire file system, in order to carry out the PHP functions file_exists(), is_file(), etc., and not just for the directories in which TYPO3
is installed. This user must also be assigned read and execute permission for the program cmd.exe in order to run ImageMagick, where appropriate, and must also have read permission for the file php.ini. In the web server directory the following permissions must be assigned to the user IUSR_MACHINENAME: 27
2 Installation TYPO3
Permission
web server directory (normally: Drive:\inetpub\wwwroot)
Read
fileadmin\
Edit (with subdirectories)
typo3temp\
Edit (with subdirectories)
uploads\
Edit (with subdirectories)
typo3ext\
Edit (with subdirectories)
typo3conf\
Edit (with subdirectories)
C:\PHP\uploadtemp\
Edit
ImageMagick
Read and Execute
C:\Windows\system32\cmd.exe
Read and Execute
2.4 The Installation Tool The Installation Tool is essentially a graphical interface for editing TYPO3 system settings saved in the file localconf.php, in the directory typo3conf/. This file, as well as the entire localconf directory must therefore also be writable for the web server. Let's try to understand the functioning of the configuration system. At run time, TYPO3 generates cache files in the typo3conf directory, on whose configuration parameters TYPO3 operates. So if configuration data is modified, these cache files must be deleted for the changes to take effect. Normally this is done automatically, but if the sources are replaced, especially when downgrading the version, TYPO3 may not become active by itself, so the cache files have to be deleted manually. These files have names such as temp_CACHED_ps2268_ext_localconf.php. By adding /typo3/install/ on to the name of your domain, you call up the Installation Tool: http://www.yourdomain.de/typo3/install/. To be able to use the Installation Tool, a locking function must be removed from the script typo3/install/index.php. This has already been described in the section on the LAMP and WAMP installations. The default password for the Installation Tool is joh316 and should be changed immediately after the first login. After this, the installation can be started, by entering various information. You need to enter the following: 1. User name and password as well as host name and, if appropriate, the name of an already created database that 28
2.4 The Installation Tool
TYPO3 should use. 2. The path to the directory where ImageMagick is installed on your system. With the command user@linux:~> locate identify
you can quickly find this out on most Linux distributions. The Installation Tool is divided into the following areas, where the first three have to be edited to some extent when it is installed. The other views are for system maintenance.
2.4.1 Basic Configuration The tab for basic configuration checks the permissions of the directories that need to be writable for TYPO3, and also checks the PHP configuration in the php.ini file. Any problems that might prevent the installation from being performed are shown here, with corresponding warnings.
Figure 2.2: All directories required by TYPO3 were identifed as being correctly configured
Here you must also specify the access data for your database. After entering the user name, password, and host name (usually "localhost", if MySQL is installed on your server), the form must be submitted once with the update configuration command in order to select a database or, if your user has the appropriate permissions (create), to create a new database.
Figure 2.3: Access data for the database
29
2 Installation
Next we will discuss the settings for generating images. If you have installed ImageMagick, you should specify the path to your installation here. TYPO3 searches automatically in the default directory for ImageMagick and also determines independently whether you have compiled the GDLib with Freetype into PHP. With current Freetype versions, the text in the test picture might extend beyond the edges. If this problem persists, we will fix it at a later stage (see section 2.4.4).
Figure 2.4: Output of the Freetype test at the correct resolution
If you submit the form, the Installation Tool will write the corresponding values to the localconf.php file.
2.4.2 Database Analyzer The script for database analysis enables you to both edit and update an existing database as well as to fill it for the first time with a database definition and standard contents. A basic database definition is included in the dummy package. The corresponding SQL file is in the "localconf" directory, typo3conf/, and is displayed automatically in the Installation Tool.
Figure 2.5: Display of the default SQL file with the basic database contents and the database definition
With the Import option, the database is imported. After clicking on this option, you will receive a security query, where you should select the option to read in all data, and submit the form with Write to database.
30
2.4 The Installation Tool
Figure 2.6: Importing the database
Depending on the performance provided by your web server, this processing may take a while. In the next step you will see a list of all database tables, with the warning that they already exist. If this is not the case, and a number of tables are displayed as not yet existing, then the import process has failed, and you should try it again. Initialization of the database is now finished. An administrator account is then set up with the user name admin and with the password password.
Figure 2.7: Message of the Database Analyzer after successful import of the SQL file (attention: your display may contain different tables!)
31
2 Installation
An alternative method that does not need the database.sql file from the dummy package can be used to initialize the database—select the COMPARE option. A list of all required database tables is shown. These have been pre-selected. Press the confirm button in the form to create the database tables. Then select the Create "admin" user function and set up an administrator account.
2.4.3 Image Processing This script is a collection of test outputs to test the function of ImageMagick and the GDLib and Freetype. It has no influence on the configuration of your system, and is therefore not discussed further here.
2.4.4 All Configuration The All Configuration script contains entry fields with short explanations on all configuration options of TYPO3, which are named in the TYPO3_CONF_VARS array. In general, only a few entries are important. If the text in the previously introduced Freetype test extends beyond the edges, adjust the resolution for Freetype and increase it from 72 to 96 dpi. Enter this value in the field [GFX][TTFdpi]; you will find it as the final part of section [GFX], before the [SYS] section. Further entries are not normally necessary here.
2.4.5 typo3temp/ Here you are shown a statistical overview of the files stored in the typo3temp directory, and you can also delete them from here. This is an important function for maintaining the installation. The directory is used by TYPO3 to store image files shown in the front end. The images are freshly generated each time the page cache is deleted, while the old ones remain in this folder. For large websites with large amounts of image material, many MBs can quickly accumulate here. If the images are deleted from this directory, although the files are still referenced from the pages, the image is newly generated, as long as you emptied the page cache after deleting the files. You can also take a look in the back end of your TYPO3 installation, in the Tools | Check DB module under Missing Relations, to see how many files without a database relation are located in this directory.
32
2.5 Configuration Options in TYPO3_CONF_VARS
2.4.6 phpinfo() This area calls up the PHP default function phpinfo() and displays all the essential parameters of the PHP installation. At the top you will also find a summary of the most important system parameters of TYPO3, which you should include in your e-mail in case of questions to the Install list, so that all essential information to search for the error is provided.
2.4.7 Edit Files in typo3conf/ This option shows a list of the files in the typo3conf/ directory. You can edit each of the files; just click on the name of the file to reach the editing dialog. This can be a very useful option for experienced TYPO3 users, to set configuration values by hand, for example, if one of the installation scripts has failed to work. You have the option of converting all line breaks from the Windows format into Linux line breaks, and automatically creating a backup copy of the file you are editing. This last function is highly recommended for configuration attempts in the file localconf.php, so that you can easily restore the former configuration.
2.4.8 About You already know this page: it is the first page you are shown when the program starts. It provides you with the option of changing the Installation Tool password. If you have not already done this, do it now.
2.5 Configuration Options in TYPO3_CONF_VARS Apart from the basic configuration, a whole range of settings can be influenced by the All Configuration script. Here is a list of all the parameters, together with descriptions, some of which are contained in the script itself in abbreviated form.
2.5.1 [GFX]:$TYPO3_CONF_VARS The GFX area (for "Graphics") contains all the configuration options for image processing in TYPO3. IM is an abbreviation for ImageMagick, GD stands for the GDLibrary.
33
2 Installation
[image_processing] Boolean value (0,1). Switches image processing in TYPO3 on or off. Example: [image_processing] = 1 [thumbnails] Boolean value (0,1). Switches display of thumbnails in the back end on or off. Example: [thumbnails] = 1 [thumbnails_png] Bits. Bit 0: the entry 0 creates thumbnails in GIF format, 1 in PNG format. Bit 1: the entry 2 specifies that all files displayed in JPG format are also displayed as GIF, or with 3, as PNG. Example: [thumbnails_png] = 0 [noIconProc]
Boolean value (0,1). If switched on (1), icons are not processed dynamically in the back end with overlays (e.g. start time and end time, hidden), but must be available on the server. This can be useful to obtain a functioning back end, even if overlays are not correctly performed by the installed ImageMagick software. This option should only be switched off if the server provides all imageprocessing options. Example: [noIconProc] = 1 [gif_compress]
Boolean
value
(0,1).
This
activates
the
t3lib_div::gif_compress() function, which recompresses
generated GIF files if they do not use any compression or only use RLE compression (Run Length Encoding). See: [im_path_lzw]. Example: [gif_compress] = 1 [imagefile_ext]
You can specify here, in a comma-separated list, which file extensions should be interpreted by TYPO3 as images. The list should be restricted to gif,png,jpeg,jpg if IM is not available. The file extensions are written in lower case, without spaces. Example: [imagefile_ext] = gif,jpg,jpeg,tif,bmp,pcx,tga,png,pdf,ai
34
2.5 Configuration Options in TYPO3_CONF_VARS [gdlib]
Boolean value (0,1). This setting enables the use of the GDLibrary by TYPO3. Example: [gdlib] = 1 [gdlib_png]
Boolean value (0,1). Entering 1 specifies that GD will generate only PNG files instead of GIF files. However, older browsers cannot display PNG files. Even the current versions of the IE do not support all PNG features, such as transparencies. Example: [gdlib_png] = 0 [gdlib_2]
Boolean value (0,1). This value should be set to 1 if your web server uses GDLib 2.0.1 or higher, otherwise problems may occur. Example: [gdlib_2] = 0 [im]
Boolean value (0,1). Enables the use of ImageMagick (IM) by TYPO3. Example: [im] = 1 [im_path]
Here the path in which the IM programs convert, combine, and identify are located in the file system of the web server is specified. Example: [im_path] = /usr/local/bin/ [im_path_lzw]
Path details to an IM version whose convert command can implement LZW compression. This compression belongs to a Unisys patent and was supported only temporarily by ImageMagick. The recommended version 4.2.9 of IM can be equipped with LZW compression; in this case the field is left blank and [gif_compress] is switched off. It can be expected that future versions of various software will support LZW compression, since the patent on it has expired. Example: [im_path_lzw] = /usr/local/typo3sh/bin/
35
2 Installation [im_version_5]
Boolean value (0,1). This value must be set to 1 if you are using an IM version upwards of 5.x. Example: [im_version_5] = 0 [im_negate_mask]
Boolean value (0,1). From version 5.1, images must be inserted before they are overlaid with a mask. Example: [im_negate_mask] = 0 [im_imvMaskState]
Boolean value (0,1). Since version 5.4.3+, the situation described in the last item has been reversed, and TYPO3 can be configured so that the global [im_version_5] setting does not require any conversion of the image files to be masked, as was necessary until this version. 9 Example: [im_imvMaskState] = 0 [im_no_effects]
Boolean value (0,1). Effects with ImageMagick work well in the recommended version 4.2.9. In newer versions they have become much slower, and can be switched off with this setting. In the most recent IM versions, effects perform much better again, but the syntax of the API has again been changed—no comment. Example: [im_no_effects] = 0 [im_v5effects]
Integer (-1,0,1). 0 = switched off. -1 = do not focus sharpen images by default. 1 = All; blurring and sharpening are enabled and the setting [im_no_effects] is overridden. Example: [im_v5effects] = 0 [im_mask_temp_ext_gif]
Boolean value (0,1). This should be enabled when using IM
9 This and many other developments led to the splitting of the GraphicsMagic project,
aimed at creating a more reliable interface. Kasper Skårhøj’s original comment at this point is obviously a heartfelt one: “Halleluja for ImageMagick - have I ever regretted using that package...”
36
2.5 Configuration Options in TYPO3_CONF_VARS
versions 5+. The tslib_cObj class by default uses the PNG format, because generating is faster and puts lesser load on the CPU. But since some IM versions above 5 do not correctly support the PNG format, this can be suppressed here. Example: [im_mask_temp_ext_gif] = 0 [im_mask_temp_ext_noloss]
String. While images are being masked, the temporary files should be stored in a loss-free format, of course. ImageMagick's own format, named miff, is ideal for this. Unfortunately version 5.4.9 is not in a position to generate its own file format, so that this function became necessary. If problems occur with masked files, TIF, PNG, or JPG can be used instead. Example: [im_mask_temp_ext_noloss] = miff [im_noScaleUp]
Boolean value (0,1). If enabled, images are not enlarged. Example: [im_noScaleUp] = 0 [im_combine_filename]
String. More recent IM versions have renamed the combine command to composite; the proper name can be given here. Example: [im_combine_filename] = combine [im_noFramePrepended]
Boolean value (0,1). Some image formats such as GIF or TIF allow several images to be saved in one file. ImageMagick provides an option to work only with the first image, which in general increases working speed. Unfortunately, some IM versions contain an error that causes the IM to simply ignore these images. In such a case, this option must be enabled. Example: [im_noFramePrepended] = 0 [enable_typo3temp_db_tracking]
Boolean value (0,1). Here it is specified whether all files in typo3temp/ are recorded in a database table. This prevents files from being doubly rendered, since the relation between the temporarily rendered output file and the source file is noted here. In addition, in the Tools | Database check module in the back end and in the Installation Tool, you can find out how many old files there are in the temp/ directory. Example: [enable_typo3temp_db_tracking] = 0 37
2 Installation [TTFLocaleConv]
String. Up to version 3.6.0 you could specify here, using the recode designations, in what encoding TrueType functions were generated. Since version 3.6.0, the output has always been in UTF-8. Example: [TTFLocaleConv] = [TTFdpi]
Integer. This important option is for setting the resolution in dpi (dots per inch) in which the existing Freetype system on your server works. Since version 2 this has been 96 instead of 72 dpi; this causes fonts to be displayed too large if the value is not changed to 96 dpi for a more recent version. Example: [TTFdpi] = 96
2.5.2 [SYS]:$TYPO3_CONF_VARS["SYS"] This section describes configuration options involving system behavior in the back end and front end. [textfile_ext]
You can specify here, via file extensions, which file types may be edited in the back end. Example: [textfile_ext] = txt,html,htm,css,inc,php,php3,tmpl,js,sql
[contentTable]
With this option you can specify what the page content table should be called. The default value is tt_content. Example: [contentTable] = tt_content [sitename]
This is the name of the installation and is shown at the top of the page tree next to the globe. The name can also be set directly in the Basic Configuration view of the Installation Tool. Example: [sitename] = BT3 Enterprise [ddmmyy]
Format of the date display—corresponds to the notation of the PHP function, date(). Example: [ddmmyy] = d.m.y 38
2.5 Configuration Options in TYPO3_CONF_VARS [hhmm]
Format of the hour display—corresponds to the notation of the PHP function, date(). Example: [hhmm] = H:i [encryptionKey]
Here you can specify a random string to be used in the creation of hash values for encryption in the context menu, the Direct Mail Module, and at other points in the system; this helps to increase security. Example: [encryptionKey] = Haaken Flip [doNotCheckReferer]
Boolean value (0,1). With this option, active checking in the back end to see if the currently accessing host is identical to the Referring Host can be switched off. If this value is set to 1, checking is switched off. This can be useful when accessing via proxy servers, which prevent the correct output of the HTTP_REFERER variable. Example: [doNotCheckReferer] = 0 [recursiveDomainSearch]
Boolean value (0,1). If enabled (1), TYPO3 searches for a suitable entry, if access is attempted to a non-existent domain by recursively deleting parts of the domain name to find a suitable match. Example: [recursiveDomainSearch] = 0 [T3instID]
This option has not yet been used. The intention was to create a unique identity designation with which each installation could identify itself when accessing the Extension Repository. This was intended for statistical purposes, but until now has not been put into practice. Example: [T3instID] = N/A [devIPmask]
Comma-separated IP addresses. This important option defines a list of IP addresses from which error output is displayed in the front end. The Debug() function uses these entries as a filter. Without an entry, no access is allowed, * allows all hosts. * as a wild card can also be used for any part of the IP; thus 39
2 Installation 192.168.*.* allows all IP addresses which begin with 192.168..
Boolean value (0,1). The getUrl function used by the system can be used by entering 1 curl instead of fopen(), so that you can work with proxies (which is not possible with fopen()). Curl must be available in your PHP installation. Example: [SYS][curlUse] = 0 [curlProxyServer]
URL. Curl must be given the address of the proxy server in the form http://proxy:port/. Example: [curlProxyServer] = http://192.168.1.1:8080 [curlProxyTunnel]
Boolean value (0,1). For some security systems it is necessary to choose a "tunneled" connection through the proxy. 1 instructs Curl to do this. Example: [curlProxyTunnel] = 0 [curlProxyUserPass]
String. User name and password for access to the proxy server should be entered here, if appropriate, in the notation User name:Password. Example: [curlProxyUserPass] = Leeloo:Multipass [form_enctype]
String. The encryption type of most forms in TYPO3 can be globally adjusted here. multipart/form-data is set by default, to allow file uploads. If file uploads are not permitted in your PHP installation, data created with this form time will not be transferred. The encryption type can be changed accordingly to application/x-www-form-urlencoded. Example: [form_enctype] = multipart/form-data [loginCopyrightWarrantyProvider]
String. The GPL excludes all claims of warranty from the author of the software. If you want or need to assume the warranty for the function towards a customer, you can enter your name here, so 40
2.5 Configuration Options in TYPO3_CONF_VARS
that it can be displayed in the login page. An Internet address (URL) must also be given in the next step. Example: [loginCopyrightWarrantyProvider] = VEB Optimism
[loginCopyrightWarrantyURL]
String. A URL is specified, in the form http://www.yourdomain.de/; this is automatically placed as a link to the names given in the previous option. Example: [loginCopyrightWarrantyURL] = http://www.veb-optimism.de/
[loginCopyrightShowVersion]
Boolean value (0,1). If 1 is entered, the login page shows the TYPO3 version. Example: [loginCopyrightShowVersion] = 0 [binPath]
String. Comma-separated list: here you can enter a list of absolute system paths where a search is made for external programs. This is used by the DAM for services, for example. Example: [binPath] = /usr/bin/ [t3lib_cs_convMethod]
String. In the t3lib_cs class, entering one of the following values specifies with which tool character sets are converted: iconv or recode are external programs; the default is TYPO3's own PHP code. The external programs are significantly faster, but the SGML fallback HTML coding of special characters is not supported. Example: [t3lib_cs_convMethod] = recode [t3lib_cs_utils]
String. With this entry you can specify that instead of TYPO3's own code for processing character sets, the PHP module mbstring should be used, which is much quicker. The only possible value, in contrast to what is specified in the English description in the Installation Tool, is mbstring; if nothing is entered, TYPO3's own code is used. Example: [t3lib_cs_utils] = mbstring
41
2 Installation
2.5.3 [EXT]: $TYPO3_CONF_VARS["EXT"] This section describes various options for configuring the Extension Manager and related system parts. [noEdit]
Boolean value (0,1). 1 prevents files in the Extension Manager from being edited. For developers, the value should be set to 0 so that changes can be implemented directly here. Example: [noEdit] = 1 [allowGlobalInstall]
Boolean value (0,1). With 1 global extensions can be installed in the typo3/ext/ directory via the Extension Manager, updates can be implemented, and extensions deleted from that directory. This option is important if several instances are to be operated on one installation, and if administrators are not to edit global extensions of individual instances. Example: [allowGlobalInstall] = 0 [allowLocalInstall]
Boolean value (0,1). 1 enables the administration of local extensions in the typo3conf/ext/ directory of the instance in question, via the Extension Manager. Example: [allowLocalInstall] = 1 [em_devVerUpdate]
Boolean value (0,1). If 1 is entered, developer versions of extensions are marked in red in the Extension Manager if updates are available. Example: [em_devVerUpdate] = 0 [em_alwaysGetOOManual]
Boolean value (0,1). With the value 1 you can specify that the documentation included in extensions, available in OpenOffice format, is always downloaded to the server. Example: [em_alwaysGetOOManual] = 0 [em_systemInstall]
Boolean value (0,1). With the value 1 the Extension Manager is allowed to install extensions to the sysext/ directory. This is needed to be able to perform updates to the cms and lang system 42
2.5 Configuration Options in TYPO3_CONF_VARS
extensions with the EM. Example: [em_systemInstall] = 0 [requiredExt]
String. Comma-separated list: here you can specify extensions that cannot be disabled by the Extension Manager. Normally these are at least cms and lang, which form the core of the system. Example: [requiredExt] = cms,lang [extCache]
Integer (0,1,2,3). 0 causes the extension scripts ext_localconf.php and ext_tables.php not to be stored in the cache, but to be read through each time the page is requested—interesting when developing extensions, as it saves you from deleting the cache in the back end. The default is 1: the scripts are saved in files of the form typo3conf/temp_CACHED_[sitePathHash]*, reducing the load on the server and increasing performance—a useful setting for live operation. The value 2 has the effect that the file name of the cache file contains a hash value based on the [extList] string. 3 means that the names of the cache files do not contain any hash value. Example: [extCache] = 1 [extList]
String. Comma-separated list: extensions installed by the EM are entered in this list. If you install a defective extension that makes working with the system impossible, you must edit the file typo3conf/localconf.php to remove this extension and delete the key from this list. In addition the typo3conf/temp_CACHED_* files must be deleted for the system to be operational again. Example: [extList] = tsconfig_help,context_help, extra_page_cm_options,...
43
2 Installation
2.5.4 [BE]: $TYPO3_CONF_VARS["BE"] This section involves the parameters for back end configuration. [unzip_path]
Path details on the decompression program, unzip. Example: [unzip_path] = /usr/bin/ [diff_path]
Path to the command line application diff, used to compare files. A Windows version of diff can be downloaded from http://unxutils.sourceforge.net/. Example: [diff_path] = diff [fileadminDir]
Path details of the Fileadmin directory; this must be relative to the path of the website from the constant, PATH_site. Example: [fileadminDir] = fileadmin/ [RTE_imageStorageDir]
Path to where files of the Rich Text Editor are saved. Example: [RTE_imageStorageDir] = uploads/ [staticFileEditPath]
Path to the directory where so-called static files can be stored and edited. Database fields can be configured in such a way in the $TCA that in reality they are stored in a file. The extension sys_staticfile_edit is one application of this. Example: [staticFileEditPath] = fileadmin/static/ [lockRootPath]
String. Specifies the first part of the path to [userHomePath] and to [groupHomePath]. Please note that the first parts of [userHomePath] and [groupHomePath] must match [lockRootPath]. This is also used to check if a path is also allowed outside the PATH_site constants. This can be changed if, for example, data processing is to be allowed in a level above the web directory. Example: [lockRootPath] = /srv/www/archiv/ [userHomePath]
String. Path to a directory where the back end user should have 44
2.5 Configuration Options in TYPO3_CONF_VARS
his or her own home directory. If the path is entered here, TYPO3 automatically creates its own directory for each user, for example if the value /home/typo3/users/ is entered, then a directory with the path /home/typo3/users/43_cameronfrye/ is created for the user cameronfrye with the uid 43. Example: [userHomePath] = /srv/www/htdocs/typo3/users/ [groupHomePath]
String. In the same way as for users, a separate directory can be created automatically for each group. Example: [groupHomePath] = /srv/www/htdocs/typo3/group/ [userUploadDir]
String. A pre-configurable suffix that is added to user directories. If the user directory matches the user name and the uid, that is, 43_cameronfrye/, and the value set here is /250GT, a directory with the name 43_cameronfrye/250GT/ is made available to the user. Example: [userUploadDir] = /250GT [fileCreateMask]
In accordance with the UNIX umask syntax, you can define here what access permissions should be given to files created by TYPO3 in the file system. Example: [fileCreateMask] = 0644 [folderCreateMask]
Is the same as the above setting, but refers to folders. Example: [folderCreateMask] = 0755 [warning_email_addr]
E-mail address to which a warning message is sent if four failed login attempts to the back end have taken place within one hour. Example: [warning_email_addr] = [email protected] [warning_mode]
Integer (1,2). With 1, the address specified above always receives a message if a user has logged in to the back end. If 2 is set, the address only receives a warning message if an administrator logs in. Example: [warning_mode] = 2 45
2 Installation [IpmaskList]
String. IP addresses can be specified here for which access to the back end is granted exclusively, so that users from other addresses basically have no access at all. It is possible to use * as a wild card. Example: [IPmaskList] = 192.168.1.* [adminOnly]
Boolean value (0,1). If 1 is specified, only administrators may log into the back end. 0 allows access to all users. This can be implemented to exclude users from the system during maintenance work and updates. Example: [adminOnly] = 0 [lockBeUserToDBmounts]
Boolean value (0,1). 1 is entered here by default so that users only have access to their own Pagemount. This can be disabled with 0. Such an application scenario is very improbable, however. Example: [lockBeUserToDBmounts] = 1 [lockSSL]
Integer (0,1,2). With both entries, TYPO3 is instructed to make the back end available only via an SSL connection. 2 causes access to http://your-domain.de/typo3 to be automatically redirected to https://your-domain.de/typo3. Example: [lockSSL] = 0 [disable_exec_function]
Boolean value (0,1). On Windows systems, it is possible that the use of the PHP function exec() needs to be suppressed. This is done by entering 1. For ImageMagick this can be achieved by switching off all graphic functions: [GFX][im]=0. Example: [disable_exec_function] = 0 [usePHPFileFunctions]
Boolean value (0,1). If PHP is operated in safe_mode, it is possible, even under UNIX, that all file functions with standard PHP functions have to be used together with exec() instead of with external commands. This is changed accordingly by entering 1. Example: [usePHPFileFunctions] = 1
46
2.5 Configuration Options in TYPO3_CONF_VARS [compressionLevel]
Integer (1-9). Requires zlib in PHP. Compression using gzip is set with a value on a scale from 1-9. Compressed pages use less bandwidth, but system load increases with higher compression rates. 0 stands for no compression, 9 for maximum compression. Alternatively you can specify TRUE, whereby compression is adjusted dynamically, depending on the system load (only under Linux and FreeBSD). Compression can alternatively be configured in Apache. Example: [compressionLevel] = 0 [MaxFileSize]
Integer. The maximum file size which can be edited by TYPO3 can be set here. The setting is only relevant in the context of the file size defined for PHP in the file PHP.ini. Example: [maxFileSize] = 10000 [RTEenabled]
Boolean value (0,1). With this option the Rich Text Editor can be switched on (1) and off (0) globally, independent of the settings in the back end. Example: [RTEenabled] = 1 [forceCharset]
String. Character set is normally used in accordance with the language set in the back end for the respective user. The character set can be defined here for all users. The options can be seen in the character set tables and the t3lib/csconvtbl/ directory. utf-8 can be used, for example, for Unicode coding. The character sets must be specified in lower case. Example: [forceCharset] = iso{-8859-8} [installToolPassword]
String. This is the md5 hash value of the password for the Installation Tool. To lock the access, do not enter a value. It is advisable to additionally protect the directory for the Installation Tool, typo3/install/, with a password query through a .htaccess file. Example: [installToolPassword] = e1c102cf0300bf73e47018f5bd7766e5
47
2 Installation [trackBeUser]
Boolean value (0,1). With the value 1, TYPO3 is instructed to log every call of a script in the back end, in the table sys_trackbeuser. To evaluate this, the extension beuser_tracking is needed. Example: [trackBeUser] = 0 [defaultUserTSconfig]
String. TypoScript: It is possible to define default TypoScript settings for all back end users here (see Chapter 4.8). Example: [defaultUserTSconfig] = admPanel.enable= 1 [defaultPageTSconfig]
String. TypoScript: It is possible to define default TypoScript settings for all back end users here (see Chapter 5.8). Example: [defaultPageTSconfig] = mod.web_layout. tt_content.colPos_list= 0,3
[enabledBeUserIPLock]
Boolean value (0,1). If 1 is set, the User/Group TSconfig option option.lockToIP is enabled. Further settings can be found in the TSConfig field of the user or group to be configured. Example: [enabledBeUserIPLock] = 1 [fileDenyPattern]
String. In accordance with the eregi() function, components of names can be specified here. Files containing these components cannot be loaded to the server or renamed. Example: [fileDenyPattern] = \.php\.|\.php3\ [interfaces]
You can specify here which interfaces are presented to users for selection when logging in to the back end, and in which order. The choices are backend and frontend (comma-separated). Example: [interfaces] = backend [loginLabels]
The input options of the login screen can be overwritten here with other expressions, in German, for example. Example: [loginLabels] = Username | Password | Interface | Log In | Log Out | ...
48
2.5 Configuration Options in TYPO3_CONF_VARS [notificationPrefix]
This option allows a header to be set for messages from the system to the administrator. Example: [notificationPrefix] = Miracles may happen...
2.5.5 [FE]: $TYPO3_CONF_VARS["FE"] Configuration parameters in the following section referred to the front end, that is, the websites published by TYPO3. [png_to_gif]
Boolean value (0,1). The value 1 enables the conversion of all PNG files generated in the front end to GIF files. This leaves behind a large number of temporary files in the typo3temp/ directory. Example: [png_to_gif] = 0 [tidy]
Boolean value (0,1). If 1 is set, the HTML code is cleaned and optimized with the tidy program. This option is recommended, especially during development periods, so that the HTML code generated can be more easily read. But remember that tidy, depending on the options, cleans or repairs defective HTML code. This option should be switched off on live systems, to prevent unnecessary load on the server. tidy can be obtained here: http://www.w3.org/People/Raggett/tidy/ Example: [tidy] = 0 [tidy_option]
Options: [all, cached, output]. all causes tidy to clean up all content before it is saved in the cache. cached causes content only to be cleaned before it is saved to the cache. output cleans HTML code only if it is requested from the cache. Example: [tidy_option] = cached [tidy_path]
Here the command tidy is specified, including the path and all necessary options, where appropriate. Apart from the default setting, other parameters can be defined in accordance with the documentation of tidy. To generate XHTML through tidy, for example, the expression --output-xhtml true should be added. 49
Path. In the directory given here, TYPO3 writes log files in the notation of a web server for evaluation by statistical programs. The directory must be writable for the web server. The directory name must be concluded with a slash. More information can be found in Chapter 4.12.2. Example: [logfile_dir] = /srv/www/logs/ [logfile_write]
The log files can be written using various methods. Without further settings, TYPO3 uses the UNIX command echo. Entering fputs causes TYPO3 to use the PHP function of the same name, which also works in safe_mode mode. Example: [logfile_write] = fputs [publish_dir]
Path to a directory in which TYPO3 should statically publish HTML pages. The directory must be writable for the web server. The pages can then be published from the Admin Panel in the publish area. Example: [publish_dir] = /srv/www/htdocs/publish/ [addAllowedPaths]
Path, comma-separated list: other directories can be specified in which resources are stored for use in TypoScript. Paths must be specified relative to the web directory. The default is specified with a leading slash; without a slash, every directory is accepted that begins with the same expression. Example: [addAllowedPaths] = b2b/, /b2c/ [allowedTempPaths]
Path, comma-separated list: additional paths where temporary images may be located for use by imgResource in TypoScript. Example: [allowedTempPaths] = b2btemp/ [debug]
Boolean value (0,1). If enabled with 1, debug information is shown in the front end. This can also be set in TypoScript. Example: [debug] = 1 50
2.5 Configuration Options in TYPO3_CONF_VARS [simulateStaticDocuments]
Boolean value (0,1). Display of simulated static URL addresses is switched on by default with this entry, but needs to be enabled separately in TypoScript. Example: [simulateStaticDocuments] = 1 [noPHPscriptInclude]
Boolean value (0,1). If enabled, PHP scripts are only called by TypoScript if they are located in the directory media/scripts/. Example: [noPHPscriptInclude] = 0 [compressionLevel]
This value defines the compression of HTML pages in the front end through the zlib function in PHP. 1 is the lowest compression rate, and 9 the highest. Compression helps to spare bandwidth, but also puts more load on the server, the higher the compression rate. If you enter TRUE, the compression rate is automatically adjusted to the system load. Example: [compressionLevel] = 0 [compressionDebugInfo]
Boolean value (0,1). If enabled, the size of the compressed and uncompressed versions of a page are shown at the bottom of the page. This should only be used for test purposes, as the pages for static evaluation are compressed twice. Example: [compressionDebugInfo] = 0 [pageNotFound_handling]
String. With this option you can configure how TYPO3 should react to queries for unavailable pages. The default behavior is to display the next page. With TRUE or 1, an error message is displayed. Alternatively an HTML page can be specified, which will be displayed. Example: [pageNotFound_handling] = http://www.brunching.com/gone.html
[pageNotFound_handling_statheader]
String. If the option [pageNotFound_handling] is enabled, the string set here is always sent as the header. Example: [pageNotFound_handling_statheader] = Status: 404 Not Found
51
2 Installation [userFuncClassPrefix]
This prefix must be the first part of each function or of the name of a class that is called from TypoScript, e.g. in the stdWrap function. Example: [userFuncClassPrefix] = user_ [addRootLineFields]
Comma-separated list. A list of additional database fields in the pages table; should be used for Rootline queries. Example: [addRootLineFields] = [checkFeUserPid]
Boolean value (0,1). If enabled, login forms in the front end must specify the page ID (pid) of the front end user under which these are stored. If this is disabled, with 0, the eval configuration of uniqueInPid in the $TCA for the fe_users.username field should be changed to unique. The entry then looks like this: $TCA['fe_users']['columns']['username']['config'] ['eval'] = 'nospace,lower,required,unique';
The storage location no longer has to be specified in the TypoScript page on which the login form is located; all FE users are globally valid for the TYPO3 instance. Example: [checkFeUserPid] = 1 [defaultUserTSconfig]
String. TSConfig entries can be predefined here for all front end users and groups. Example: [defaultUserTSconfig] = [defaultTypoScript_constants]
String. Option to predefine TypoScript for constants systemwide. Example: [defaultTypoScript_constants] = [defaultTypoScript_editorcfg]
String. Option, to define the TypoScript editorcfg configuration systemwide. Is used by the CSS Styler (extension key: tstemplate_cssanalyzer). Example: [defaultTypoScript_editorcfg] =
52
2.5 Configuration Options in TYPO3_CONF_VARS [dontSetCookie]
Boolean value (0,1). If enabled, the system does not set any cookies in the front end, which also causes logins to be switched off. Example: [dontSetCookie] = 0 [get_url_id_token]
String. In the front end, users can log in without a cookie if the TypoScript option config.ftu is enabled. In this case the user session is managed via a GET parameter, the name of which is specified here. In principle this type of session administration is not recommended, as it is more error-prone than the cookie variant. Example: [get_url_id_token] = SESSID [content_doctypes]
String. Page types (type number of the field pages.doctype) that are to be recognized by the system as pages or SysFolders are defined here as a comma-separated list. Example: [content_doctypes] = 1,2,5,7 [enable_mount_pids]
Boolean value (0,1). With this option the function of Mountpages can be switched off globally (0). Example: [enable_mount_pids] = 1 [pageOverlayFields]
String. The specified fields are used in database queries for multi-language websites. This option is relevant for extensions that add their own fields to the pages table. Example: [pageOverlayFields] = title,subtitle, nav_title,media,keywords,description,abstr...
53
2 Installation
2.5.6 Other Options [MODS: $TYPO3_CONF_VARS["MODS"]]
Used to contain options for configuring modules, but was replaced by the extension system. [USER: $TYPO3_CONF_VARS["USER"]]
Used to contain options for configuring parameters for your own scripts, but was replaced by the extension system. [SC_OPTIONS: $TYPO3_CONF_VARS["SC_OPTIONS"]]
This section is used to make available your own configuration options for any scripts at all (in general, BE modules) in TYPO3. [EXTCONF: $TYPO3_CONF_VARS["EXTCONF"]]
Here you can add configuration options for your own extensions. During the installation in the EM, these should be displayed using the file ext_conf_template.txt. Example: $TYPO3_CONF_VARS['EXTCONF'] ['my_extension_key']['my_option'] = 'my_value';
2.6 Separation of Production Server/Live Server In cases where increased performance capacity is required and also for security reasons, it can be useful or even necessary to share the processing of pages and other contents, as well as their presentation across several different servers. A simple possibility would be the publication of the website as static HTML pages, without a database or TYPO3 on the live system. But in the standard scenario, the website itself contains these dynamic elements generated from a database, which make TYPO3 necessary on the live system. The essential problem in such a scenario therefore lies in the synchronization of database content between different systems, where several different servers might be involved, perhaps to spread the load. Depending on the database used, some very different synchronization mechanisms are available for this purpose. Please consult the documentation of your database vendor. With direct synchronization, you cannot make any further decisions in the publication: what is live on the production system is automatically placed 54
2.6 Separation of Production Server/Live Server
online. Alternatively the synchronization can be performed manually, depending on the RDBMS used, in case a further release step is necessary. For the TYPO3 installation delivering the site and offering no editing functions, it is advisable to disable the back end logins of regular users altogether by setting the following parameter in the All Configuration tab of the Install Tool: $TYPO3_CONF_VARS['BE']['adminOnly']='1';
2.6.1 Static Pages A second and simpler variation is to publish static pages, already mentioned briefly in section 2.4.4. The following entry in the Installation Tool and configuration in the Admin Panel of the front end causes all webpages to be saved in a predefined directory of the server.
Figure 2.8: Selecting the page levels to be published, in the Admin Panel of the front end
Apart from the TYPO3-like systems for generating static pages, there are many other software solutions for all standard platforms. An example is HTTrack, available under both Linux and Windows, and which can be obtained without charge as an Open Source tool at http://www.httrack.com/.
2.7 Backup You can use various methods to create backups. Most companies have proper backup strategies, and the safest way is to include the relevant directories of the web server in these backup routines, not forgetting the directory where the database files are stored. If it is just a matter of creating backups from TYPO3 alone, there are various extensions available to perform this task. However, a relatively inexperienced administrator can easily set up an automatic backup system at the operating system level, which is normally a better solution, because the backups do not have to be manually started each time. 55
2 Installation
With an entry in the crontab system (UNIX), this script can be called up regularly: in the example below, this is done every 24 hours, at 1 o'clock in the morning. After this, the backup files should be copied automatically onto a physically separate system. A script such as the following one could perform this conveniently and automatically via rsync. To do this, an SSH key is necessary to enable the data to be transmitted in encrypted form. Here is an example script (with thanks to Harald Oest from http://www.ixsys.de/): #!/bin/sh # script rsync_backup.sh # backup of web server document root via rsync to # backup server # additionally do a dump of typo3-db # ip or fqhn of backup server SERVER="my_backup_server" # user account at backup server USER="my_username" # ssh-key (without passphrase!) used for login SSHKEY="/root/.ssh/backup_server_key" # destination dir at backup server DSTDIR="/typo3_bkp" # name of local typo3 database DB="typo3_db" # user account to access typo3 database DB_USER="typo3_db_user" # password to access typo3 database DB_PASS="typo3_db_password" # these directories will be rsynced with backup server DIRS="/srv/www" # do a mysql-dump and store result in source dir /usr/bin/mysqldump --password=$DB_PASS -u $DB_USER $DB > \ /srv/www/typo3db_bkp.sql # rsync all requested dirs for DIR in $DIRS; do logger "rsync backup $DIR to $SERVER" rsync --rsh="ssh -i $SSHKEY" -a $DIR $USER@$SERVER:$DSTDIR done; # get actual size of backup ACT_SIZE=`ssh -i $SSHKEY $USER@$SERVER "du -sh $DSTDIR" logger "total backup size: $ACT_SIZE"
56
2.7 Backup
You can generate an SSH key without a password query as follows: keygen -tt rsa linux:~# ssh-k Generating public/private rsa key pair. Enter file in which to save the key (/root/.ssh/ id_rsa): /root/.ssh/backup_server_key Enter passphrase (empty for no passphrase): [Enter] Enter same passphrase again: [Enter] Your identification has been saved in /root/.ssh/ backup_server_key. Your public key has been saved in /root/.ssh/ backup_server_key.pub. The key fingerprint is: 8b:1f:f9:c9:54:65:bc:f5:d6:ce:79:0d:e4:1d:56:2f root@local_box
The key pair has now been created, and the private key is already in its correct location (/root/.ssh/backup_server_key). The public key now needs to be sent to the backup server: linux:~# scp /root/.ssh/backup_server_key.pub \ > user@my_backup_server:/home/.ssh
Now make a connection to my_backup_server and activate the SSH key: root:my_backup_server:~# cat
/home/.ssh/ backup_server_key.pub >> \
> /home/.ssh/authorized_keys
In order to clear up after this: root:my_backup_server:~# rm
/home/.ssh/ backup_server_key.pub
And the same on the local computer: linux:~# rm /root/.ssh/backup_server_key.pub
You can now make a connection to the backup server without a password: linux:~# ssh -i /root/.ssh/backup_server_key user@my_backup_server
Here is an example of an appropriate crontab entry, which calls up the rsync backup at 1 a.m. in the morning: # call backup script every night at 01.00 0 1 * * * root test -x /root/bin/rsync_backup.sh && \ /root/bin/rsync_backup.sh
57
2 Installation
2.8 Updates TYPO3 updates are particularly enjoyable for the administrator, since they rarely last more than a few minutes. The reason for this lies in the often mentioned symbolic links, which summarize the actual TYPO3 version in a single directory; all the other files are either version-independent, and remain where they are, or are also symbolic links. However the first step in every update is to make a backup of the entire installation, or at least of the database. With the command linux:/srv/www># mysqldump -u user -p databasename backup.tgz
you can create a backup file, after entering the password of the database user in MySQL. In emergencies, you can unpack this backup with the command linux:/srv/www># tar xzf backup.tgz
and then, with the command linux:/srv/www># mysql -u user -p databasename < backup.sql
write it back to the database. Back to the update: to use the new version instead of the old one, you must delete the old symbolic link. For example, with linux:/srv/www># {rm typo3_src}
your site is now offline! With the command linux:/srv/www># {ln -s ../typo3-src-3.8 typo3_src}
a new symbolic link is set to the new source that was previously placed on the server (see section 2.3.1). Under Windows and generally with zip-distributions, if you are not using Junction, all the TYPO3 directories (typo3, t3lib, tslib) have to be replaced manually. So if the symbolic link that points to the TYPO3 version is replaced, the update on the file level is already complete. Please remember that after an update (or a downgrade) of TYPO3, you should first call up the Database Analyzer of the Installation Tool. With the COMPARE function, necessary changes to the database are identified and displayed. These are new database fields as well as changes in the 58
2.8 Updates
field definition of existing fields. Select Implement All Changes and carry out the update. The COMPARE function can also remove database tables that are no longer required from uninstalled extensions. It goes without saying that you should know what you are doing when carrying out this function, and of course: back up, back up, back up! The tables and fields to be removed are first renamed and then provided with the prefix zzz_. They can be reactivated by removing this prefix, for example with phpMyAdmin. It is recommended, for obvious reasons, not to carry out the update on heavily visited sites. Instead you can duplicate the database and the file system, adjust the access data to the new database in the copy, and carry out emergency test scenarios. This helps you switch over in a few seconds, by changing the web server or swapping directories.
2.9 Help with Problems The TYPO3 community maintains various contact points regarding installation problems. These can be wide-ranging due to the various possible combinations of web server, database, and PHP distributions used. Two mailing lists exist for installation questions, one each for Linux and Windows operating systems, which can also be used by nntp-client (newsgroups). In addition, there is an online archive you really should browse through to make sure that a question has not already been answered. Bear in mind that all those providing help are volunteers: as someone seeking help, you should try not to distract them with unnecessary or repeat questions. If you have discovered a bug not yet described anywhere, you can register it at http://bugs.typo3.org/.
59
3 TYPO3 for Editors In 1999 Tim Berners-Lee, father of the World Wide Web, exclaimed: "From the point of view of users, the biggest change I want to see is to make everyone capable of writing web pages and making links just as easily as people can create e-mail messages today." 1 One of the main reasons that content management systems have made a breakthrough is that they have put this demand of hypertext authors into practice. However, this has varying degrees of success in terms of user-friendliness—especially for enterprise content management systems. Forrester Research, a market research company, diagnosed in a study in 2001 that there is an urgent need for improvement in usability among the systems reviewed in the study. 2 Usability can be achieved and measured in concrete steps. Here are some common requirements:
•
The user interface must be appropriate, intuitive, and simple to use.
•
It should follow consistent logic and have a uniform structure.
•
It should be possible to customize it, according to the different tasks of each user and/or group.
•
Each function of the application should support the user with context-sensitive help functions, a user manual, and examples for beginners.
•
It should be possible to revoke individual working steps in a work session at the push of a button (the "Undo" function). An editing history helps to recreate previous working states of the record.
In addition, wizards are important, helping users to perform specific work steps.
In general, the following applies: too little functionality blocks the workflow—and too much functionality does the same. For this reason it must be possible to extend or reduce functions: the system must provide users with exactly those functions they require for their work. In addition, the technical requirements for using the CMS on the user side must be as low as possible, in order to be able to keep installation work to a minimum. All this (and more) can be managed by TYPO3. In the course of its six years of development, the user interface has been optimized in terms of userfriendliness, thanks to the experiences of users (there are now some 122,000 installations in operation) who use it in their daily work.
3.1 The Role of the Editor The task of the editor is to create new content and assets, to prepare this content for the appropriate media, and to integrate it into the corresponding application, for example, a web site. For this purpose, the administrator, in the context of user permissions, puts the user into a kind of "sandpit", from within which he or she has (restricted) access to the system and its functionality. So the user's view of the back end, workspace, and of the resources allocated to him or her are limited (see Chapter 4). In contrast to an editor in the press department, for example, who "works in" new articles into the system (this is the jargon in CMS circles), an editorin-chief uses an expanded view, because of his or her (system-internal) group and individual permissions. Softlink 509060
Depending on the size of the content life cycle and complexity of working procedures, the editor merely processes parts of the content on its way to publication. This means that the editor works within a so-called workflow, together with other editors. Below, we will introduce the user interface in which the content is edited, and a tasks module—a communication center for those involved in a project. We will then go on to explain how pages can be created and content added. The focus here is not on the explanation of all the entry fields (context-sensitive help exists for this purpose, as well as the extensive "Manual for Editors", see soft link), but on the general representation of pages and content types, and practical use. Individual aspects, such as handling the Rich Text Editor, will be treated separately. Finally, routines and utilities are presented that can simplify the daily work with TYPO3 for editors, and make it more efficient.
62
3.2 Logging in to the System
3.2 Logging in to the System TYPO3 is a web-based content management system. It is installed in the intranet on an internal company server, or on the web/extranet on a publicly-accessible server. To access the system, editors need nothing more than a browser and the correct Internet address, in order to create and update page contents, irrespective of time and place. TYPO3 makes a distinction between two different areas: the back end or administration area for managing pages and data, and the front end, the actual web site as the normal visitor views it. The editor logged in can use both modes in TYPO3 to edit content. While the back end provides a complete work environment with many functions, the front end can be operated in a very simple and intuitive manner. The primary editing options are all very similar; the operating elements and ways of functioning introduced here can to some extent be also found in the front end.
3.2.1 The Correct Browser Settings TYPO3 works with current browsers (Netscape Navigator 6.x, 7.x, Mozilla Firefox, Internet Explorer 5.x, 6.x, etc.), some of which have a slightly different display and functionality. These differences in display are not significant, apart from the fact that the Rich Text Editor is only available in Internet Explorer, since it also requires Microsoft ActiveX. There are several alternatives for Mozilla, which have to be installed as extensions on the system.
Softlink 352869
The browser must accept cookies, and JavaScript must be activated. Settings for the browser cache should be adjusted so that when a page is called, a fresh version is requested from the server each time.
3.2.2 Login In order to log in to the system, you just need to enter the corresponding URL (web address) in the browser, adding /typo3 (e.g. http://www.your-domain.com/typo3). There you will find the login window, shown in the following figure. Enter your user name and password here. Passwords for back-end users are transmitted in encrypted form by TYPO3 and saved securely in the database system.
63
3 TYPO3 for Editors
Figure 3.1 Login with username and password
3.3 User Interface and Module Softlink 502403
Back end is the name given to the user interface of TYPO3 where the editor works. The administration of pages and content through so-called front-end editing will be discussed separately (section 3.8). Once the editor has logged in, he or she will be in his or her workspace. Remember: the appearance of the user interface may change drastically from one editor to another, depending on settings made by the administrator. So you are either taken to a help page, with a short description of all the elements in the module bar, or to the module User | Task center. After clicking on one of the navigation options on the left of the page in the Web area you will see the structure of the back end:
Figure 3.2 The module Help | About Modules after the login
The user interface of TYPO3 is generally divided into three areas: the Module Bar on the left-hand side, the Navigation Area with the page tree in 64
3.3 User Interface and Module
the middle, and the Details View on the right-hand side.
3.3.1 Areas of the User Interface If several different editors are working on the same system, the User | Task center module (the TYPO3-internal communication and administration center) usually has preselected settings when it is called up for the first time. Here you can see the typical division of the user-interface into three parts.
Figure 3.3 The three areas of the desktop in terms of the Tasks module: module bar [1], navigation area [2], details view [3]
Module Bar The module bar is what the top navigation layer in the back end of TYPO3 is called. Here you can find a list of modules that are available for a particular editor. The main module (Web, File, Document,...) contains various submodules (e.g. Page, View, List, etc.), where actual editing functions can be found.
65
3 TYPO3 for Editors
Figure 3.4 Different back-end congurations: two users with different permissions and editing options
Navigation Area Depending on the module, navigation is done through the navigation area. In the main Web module you can see the page tree [1], where all the pages that the editor may see are displayed. Access to the file system for the main File module is obtained through the directory tree.
Exactly as in Windows Explorer and other file managers, the levels of the directory structure are expanded and collapsed with the "+" and "-" icons. If you click on the title, a Details View of the selected element will open on the right. If you click on an icon in the page tree, a context-sensitive menu opens for quick access to the most important work functions. For Windows browsers, this menu opens directly in the page tree, for other browsers, the functions appear in the top bar. Bear in mind the following rules of thumb: Click on icon= Call file functions (copy elements, cut, etc.) Click on title= View/Edit contents
66
3.3 User Interface and Module
Figure 3.5 Page tree [1] and directory tree for the file system [2]
Details View The actual workspace is represented in the so-called Details View (third column). Depending on the modules selected, various information and records may appear here. In the main Web and File modules, a contextsensitive menu is also available (remember: click on the icon), which simplifies your work.
3.3.2 Main Modules and Submodules—An Overview Web The Web module area is the one used most by the editor. Pages and content are stored, managed, and edited here. Individual sub-modules often allow you to achieve the same results using different ways.
Softlink 762976
Pages New pages and content are created and edited using the Page module, . 67
3 TYPO3 for Editors
The individual options are: Quick Edit The contents are opened directly in editing mode. Using another foldout menu or the graphical navigation in the footer bar, you can switch between the elements to be edited. Columns Displays the content of a page, according to how it is placed in the columns of the page, and according to the sequence of text. Languages Represents the contents of a page, sorted by language. Since multi-language applications can be implemented within a single page tree with TYPO3, administering several language versions is no great problem. Page Information Provides an overview of basic data for the selected page; you can see, for example, what type the page is stored as in the cache, whether it is to be published on a time-controlled basis, whether only certain front-end user groups have access to it, or what metainformation is contained in the page for search engines.
View The View module shows a page just as the visitor will get to see it later. It also includes small pencil icons that can be used to edit the page in View mode. In this mode you can view pages that have not yet gone online.
List The List View gives direct access to pages and contents. More experienced users in particular prefer working with this. By activating Extended View and the so-called clipboard using the checkboxes at the foot of the Details View, together with various sort functions, it is possible to edit records together, in a target-oriented manner. You can find more information on the use of this function in section 3.10. The Localization View gives you an overview of the current state of the translation of the contents.
Info In the Info module, important information on the current page is summarized. Depending on his or her access permissions, it provides the editor with different views of the database contents: 68
3.3 User Interface and Module
Pagetree Overview Includes basic settings (e.g. time-controlled publishing or access permissions for front-end user groups), cache, and age, as well as an overview of the types of records contained in the pages that may be processed by the editor. If you operate this view over several layers of the page tree, then the fields listed in each case for entire groups of pages can be edited with one mouse click, using the pencil icon. Localization Overview The translation overview allows you to enter several page levels to inspect the state of the translations. At the same time new translation headers can be added to alternative page languages, and you can edit these and the translation of the content. Log This logs all changes made to the records for each editor; the view can be adjusted in the navigation bar in terms of the number of levels to be displayed and the time period for the modifications. In the Details column the history of individual records can be displayed and opened for editing with the - > His link. Page TSConfig Page TSConfig is not of much significance to the editor, and should be deactivated by the administrator; the view shows the page-specific and user-specific TypoScript details, which are important for administrators and programmers (the rule also applies here: what has been determined in one page is also valid for all the pages beneath it). Hit Statistics Hit Statistics are useful for the daily evaluation of user accesses. Provided that the Simple hit statistics extension is installed on your system, the administrator can quickly find a good summary of individual page impressions for the web site.
Access If the module is released for the editor, he or she can have editing permissions displayed for individual pages, via the User Overview module. Only if the editor is the "owner" of the respective page, that is, if he or she has created it, can the editor, using the pencil icon, transfer permissions to, or remove them from, a group of which he or she is a member, or trans69
3 TYPO3 for Editors
fer the ownership of the page entirely to a different group member. The Permissions module lists owner, group permissions, and permissions for everybody. Also, here the editor may only change permissions of the pages of which he or she is the owner.
Functions The Functions module contains some practical help functions that can simplify the creation and administration of pages and contents. A prerequisite here, of course, is that the respective extension is installed and has been released for the editor. The various Wizards it contains allow entire page structures to be quickly created and sorted. The Import mode allows the import of entire page structures from a TYPO3 page tree. The Text tools allow specific text searches and the replacement of text passages in content elements. In section 3.10.6 we will take a closer look at the use of this function in practical situations.
File TYPO3 manages all resources, such as HTML templates, images, or documents, that are required to create a web site, on its file system in the fileadmin/ directory. The editor is granted access to the branches of the file system required, according to his tasks. In addition to this, the administrator can more precisely determine the type of access: for example, whether the editor is allowed to upload, copy, move, delete, rename, edit, or create new files, or even recursively delete files.
Filelist The Filelist submodule allows the editor to access the above-mentioned resources. The contents of the selected folder are displayed via the List View. You can also navigate here via the folder icons of the directory tree. To make files accessible, they can be uploaded directly from the editor's local computer or network to the respective directory in TYPO3, via the context-sensitive menu. Here the same rules of thumb apply as mentioned earlier: Click on icon = Call file functions (copy element, cut, etc.) Click on title = View/Edit contents 70
3.3 User Interface and Module
The checkboxes in the foot of the Details View activate thumbnails for image files, and the clipboard shows the content of the temporary storage space for moving or copying files.
Images The Images submodule reproduces image files in a preview, with details of the file size and its measurements in pixels.
Document The Document module is useful when accessing pages or page contents that you have opened for editing. If you have a number of records opened, it allows you to change quickly between different editing steps and modules. Thus you can, for example, change efficiently from the file system to editing a content element. You can navigate between records via the foldout menu. If no documents are open, a list is shown of the last records to have been processed.
Figure 3.6 Display of the last records to be processed in the Document module
User The User module shows the tasks and personal settings for the respective user, and also offers the possibility of communicating with other users.
Task Center Hidden behind the nondescript term "Task Center" lies the communications center of TYPO3. Various submodules allow, for example, personal notes to be saved, or allow communication among project members within workflows and within the messaging system. We will describe the module in more detail in section 3.4.
71
3 TYPO3 for Editors
Setup Softlink 582216
Every user has the opportunity to adjust the work environment of TYPO3 to a certain extent to his or her needs. This starts with the selection of the language in which the back end is presented. There are currently 41 languages integrated into TYPO3. In addition, the display of the back end can be adjusted accordingly to your own preferences and to the performance of your monitor. In this way the module bar can be displayed as a selection box or in icon form in the top frame, to save more horizontal space. You can decide here if you want to have help text displayed for the individual fields of the data input dialogs, or if you want images in the list to be displayed by default as thumbnails. The context-sensitive menu or the Rich Text Editor (for Text or Text w/image content elements) can be deactivated, recursive copying limited to a certain number of levels, or you can decide if recursive deletion should be allowed at all, or switched off. Either way, it is recommended that you activate file upload via the Document module and the Element Browser, to be able to work more effectively: this allows an "interim upload", without having to change to another module just for this purpose. The values that can be set here can be preselected centrally for users and groups by the administrator, whereby the settings can be permanent or temporary (see Chapter 4.8.2). If this has not already been done by the administrator, your name and email address should be entered in the "Security" area. A number of extensions, such as the News module, use these details to automatically determine the author of contributions. Activate the checkbox at the end of the form in order to be informed by e-mail about every login that uses your user name.
Help Softlink 647456
The Help module can contain several submodules. As a rule, About modules, About TYPO3, and Manual (the TYPO3 Inline User Manual) are activated; the first one introduces the main function of individual modules, the other one offers information on the version used and the copyright, and points out the TYPO3 license conditions. In order to always have available the description of all areas relevant to the editor and their entry options as online documentation, the "Manual for Editors" can also be integrated into the TYPO3 back end as an extension.
72
3.4 The User | Task Center as a Communication Center
3.4 The User | Task Center as a Communication Center TYPO3 provides various functions in this module that help in the general editing of contents in a workflow, and which can also access certain actions and contents from the page tree quickly. There are also other important functions for simplifying and summarizing tasks in one particular area of the system. If the module is called via User | Task center, the navigation area displays the functions for selection. The functions are described below in more detail, in the order they appear.
Figure 3.7 Navigation area of the User | Task Center module (example view)
3.4.1 Quick Note The entry field provides the back-end user with some storage space for personal comments, notes, and other texts, which he or she will be reminded of in the next session. The entries are not visible to other users (with the exception of the administrator).
Softlink 740912
3.4.2 Recent Pages The Recent Pages function lists the last pages edited by the current user as links in the navigation bar. If you click directly on the Recent Pages menu item, there is a choice of frequently edited records, sorted by processing date. This is also useful if you want to retrace your steps in the editing history, for a session that took place a while ago. 73
3 TYPO3 for Editors
3.4.3 Actions Softlink 748421
The administrator has the possibility of assigning predefined actions to individual users or user groups, through so-called "actions". The types below therefore refer to the function, and not to the name under which the action is displayed in the User | Task center module. Create Backend User Here an editor can create a new back-end user, with only a few details and without administrator permissions. The administrator can assign his or her own name to these commands (e.g. "create new product manager") and use the command type "Create backend user" to do this. SQL Query This is of help if you want to obtain a predefined output of data from the database directly, for example, to call product records or transaction data, and then export these in the CSV or XML format for use in external programs. Record List The record list shows the elements of a definable position in the page tree, in order to access this directly in the Details View of the Web | List module. Edit Records Creates a definable list from any position of the page tree, and consisting of any elements (pages, page contents, any other records), that in this way can be made available for special quick processing. Creating actions is explained in more detail in section 4.10. When an action is run, the Details View shows the type of action, a description, and the record that is to be created or modified.
Figure 3.8 Details view of a simple action for editing a page
74
3.4 The User | Task Center as a Communication Center
3.4.4 Messages In the Messages area, the editor will find a simple messaging system for internal project communication. The editor can use this to send and receive internal messages to individual members or to entire groups. New messages are displayed in the User | Task center module and stored in the Inbox folder [1]. Mail inboxes can be moved to an archive or deleted [2]. For a user who is sent a message to notice this before he next logs in, the sender can send a message directly to the e-mail address of the user. This assumes, of course, that the web server also has a mail server. Received messages [3] can be answered using the original message [4].
Figure 3.9 You have mail: mailbox folder [1], moving or deleting emails folder [2], message content [3], reply to messages [4]
3.4.5 Tasks The Tasks function area contains the workflows for the editors, defined by the administrator. 3. In the navigation bar the To-Do entries for the editors 3 How workflows are created is described in section 4.9.
75
3 TYPO3 for Editors
are displayed. Depending on permissions within a workflow, the editor may be authorized to start new tasks. An author can only carry out one processing step and make a status change, or cause the record to be released. The Details View (3rd column) in the header shows incoming To-Do entries [1], outgoing To-Do entries [2]—as long as permissions for this exist—and the corresponding selected entries [3]. The status log [4] notes all the instances through which the record has passed until now, with the option of opening the record for editing. If the editor has completed his editing, or certain points are still unresolved, he or she adds a new status, with a comment, and sends the workflow on for further processing [5]. Only task managers are authorized to start a new workflow [6].
Figure 3.10 Editing a record by means of a workow via the Task Center function area
76
3.5 Pages as Containers for Contents
3.5 Pages as Containers for Contents 3.5.1 Site Structure, Page Tree, and Contents Before we present the main tasks performed by the editor (creating pages and content), we would like to say a few words in advance about the basic concept of TYPO3. This is aimed primarily not at an understanding of the technical background but (a) at handling hierarchies safely when creating site structures, which are mirrored in the front end in the shape of menus, and (b) at an understanding of how content for individual pages behaves. To illustrate this, we have chosen an example of a small application from the classical B2C-environment. This already contains different pages of various types (see the following figure). In the course of this book we will modify this example application. We would like to encourage you to set it up for practice purposes. In section 5.9 we will use a variation of this as a basis for the further development and configuration of front-end outputs. The page tree of the web site consists of individual pages, such as "Home", "Imprint", and "Contact", and the main areas "News", "Events", and "Products".
Figure 3.11 Page tree of the example web site
A page itself does not have content saved within it! It merely serves as a frame or container for those elements that are assigned to it. The editor in TYPO3 hardly has to worry about technical issues. The only 77
3 TYPO3 for Editors
things that matter are at what points, in what sequence, and of which type he or she should create new pages and subpages in the hierarchy of the page tree, and how to move these around, if necessary. Handling is taken over by TYPO3 internally. Each page has a unique identification number (ID). It appears if you move the mouse over a page icon, and it is also shown in the editing form of the page title. In the preceding figure you can see ID 56 for the page "B2C Home". The editor does not need to know the IDs, even if they play a crucial role in the background. Internal TYPO3 links use IDs for reference. This has the advantage that the links remain, even if a page is moved about, since the IDs are never changed. The site structure is shown in the page tree. This ordering principle should be very familiar to PC users. The tree stands on its head, so to speak: the globe (right at the top of the page tree) forms the roots (also called root or Rootline). Pages can be added to any point of the tree, which form branches. Individual pages, or even whole branches of the tree, can be moved. This structure also matches the navigation structure of the web site, because the menus are created from it. What can also be seen from the various icons in the page tree are the different page types. TYPO3 already provides a number of preconfigured page types, which differ in their behavior and functionality. Certain settings are also made clear by the icons, such as hidden pages, access permissions, and time restrictions. Below we will explain the individual page types and additional functionalities in more detail.
3.5.2 Creating and Editing New Pages Softlink 195486
78
Creating new pages with TYPO3 is very simple: in the Web module area, select the Page or List submodule. The navigation area now shows the page tree with all those areas to which you have access. To create a new page, call the context-sensitive menu by clicking with the left mouse button on the icon for the page to which the new page should refer. Select the action New. In the Details view, pages or content can now be created in various ways, depending on the extensions installed and their permissions in the system. Depending on where you want to create the new page, select Page (inside) (page is created one level further down) or Page (after) (page is created on the same level). If you prefer to create the page via the Wizard, you can simply define the position by clicking on a positioning arrow.
3.5 Pages as Containers for Contents
Figure 3.12 Context menu for the “Product 3” icon [1] and Detail view [2]
After defining the position, you are taken to the create page form. The basic structure of this Details view is always the same for pages and content elements: the header and footer contain icons for saving (floppy disk), saving and viewing (floppy disk with magnifying glass), saving and closing (floppy disk with X), undoing changes (X) or deleting the data record (trashcan with yellow warning triangle). If the data record has already been edited, editing steps can be undone using the undo button (wavy blue arrow). With two selection lists, you can either switch between two opened data records or initiate actions such as "Save Document" or "Clear Page Cache" [1]. Specifying the page type and entering the compulsory details (marked by a yellow warning triangle if the corresponding field has not been completed) is done through the form fields. These are organized by subject, in blocks. All page types have the blocks Type [2], Pagetitle [3], Localization settings [4] and General options [5] in common.
Figure 3.13 Figure 3.13 Details view with input form when creating a new page (type: Standard). Not visible here for the editor: the fields TSconf and General Record Storage page
79
3 TYPO3 for Editors
Type TYPO3 provides a series of predefined page types, simplifying daily work. They differ in terms of their functionality and their appearance in the front end. The most important ones for the editor are Standard and Advanced. The form block also contains the Hide page marker, with which a page can be switched online (visible) or offline (hidden). If a page is "hidden" (that is, not visible in the front end), this is marked by a faded page icon with a red cross.
Pagetitle The Pagetitle is the only compulsory field when creating new pages. Within the advanced options (page type: Advanced), you can assign a so-called Alias to the page, and you can then call the page using the URL http://www.your-domain.com. As a rule, pages are "cached"—they are generated entirely by TYPO3 and the result is stored in the database. Why is this done? It costs time and server capacity to generate a page. An already created page can be served much quicker. In order that the cached pages are still up to date, they are freshly generated every 24 hours. But this cache interval can be set individually by the administrator for each page or area. The editor can, however—assuming he or she has the appropriate permissions—overwrite the cache interval, or even specify that the page should not be cached at all (No cache). This may be necessary for pages with content that changes by the minute, or by the second (e.g. stock market prices or in a forum).
Localization Settings Here you can determine whether the respective page is translated into the default language in general, or if it remains off-line only if no translation is present.
General Options Here you can define the behavior of a page for a time-controlled publication or for a page with restricted user rights. Start specifies the time at which the page will automatically be switched online (made visible), Stop is the time at which it will become invisible. Date fields use the format "day-month-year", that is, "23-01-2004", for example. A tip: if you enter d and move with the tab key to the next field, the current date is entered automatically in the correct format. If you want the page, for example, to be published automatically in 14 days, simply 80
3.5 Pages as Containers for Contents
enter d+14. With the Access fold-down menu, a page can be displayed in the front end exclusively for certain groups, and you can also specify whether a page should be visible or invisible after logging in to the front end. With the Include subpages marker, you can apply the above mentioned settings (Start, Stop, Access) to all sub pages of the page selected. All form input fields contain context-sensitive help in the question mark icon. The Form with a hand icon [6] allows optional entry fields (More options) to be shown in the gray horizontal bar at the top (not shown in the picture). In the page footer [7] you can alter the Details View via checkboxes or restrict the functionality for all text context elements on this page. You can obtain a short description by clicking on Show field descriptions. Clicking on Show secondary options (palettes) displays the optional entry fields directly in the Details View. In this way you can decide if you want to have the form clear, or prefer to have all the options permanently displayed. Via the Disable Rich Text Editor (RTE) checkbox, the RTE can be activated or deactivated for all page elements that use it as an option.
3.5.2 Different Page Types The page types define in the first instance what part of a page is visible in the front end and is displayed in the menus, or whether it is just serving as an invisible data storage for the back end. You can see what a page is used for from the icon in the page tree.
Standard The Standard type is usually sufficient; it provides a simple selection of the most important information on a page, as already shown above. When changing to a different page type with more or different options, and switching back again, the extra entries outside the options of the Standard type are not lost. So if you have made entries in fields that are only available for the Advanced type, and you change this type to the Standard type, all the entries will still be available if you change back to the extended mode. From a technical point of view the page types are just different input dialogs for different sections of the same database table (Pages).
Advanced The Advanced page type provides considerable advantages: meta-information can be specified here, and files and plugins can be integrated. You can also give the page a title different from the navigation title, so that the 81
3 TYPO3 for Editors
page can appear in the navigation of the web site with a different name than in your back end. Meta-fields like Abstract, Keywords, and Description are important for external search engines and for the internal TYPO3 search function. Correspondingly informative titles are recommended when naming pages. A number of extensions must be integrated directly into the page via Contains plugin for them to function. If Files are to be integrated from the file system or from your local network via the Element Browser, it depends on the configuration of the template whether and how they are displayed.
Figure 3.14 Integrating files from the file system via the Element Browser [1] or “Browse” [2]
Depending on the task, you can search through pages or directories of the file system with the Element Browser, for example to integrate records, place links, or integrate files directly (e.g. images, video, sound, print). Individual files are integrated by clicking on the title, or are grouped together using the "+" sign. You can also create new folders or upload files from the local workplace to the server, from the page or content editor.
Figure 3.15 Element Browser accessing the file system: directory tree [1], individual selection of files via the title or multiple selection via "+"' [2], file upload to the file system [3]
82
3.5 Pages as Containers for Contents
External URL The External URL page type refers to an external web, FTP, or e-mail address. The page itself does not have any content. The page type is used to integrate links to external applications in the menu structure in the front end. Enter the address and protocol type.
Softlink 132947
Figure 3.16 External URL
In special cases it may be interesting to specify an internal URL, for example to address a plugin with the corresponding parameters, in order to link a news entry directly as a new page, or something similar.
Shortcut The Shortcut (link) page type is applied in the same way, with the slight difference that it refers to an internal page. In our example application, the "Home" page is of this type. It is used when no content is included in the page, although it will still appear in the menus in the front end.
Softlink 524611
This page type has two modes for defining the target page: 1. A special page, or even a specific page content, can be defined as a jump label by the Element Browser. 2. With the Shortcut Mode function (reached via extended options), a link can be made to the First subpage or to a Random subpage. In the example application, the first method was applied to link "Home" to the root page of "B2C Home". Figure 3.17 Shortcut via the Element Browser [1] or Shortcut mode [2]
The Element Browser can be used in the context of the page tree in a similar way as in the directory tree. This user concept is applied consistently in TYPO3 and is also used in the Rich Text Editor to maintain links manually. As an additional help, the Element Browser simplifies the quick search for pages or contents via search terms.
83
3 TYPO3 for Editors
Figure 3.18 Element Browser links to the contents of another page via a shortcut: page tree [1], select records via the title via + [2]
Not in Menu Softlink 157087
The Not in menu page type is closest to the Advanced type in terms of the entry fields. What distinguishes it from this page type, however, is its behavior in the front end: it can be called directly via the ID number, but no menu item is generated for it. In the example application, the "Imprint" and "Contact" pages are of this type.
Backend User Section Pages of the Backend user section type are only visible to users in the front end if they have previously logged in to the back end. You also require read permissions for these pages, and in addition the front-end view must be called via the back end. Do not confuse the back-end user area with a login for closed areas via the front end, because this is not regulated via the page type, but via the Access field of the individual pages and content elements.
Mount Point The Mount point page type integrates page shortcuts where it is used (similar to the symbolic link familiar in Unix circles). In doing so, it not only points to the target page set in the Mount Point (advanced) field using the Element Browser, like the shortcut, but also ensures that the format defaults for the output page are kept (even if the target page uses a completely different design). This is achieved through parameters which are added to the respective pages called: index.php?id=13&MP=8-81 can be translated, for example, as
84
3.5 Pages as Containers for Contents index.php?id [page called up]&MP=[target page]–[output page].
In this way you can, for example, set up a common content pool used by various different web sites. The content is then displayed in each case in the individual design of the page.
Spacer Pages of the Spacer type help to structure menus. In the front-end menu, the page title appears, but it is not linked. This means that you can create temporary headings in menus, for example. The display must already have been defined by the programmer using TypoScript, of course.
SysFolder The SysFolder serves primarily as a container for records. It is not shown in the front end. It can be used for pages and content, but is principally intended for the administration and structuring of records not intended for display in the front end (e.g., categories for the news extension by which messages are classified, or the collection of front-end users and groups). In our example application, this function is used by the "functions" page. But entire page areas can also be created within a SysFolder, if they are intended to bypass the automatic menu creation procedure. Under "Individual dates", pages were created in our B2C application, to be queried in the content area.
Recycler The Recycler behaves like a SysFolder, with the difference that its defined area of application is symbolized with its own icon. The Recyler is intended in TYPO3 to have its own page type so that back-end users have a place where they can move records without having to delete them immediately. So records are not moved automatically to this folder when they are deleted! Once records have been deleted, you have no more access to them. If they are stored in the Recycler, they can be retrieved and processed at any time. With the undo or history functions, you can return them to their original position in the page tree.
85
3 TYPO3 for Editors
3.6 Content Input with TYPO3 Until now it has been shown that pages merely provide the framework for content, and that TYPO3, as a content management system, can integrate any number of content elements into a page. Inside a page, contents are categorized by columns and by language. The columns concept allows templates to assign specific areas to an application in which the contents of the respective page are grouped together. In this way a template can, for example, specify a division into a main area and a smaller side area (e.g. for a news ticker or other service). Each page can take on any amount of content. The sequence of content in the front end always matches the sequence of the column view of the back end (module: Page | Columns).
Figure 3.19 Display of two content areas in the front end and in the details view of the back end (module: Page | Columns)
By default, TYPO3 provides four preset columns: Left, Normal, Right, and Border. Normally not all the columns are required. But during implementation, further areas could be added, or existing ones renamed. The administrator decides in addition which areas can be accessed by a specific editor, and can switch off columns that are not required. The language concept of TYPO3 behaves in just the same way: the same page can contain contents for different language editions. In this case the contents are filtered into a language, depending on instructions, and 86
3.6 Content Input with TYPO3
shown in full in the back end, in the Page | Languages module. Managing multi-language web sites is discussed in more detail in section 3.10.8.
Figure 3.20 Details view of the back end for administration of language versions (module: Page | Columns); contents input here restricted to Normal and Right columns
3.6.1 Creating and Editing New Content The form for creating contents is very similar to the one for creating pages: in the context-sensitive menu of the page tree in the Web module area, click on the New option. Possible data types that can be created appear in the Details View. Now select the type of new page content in the assistant and define its position within the page.
Softlink 533217
87
3 TYPO3 for Editors
Figure 3.21 Assistant for creating contents: selecing content types [1] and options for positioning [2] the new content
The Details View that now appears for creating new content resembles the one for setting up pages: the header contains the menu bar [1], and in the footer the viewing and entry options for the form areas can be adjusted [5]. If the Rich Text Editor is switched off for the Text or Text w/image content elements, simple options for formatting the text are not included. This can be very useful, for example, if you want to check changes made with the Rich Text Editor in the source code. The content types all have the same form areas for specifying the Type [2], Header [3] and General options [4]. If the secondary options (palettes) for the entry fields are deactivated, these can be called up with the appropriate icons in each context [6].
88
3.6 Content Input with TYPO3
Figure 3.22 Entry form for the text content element
Type In the content input form you will find a selection list for various content types (so-called CTypes or content types), from simple text to multimedia elements. If a content type is changed, the entry fields are automatically adjusted to the requirements specific to that type. The individual types are briefly introduced below. When making entries in the Type form area, it is important to assign the content to a specific Column—and for multi-language applications, to assign the relevant Language as well. The fields are available via the extended options. Before and After define the space (to be given in pixels) between this and the next content element. Via Frame, the element can be indented, framed, given a colored background, or underlined. With the Index checkbox you can specify whether the content element should be listed inside the Section index (pagecontent w/Index checked) menu (this is used, for example, for content details of long text passages, which cannot be seen at one glance). To top adds a small link to the page element (a so-called jump label) if it is activated. With this you can move back to the top of the page with just one click, instead of having to scroll through a number of screens.
89
3 TYPO3 for Editors Figure 3.23 The Type form area
Header When it is displayed, the header normally stands out from the content element, and is formatted in bold type. With Type, various layouts can be assigned to the header, which are then implemented accordingly. If you do not want to display the header in the web site, simply activate the Hidden option. Other form fields allow you to align the header (left, middle,
right) or to add a link or details of date to it. A number of content types, such as Insert record or HTML, do not have a header in the basic configuration, so they don't have any additional extended fields either. These content types only have the Name field. Figure 3.24 The Header form area
General Options Just as in the General options for editing pages, individual contents can also be made invisible via Hide. With the Start and Stop fields you can specify a time-controlled publication. With Access, you can set the element so that it is only visible to certain front-end user groups. Figure 3.25 The General options form area
3.6.2 The Different Content Types Even in the basic installation, TYPO3 has a whole range of content types covering all standard requirements for input. In addition to this you can include your own content types via extensions. The most important of these are presented on the following page, with examples to illustrate them. Details concerning the adjustment of individual content types for front-end output are given in Chapter 6.
90
3.6 Content Input with TYPO3
Figure 3.26 Display of content types in the backend
Header The Header content type is seldom used as it is already integrated into most content types. It differs from these only through an additional entry option for the subtitle and various layout details.
Text The Text content type is used very frequently for text passages. It is entered in the Text field and can be adjusted via the Bold, Italics, Underline, and Uppercase checkboxes, or the extended options Align, Fontface, Size, and Color. Formatting here always applies to the text as a whole. If you just want to rearrange individual passages (e.g. add links or images), do this in the Rich Text Editor.
Figure 3.27 Text content type: form area for input
Image Inserting images into a page is normally done via the Image or Text w/image content element. To do this, select the images with the Element Browser from the media administration in the system, or load them directly from the local network using the Browse button. With Position you can define the alignment (align left, centered, align right). With the Text w/image content type, this defines the positioning of the image relative to the text at the same time.
Softlink 550518
If you want to use several images, you can arrange them in an invisible table, using the Columns option. The rows of the table are adjusted to the size of the widest pictures in the table columns. This effect of automatic adjustment can be switched off by clicking on the No rows checkbox. Now 91
3 TYPO3 for Editors
a separate table is made for each row, adjusted in its proportions to the images contained. In addition, you can have a border displayed around the image, by activating the Border checkbox (to create additional contrast, for example).
Figure 3.28 Image content type: integrating images from the file system via the Element Browser
TYPO3 can integrate any image format and also edit it with its internal graphics functions. You can change size, quality, and format in this way. You can specify the size of the image using the Width and/or Height (in pixels) input fields. Via Quality you can define the format (GIF, PNG, JPG) as well as the color depth or compression rate with which the images are displayed. It is even possible to post-process images and add Effects. In this way you can set contrast, brightness, sharpness, or normalization, convert color to greyscale, and rotate images by 90 or 180 degrees. If required, images can be framed not just singly, using HTML, but combined with frame images (see the following figure). Select them under Frames. The default installation includes two examples of these, the "Artists" and "Darkroom" series in the directories tslib/media/frames/. These can, of course, be adjusted individually when a developer is implementing the system (see styles.content.imgFrames in the styles.content (default) standard template).
92
3.6 Content Input with TYPO3
Figure 3.29 Setting frames using the example layout 2 in the ‘darkroom’ series
Images can be provided with a link via the Link field, or set using the Click-enlarge checkbox, so that the image is shown in its own window, in its original size, if you click on the thumbnail. Captions are normally displayed beneath the image, but they can be positioned (align left, centered, align right) via the Align option. When
assigning image texts to several images, the text should be entered in the same order as the images, with a separate line for each text. Note: When configuring the output, the template must be adjusted so that the assignment of texts to individual images is set with styles.content.imgtext.captionSplit = 1
otherwise only one image text block will be shown for the images.
Text with Image The Text w/image content element is a combination of the Text and Image types and contains setting options for both elements. In addition the arrangement of the elements relative to one another (including text flow) can be changed with the Position option.
Bullet List The Bullet list content element is ideal for making lists. Each line entered in the text field is shown in the front end as a list item. Breaks within a list item are implemented with the HTML expression .
Softlink 552631
Four different types of Layout are available, which by default use either icons, numbers, or checkmarks to separate them optically. These can, of course, be individually adjusted by the developer. As with the Text content type, text can also be formatted here. Available features are Bold, Italics, Underline, and Uppercase, and there are options for Align, Fontface, Size, and Color. 93
3 TYPO3 for Editors
Table Softlink 727880
To insert tables, the Table content type is used. Here as well, each line of the field stands for a row in the table. Individual columns within a row are distinguished by TYPO3 through the "|" character (the "pipe" icon). Here is an example of a two-row table with four columns (there is an empty space in the first column): | Column 2 | Column 3 | Column 4 Row 2 | Apud Helvetios... | Ea res... | Damnatum...
The text in the second row is abbreviated here in the example. This input results in the following table:
Figure 3.30 Example table using the standard layout 3
The appearance of the table can be changed through the Layout field. In the standard configuration, four variations are available, with which you can add color, for example, to header rows and columns. There are also options to set the Background Color, the width of the Border to be drawn, the Cellspacing, and Cellpadding. The number of columns is either detected automatically or determined manually via the Table Columns foldout menu. However, if only three columns are defined, for example, then other columns will be ignored if more than three are entered. Formatting the content is done in the same way as in the Text context type, via features and extended options.
Figure 3.31 Form for specifying the Table content type
94
3.6 Content Input with TYPO3
After the content element of the Table type has been saved for the first time, a wizard is available that simplifies the setup. It is called by clicking on the icon to the right of the text entry field. It opens in a separate window where you can conveniently edit, delete, and add content in a graphical interface. If individual fields are too small for you, because you want to enter large amounts of text, you can enlarge these with the Small fields checkbox.
Figure 3.32 Assistant for creating table contents
Filelinks The Filelinks content type is used to integrate and list various file types from the file system. They are displayed in the front end in a table; depending on the media type, a visitor can open the link or download it.
Softlink 976910
Figure 3.33 Example of the File link content type to depict various media
Files can be integrated in an uncomplicated manner, using the Element Browser, the Browse button, or via Read from path. The editor opens the Element Browser via the Files entry field, searches there for folders released for him or her, and selects individual files from these folders. Alternatively files can be uploaded from the local workstation and inserted using the Browse button. With this method, however, the files are generally not available in the Element Browser, because they are stored internally in the system, not in the directory fileadmin/, but in 95
3 TYPO3 for Editors uploads/media/.
To display all the files in a directory, you need to specify the Read from path.
Figure 3.34 Form for the File link content type
Filelinks can be displayed in the front end (via the Layout option) in four different variations. These are preconfigured in TypoScript, and in the default setting they display the title together with the file type icon or preview image. Because the display in the front end is of a table, the background color, border, cell spacing, and cell padding can be adjusted individually. Certain information can be added to the file title with the Show filesize checkbox and the Descriptions entry field. As with image texts, each file element has a separate line. The arrangement must also be configured, as with image texts, using a TypoScript entry in the template (styles.content.uploads.descriptionWrap).
Multimedia Softlink 986146
With the Multimedia type you can include files in the formats TXT, HTML, HTM, CLASS, SWF, SWA, DCR, WAV, AVI, AU, MOV, ASF, MPG, WMV, or MP3 as page content. They are selected via File, either using the Element Browser, or stored directly from the local work environment in the system internal directory uploads/media/. In the second case, the rule again applies that a file uploaded in this way to the Element Browser is not generally available, but is only used on an ad hoc basis for this one content element. The required Parameters for playing back videos, audio files, or Flash films can be entered in the corresponding field. The following parameters were set for a Flash film, for example: WIDTH=70 HEIGHT=55 LOOP=true QUALITY=high
96
3.6 Content Input with TYPO3 BGCOLOR=#FFFFFF TYPE="application/x-shockwave-flash" PLUGINSPAGE=http://www.macromedia.com/shockwave/download /index.cgi?1_Prod_Version=ShockwaveFlash;
Form With the Form content element, e-mail forms can be created. An assistant is available for this purpose, which uses the following notation. In the Configuration form area, each line defines either a form field or a function.
Softlink 404318
Name: | *name=input,40 | [Please enter your name] E-mail: | *email=input,40 Your address: | address=textarea,34,4 My vote on TYPO3: | Vote=radio | Super=super, Great=great, Unbeatable=unbeatable | formtype_mail=submit | Send! | html_enabled=hidden | 1 | subject=hidden | My opinion of TYPO3
The e-mail form is shown as a table. The "|" sign is again used here to separate the title (description or comment), form field type and configuration details.
97
3 TYPO3 for Editors
First value Second value (Title) (Form field type)
With the Jump to page form field of the content type you can specify the page to which the user is taken after an e-mail is sent. This confirmation page should definitely be set up, to inform the user that his or her e-mail has been sent. A priority in the entry options is to specify a valid Recipient-email. Several addresses can be given here, separated by commas. Once you have saved the entry, the above-mentioned assistant can be called by clicking on the icon to the right of the entry field. With this you can create and configure various types of form fields (remember to save regularly!). In the footer of the assistant you will see a checkbox with which you can activate HTML mode for e-mails. 98
3.6 Content Input with TYPO3
The assistant then translates your entries automatically into the already mentioned form syntax.
Figure 3.35 Form assistant and output in the front end
Search A simple but powerful search function is already included in the basic TYPO3 installation. Using this, the front-end user can search through the site for contents, headings, and keywords. The corresponding form is created via the Search content type. If the search result is to be displayed on a separate page, and not on the same page as the form, a Send to page must be specified—this should be created beforehand (preferably of the Not in menu type).
Softlink 481291
99
3 TYPO3 for Editors
Figure 3.36 Input form with search result on the same page
Softlink 724882
Apart from the standard search, there is a more powerful variation, the Indexed Search Extension, which if necessary can be installed and used.
Login Softlink 673847
Via the login form the (authorized) visitor reaches the areas in the front end reserved and protected for him. The login form is generated via the Login content type. A page can be defined as the Send to page via the Element Browser, to which the user is taken automatically after logging in. This assumes, of course, that front-end users and groups have been correctly set up and that the login form also "knows" where the user data is stored. In our example applications, B2B and B2E, the user data is located in the FEUser system folder. Administrators can adjust this using TypoScript (fe_adminLib.pid = [uid]) or by specifying a second send to page with front-end user data. More information on front-end user systems and setting them up can be found in Chapter 4.11.
Figure 3.37 A simple login form
Textbox The Textbox content type allows the editor to use predefined layout defaults for text passages. In the default configuration, text is inserted into a two-column table, where the left column can display images with various 100
3.6 Content Input with TYPO3
borders, and the text is indented by 30 pixels. The layout (each one specified by the developer) is selected via Textbox type.
Figure 3.38 Entry area for the Textbox content type
The following output is created with the default configuration (see content (default)):
Figure 3.39 Output example for the Textbox content type
Menu/Sitemap The Menu/Sitemap page type contains various content elements that help navigation. They can create navigation menus, content details of pages, and display a sitemap of the entire web site. Select the functionality via Menu type, and choose one or more entry points for the menu type via Startingpoint. If no startingpoint is specified, the page on which the menu is located is automatically used.
Softlink 528240
Figure 3.40 Various menu output variations of the Menu/Sitemap content type
101
3 TYPO3 for Editors
The following menu types are preconfigured: Menu of these pages Creates a list of linked page titles for the selected starting points. Menu of subpages to these pages Generates—depending on which page was selected as the starting point—a list of the next highest or next lowest page level. Menu of subpages to these pages (with abstract) This displays the title and content details of subpages. To do this, the content details must be entered in the corresponding field for the page title in the Extended page type. Menu of subpages to these pages + sections This menu displays the page title and headers for the content elements for which the Index checkbox was activated. Sitemap In the default configuration this generates an overview of page titles in a tree structure and the level to which it goes can be adjusted; the layout is determined via TypoScript (styles.sitemap.text). Section index (pagecontent w/Index checked) This menu type is suitable for content overviews for more extensive pages. The headers of all content elements whose Index field is active are displayed. Recently updated pages Lists the last ten pages that have been modified within the last seven days, and which are not excluded from the list because of the No search field. Related pages (based on keywords) Displays all the page titles of pages that contain the same keywords; pages are also excluded from this search if their No search field is active.
Insert Records Softlink 133467
102
The Insert records content type allows content elements to be used more than once in a web site. In doing so, the record is not copied, but only a reference to the original is created. If the original is updated, then all references are equally as up to date as possible.
3.6 Content Input with TYPO3
Via the Items field and the Element Browser, relationships to all classical content types, as well as entries for plugins (e.g., an address record) can be created. If special format templates are to be assigned to display the records in the front end (they can be adjusted via the Layout field), these must have been defined beforehand in the page template in TypoScript.
Figure 3.41 Insert record content type
Insert Plugin Front-end plugins and extensions organize more complex content structures in the form of categories, lists, and detail views, or make additional functions available, for example, for the shop or for the Indexed Search. In order for a plugin to be correctly displayed in a page, the relevant extension must be installed and correctly configured by the administrator beforehand. The installation is explained in more detail in Chapter 6.
Script With the Script content type you can integrate your own functions into the web site. To do this, the developer must define the function in the template, and then it can be called via the CODE field. Example: the following configuration should be integrated into the setup of the template with sectionscript: tt_content.script { key.field = select_key sectionscript = PHP_SCRIPT sectionscript.file = fileadmin/editor/script/section.inc }
The validity of the script can be specified for several page layers with the Startingpoint and Recursive fields. Additional Parameters are passed on to the script in the corresponding field. 4
4 These notes are only made here for the sake of completeness, since editors should
normally not come into contact with this content type, for technical security reasons.
103
3 TYPO3 for Editors
Divider The Divider content type serves merely to structure more lengthy contents of a page in the back end—and with the corresponding configuration (such as as an tag) in the front end as well. Content can be split into blocks with this.
HTML This content type allows the input of pure HTML code. It should be deactivated for editors, not least for reasons of security.
3.7 Assets in TYPO3 3.7.1 Managing Assets in the File Structure Softlink 599239
By assets we mean files and media of all kinds that are required for a web site. These can be images, sound, videos, and documents of any type, but they can also be format documents, such as stylesheet files and HTML templates. They are stored on the web server and made available in TYPO3 for processing and integration. The central location for this in TYPO3 is the fileadmin/ directory. Here it is advisable to create as sensible and clear a directory structure as possible, so that everyone can find their way around quickly. In particular, rules for user and group permissions should be taken into account when doing this. The administrator has the task of setting up the structure and granting individual editors access to specific areas of the file system. Depending on the size of the application, grouping files according to media types and structuring folders to match the page tree is recommended as good practice, because editors can understand such a structure easily and quickly. When permissions are assigned, attention should be paid as to which users are given permissions for the administration of the branches of the directory tree to which they have access. The number of assets normally grows very quickly. For this reason it is useful to keep them in directories that are of a manageable size. To implement this, selected editors must have permission to create, rename, copy, and/or move directories. Assets are managed in TYPO3 via the back end in the File | Filelist module. The directory tree in the navigation frame [1] shows the folder structures released for the respective editor. Clicking on the folder name causes the contents of individual folders to be shown in the Details View [2]. The context-sensitive menu is also available here, in both areas (click
104
3.7 Assets in TYPO3
on icon). With these, files can be Renamed, Information can be displayed, and files can be Copied, Cut, or Deleted. At the bottom of the Details view you can have the clipboard or thumbnails displayed for images, by checkboxes [3]. The clipboard is always available in TYPO3 and allows you to move, copy, or delete files and contents. Even batch operations are possible with this. You can find more information on this in section 3.10.
Figure 3.42 Asset administration via the File | File list module: restricted access for the file mount mediapool
The context-sensitive menu of the directory tree includes the actions New and Upload Files. You can create several folders at the same time via New, or create text files in the formats TXT, HTML, HTM, CSS, INC, PHP, PHP3, TMPL, JS, or SQL—but certain formats may be deactivated for security reasons. Using Upload Files, up to ten files can be uploaded simultaneously from the local network to the TYPO3 file system. When doing this, existing files can be overwritten, if requested, otherwise files with the same name are renamed by default with a sequential number.
Figure 3.43 File upload of localfiles to the TYPO3 file system
3.7.2 Inserting Assets into an Application To upload files, you do not have to switch specially to the File module. Files can also be copied to the web server while pages are being created in the File Manager. The Element Browser can be used both to select existing files and to upload files [3] (overleaf).
Softlink 525663
105
3 TYPO3 for Editors
Figure 3.44 Linking files via assets in the file system [1] or one-off via Browse [2]; the steps shown are for inserting an image file in the Image content element
You generally have two ways of handling file resources: selecting them from the file system via the Element Browser [1], or directly via the Browse button [2] (upload from the local workstation). Depending on how the files were copied to the web server, they will be stored at different locations, which is of significance to their availability. A file in the file system is available for multiple use on the entire site through the Element Browser. This is not the case with a direct upload [2], because the file is stored in an internal system directory (uploads/), to which the editor has no access. If the file is integrated several times via the Element Browser, TYPO3 recognizes this and numbers the image copies (automatically) with a unique combination of numbers (e.g. book.gif, book_01.gif etc.). The Rich Text Editor behaves in the same way when integrating graphics. The original file here (e.g. *.bmp) as well as the target format (e.g. *.jpg) are both stored and referenced as unique objects. This makes it impossible to mix files up, because unique data can be assigned to each record, and this does not get lost even if the original files are deleted from the file system. This function can be switched off via TypoScript (see Chapter 4.8).
Figure 3.45 t3-book.bmp was integrated three times in different content elements
106
3.8 Front-E End Editing
3.8 Front-End Editing In front-end editing, pages and contents are changed directly in the web site itself ("edit while you surf").
Softlink 615520
For many users who, due to their jobs, only work occasionally on the system, this is certainly the simplest, quickest, most intuitive, and convenient method. The front-end editing mode is also highly suitable for specialized work steps, such as final text corrections. The administrator even has the possibility of restricting access of individual users and groups exclusively to front-end editing. After logging in, the user is then taken directly to the front-end. If the editor is logged in to the back end, however, he or she is able to call pages in the front-end editing mode, via the context-sensitive menu or an appropriate button. As a rule his or her pages are displayed with small pencil icons [1] on all the content elements and processing bars [2]. Normal visitors do not get to see anything of this, of course.
Figure 3.46 Front-end editing using the editing icons [1] and bar [2]
107
3 TYPO3 for Editors
With the pencil icon, individual contents can be called in editing mode and are opened in a separate window. The editing bar also allows actions such as moving, hiding, and deleting the content, or new pages and content elements can be created. A prerequisite for front-end editing is to have the correct configuration of permissions from the administrator. He or she needs to have activated both the template and the Admin Panel for the user or user group. With the help of the Admin Panel, the user can make settings in the Editing area, show or hide editing icons in the front end, or have a corresponding form field displayed.
Figure 3.47 Admin Panel in the footer of the front end
If front-end editing is enabled for the user, the pages are newly created and shown with editing icons and bars. Caching is not used in this. Although this slows down the delivery of pages slightly for the editor, there are no effects for the normal site user. The front-end editing mode can be used as long as the user is logged in to the back end. If the session has been ended (or the editor logged out), the editing icons will no longer be shown.
3.9 The Rich Text Editor
108
Softlink 888606
For the Text and Text w/image content elements, the editor has the Rich Text Editor (RTE) available. Depending on the configuration, the editor can edit text blocks in WYSIWYG mode ("what you see is what you get") and, for example, insert images by drag n drop or set links. When this is done, though, content and format details are no longer separated, since HTML tags are saved directly in the text. For this reason it is important that access to the RTE, and to the range of its functions, is specified very carefully. If an application is to adhere to rules of accessibility as defined by the W3C guidelines, with cascading stylesheets, for example, the RTE may not use any font tags, of course. The configuration is described in Chapter 4.8.4.
Softlink 788773
The RTE is implemented in TYPO3 using ActiveX, and will therefore only
3.9 The Rich Text Editor
work with the Internet Explorer on Microsoft platforms. Alternatively, you can use htmlArea, another Open Source project. The documentation can be found online here. If the editor is authorized to use the RTE, he or she can make personal settings (module: User | Setup or do this in the respective editing mode with the checkbox at the foot of the Details View). If the RTE is activated, an editing bar with various icons is displayed in the Text form field.
Figure 3.48 Rich Text Editor with all optionally available menu items
With the icon to the right of the text field, the RTE is opened in full picture mode. Changes to the original code can be examined with the Source code checkbox. For individual content elements the RTE can also be switched off with the corresponding checkboxes in the text entry field. The functionality of most editing options is self-explanatory, and is shown separately with the rollover icon. For the sake of completeness, these are summarized in the following list. More complex functions are introduced separately afterwards.
Function
Shortcut
Description
Cut text
Ctrl + X
Text is cut out and stored in the buffer (also available via a context menu).
Copy text
Ctrl + C
The highlighted text is copied to the buffer (also available via a context menu).
Paste text
Ctrl + V
The text stored in the buffer is inserted at the position of the cursor (aso via context menu).
Paragraph type
A defined paragraph format can be selected for the highlighted text.
Character type
Classes are available for marking text passages, predefined by the administrator.
Table 3.2 Overview of RTE functions
109
3 TYPO3 for Editors
Function
110
Shortcut Description
Font Style
The highlighted text is shown in the selected standard font type. The display on the client side depends on whether that font type is installed there.
Font size
The highlighted text passage is given a font size from 1-7 in accordance with the HTML markup.
Text color
Depending on the configuration, there is either a color-picker or you have predefined colors.
Bold
Ctrl + B
The highlighted text is marked in bold (also via context menu).
Italic
Ctrl + I
The highlighted text is shown in italics (also via context menu).
Underlined
Ctrl + U
The highlighted text is underlined (also via context menu).
Align left
The block of text in which the cursor is placed is aligned to the left.
Centered
The block of text in which the cursor is placed is centered.
Align right
The block of text in which the cursor is placed is aligned to the right.
Numbering
Highlighted paragraphs are numbered sequentially.
Numbering signs
Highlighted paragraphs are given numbers with icons.
Decrease indent
Indentation of highlighted paragraphs is reduced or removed.
Increase indent
Indents highlighted paragraphs one or more times.
Insert link
Highlighted text passages within the text flow can be given links to other pages in the application.
Insert table
An assistant is available for inserting a simply structured table.
Background color
Background color is defined with a color picker or with predefined colors, depending on how the RTE is configured.
3.9 The Rich Text Editor
Function Shortcut Description Insert image
Although TYPO3 primarily has a corresponding content element for inserting text with images, images can also be inserted in the text flow directly through the RTE.
Insert icon
TYPO3 provides a range of icons that can be inserted in the text flow. You can add new icons to the selection.
Insert line
Inserts a dividing line between paragraphs.
Insert user elements
If special formatting details or functionalities have been defined by the administrator, they will be included in the corresponding menu.
Insert Link If a passage is marked in the text flow and Insert Link is called in the editing bar, the Element Browser wizard opens with special editing options. As usual, you can "browse" through the page or file tree to define a link to pages, contents, or files in the file system. Under Target you can specify manually or in the selection menu whether the link should open in its own window (_self), in the top frame (_top), or in a new window (_blank). When referring to External URLs, you should ensure that the full address is given, using the protocol (http://). For Email, the appropriate address should be given.
Softlink 648217
Figure 3.49 Inserting links with the Rich Text Editor
111
3 TYPO3 for Editors
Insert Picture Softlink 033547
Images can also be inserted directly into the text flow with the RTE. If the Insert Picture function is called from the editing bar, three modes will be available in the Element Browser: New Magic Image, New Plain Image, and Drag & drop. With the Magic Image mode, any graphic formats (within reason) can be selected in any size you want. The graphic is automatically converted to a web graphic format. Changes in size can be made later on to optimize formats and display quality. In the New Plain Image mode, only web graphic formats (JPG, GIF, and PNG) can be used up to a resolution of 640 X 480 pixels. This mode is intended for graphics that are already optimized for the web. In the Drag & Drop mode, images can be dragged directly from the Element Browser to a new position in the text. If an inserted image needs to be edited later, you should highlight it and then call the Insert Picture function again. Attributes such as width, height, border, margin left/right, margin top/bottom, or title can now be specified in the Current Image mode. But to insert images into pages, it is recommended that you use the Image and Text w/image content elements.
Figure 3.50 Inserting images in the Rich Text Editor with the Element Browser
Inserting a Table To create tables with the RTE, a simple wizard is run. Its functionality is quite rudimentary, allowing columns and rows to be specified, as well as cell padding and spacing, colors, and width of borders and the background color, or a background image for the whole table. However, to insert tables, it is better to use the corresponding content element instead of the RTE. 112
3.10 Working Efficiently with TYPO3
Figure 3.51 Assistant to create simple tables within the Rich Text Editor
3.10 Working Efficiently with TYPO3 Now that the back end, front-end editing, and standard content elements have been introduced, we will show you in this section how you can work practically with TYPO3, introducing the functions and working methods that will simplify and speed up your daily work, using a practical example.
3.10.1 Scenario Our example is based on a content management scenario in which three different target groups from a TYPO3 installation are to be supplied with information: 1.
Business to Consumer (B2C)
End customers on a freely accessible web site; this part of the page tree will contain information intended for a broad audience. Our example involves a company with products, which are introduced on a separate page, as well as a news area on the start page, events, a list of dealers and standard contents such as Contact, Company logo, and Sitemap, summarized in the "Functions" area. 2.
Business to Business (B2B)
Partners and suppliers on a password-protected web site; this page contains extensive product information and sales-related materials for dealers. 3.
Business to Employee (B2E)
Employees in a protected intranet; this information forum for internal use contains organizational information for employees. 113
3 TYPO3 for Editors
Although such a scenario is ideal for using the same content again in different locations, it is seldom implemented in this way in practice. For security reasons, intranet and internet web servers are always separated, so that the situation described here is only feasible if all web sites are created on the Intranet server, but the supply of the B2C und B2B web sites takes place on another web server in the Internet. More information on so-called "staging situations" can be found in Chapter 2.6.
3.10.2 Creating Page Structures Softlink 189036
In the first stage we will create the three web sites in the system.
Figure 3.52 Page tree as a result
First a "Portal" page is created, and under this a "B2C Home" page. To create the subpages, we choose a quicker method. The Web | Functions menu contains a Wizard area, which is used to produce up to nine pages with a form. The wizard creates these pages as subpages, or after the currently selected page in the page tree. In our case, you first set up "B2C Home" without the wizard and then call this page in the Web | Functions module. There, select the wizard from the menu at the top right, and then the function Create multiple pages. The page titles are entered for the pages to be newly created; any fields not required are simply left open. The new pages are set up as the first subpages of the selected page, unless you specify, with the Place new pages after the existing subpages option, that they should be inserted after already existing subpages. With Hide new pages the pages are created as hidden pages, which should always be the case for web sites that are already publicly available. The Sort pages function allows you to order the pages of the same level according to page title, subtitles, time of modification, and time of creation, or to reverse the current order.
114
3.10 Working Efficiently with TYPO3
Figure 3.53 Wizard of the Web | Functions module to effectively create and sort pages
To create the B2B page tree, set the Recursive Copy option in the User | Setup module so that you copy at least one level when you save a page to the buffer. You now insert the copied page into "B2C-Home" by clicking again on the page icon of "B2C-Home" and adding it to the page tree with Paste into.
Figure 3.54 Copying and inserting a page
3.10.3 Serial Editing with the Buffer It is often necessary to edit several pages or pieces of content in the same work process; the Clipboard is used for this, which displays the contents of the buffer and offers a number of editing options.
Softlink 965454
115
3 TYPO3 for Editors
It is activated in the List module with the Show clipboard checkbox at the foot of the Details View. If it is not already activated, you should also select the Extended view at the foot of the Details View. While the Normal [1] buffer can only take in one record at a time, the Clipboards 1-3 [2] allow several pages or content elements to be included. If the clipboard is activated, an extra icon appears in the List View for copying the relevant record to the normal buffer. If one of the Clipboards 1-3 is activated, checkboxes appear after each element of the List View, making a multiple selection possible [3]. The information icon in the menu bar displays all the essential data for the record concerned.
Figure 3.55 Clipboard in action: clipboard No. 1 is active, containing two content elements
With the photo icon, thumbnails of copied images are shown in the clipboard, and with the copy icon next to it you can choose between the mode for copying (orange icon) or moving (gray icon) for all elements [4]. The position where the elements should be inserted is defined with the corresponding icon in the List View (Paste after; Paste into) [7]. But the 116
3.10 Working Efficiently with TYPO3
clipboard can also be used to open the records in it for editing, with the selection menu, or to delete them all permanently [5]. If there are several elements in the temporary buffer, they will all be displayed as edit forms, one after the other. If you only want to delete records from the temporary buffer, just click on the appropriate icon for each record, or on the button in the editing menu for the currently active clipboard [6].
Example In our example, the first copy of the B2C tree in "B2B-Home" is renamed and two new pages are added to it: "Downloads" (sorted by "Dealers") and a SysFolder, "FEUsers" (sorted by "Functions"), to which the icon for frontend users was added in the page header with the option Contains plugin. With the clipboard activated, now select all the subpages of "B2B Home" in the List View and choose the Edit marked option.
Figure 3.56 Selecting and editing options in the list view with activated clipboard
In the listing of forms in the title fields, you can now change the pages so that the following page tree is produced.
Figure 3.57 The page tree of B2B-Home after editing and adding two new pages
From the "Dealers" page, a "Wholesalers" page has now been created; in addition the shortcut has been moved from "Home" to the "B2B Home" (instead of B2C) page. The B2E tree is still to be created; we will do this using the options for batch processing in the List View. 117
3 TYPO3 for Editors
3.10.4 Editing Selected Fields Softlink 729118
The List View provides the best overview, and access as well, to records connected to a page, but it also has other functionalities, which might not be noticed at first. We recommend in general that you activate the Extended View and the Clipboard. For every data type, such as pages, the corresponding tables can be selected individually, to be viewed or edited, with the "+" icon in the area header [1].
Figure 3.58 In the List module, the corresponding Type fields are opened for editing via the Page table and the selection of two records
This results in the List View being extended by a selection menu where individual fields can be selected for display [2]. In this figure the fields Type and Start have been selected [3]. By clicking on the title of the fields, you can sort up or down through the records in the selection. In this way you can quickly sort the news items alphabetically or by date of issue, for 118
3.10 Working Efficiently with TYPO3
example. All displayed fields of a column can be opened for editing with the pencil icon [4]. In combination with one of the clipboards 1-3, and by marking individual records [5], you can restrict the selection of data to be edited. To open all the displayed fields of the columns and listed (or selected) records, click on the pencil icon located in the top area above the individual editing functions [6]. This makes it very easy to edit meta-information in the page tree for all pages already created in a level, such as abstracts, keywords, and description. The view of the fields set is also retained if you return with the "Menu" icon [1] for displaying all tables. In this mode they cannot be edited individually, however. A further hidden feature is the option to export as a CSV, which appears if you have selected a table for exclusive display in the List module. Through this it is possible to download the contents of previously selected fields from the table in question as a CSV file (Comma Separated Values).
Example To complete our page tree, we now copy the "B2B Home" tree and insert the copy after the original page. This new page is renamed "B2E Home". The additional functions are now made visible in the List View with the "+" icon in the title line. Select Type, Pagetitle, and Shortcut to page. If you click on the pencil next to the corresponding column title, all the elements of this column will be called for editing. Now rename the pages, change the page types, and correct the shortcut of the "Home" page so that the following page tree is produced.
Figure 3.59 List in the Extended mode after editing
3.10.5 Shortcuts When you have been working for a while with TYPO3, you will realize that 119
3 TYPO3 for Editors
you have to edit certain pages—for example those for creating news— particularly frequently. Various shortcuts are available so that you can access these pages immediately after logging in.
User | Task Center: Recent Pages If the desired page is one that you have recently edited, it can be opened after login in the User overview | Recent pages of your customized task module.
User | Task Center: Edit Records The administrator can add pages which need frequent editing to the list, and make this available in the User | Task center module.
Shortcuts in the Footer Softlink 585979
Another possibility is to make your own shortcuts to the corresponding pages. This is already allowed for the administrator through the basic configuration of the user profile. For editors, the administrator should assign the permissions via TSConfig, so that the shortcut frame is included at the bottom of the page. See also the softlink shown here. options.shortcutFrame=1
This editor is now allowed to set links to the appropriate page via the shortcut icon [1] inside the Details View. These appear at the foot of the back end [2] and can be organized into groups [3]. To do this, activate the Edit checkbox [4], open the link, assign it to the group and provide it with a name. Using the title, the links can now be accessed directly through the selection menu [5]. Softlink 348238
Figure 3.60 Shortcut area in the footer of the backend
120
In addition the editor has an entry field [6] to call pages from the page tree directly via their page ID, if errors in display have been noticed in the front end, for example.
3.10 Working Efficiently with TYPO3
3.10.6 Help on the Content Level Word Processing with the Extension Text Tools If pages and amounts of data grow quickly within an application, TYPO3 can help in retaining an overview: specific records and content can be easily found with the search field at the foot of the detail frame. The search depth can be extended down to three levels in the page tree. Figure 3.61 Search option in the details frame
Even more effective ways of finding text and immediately editing or replacing it are provided by the Web | Func, Text tools (cc_textfunc) extension. It must first be installed, as described in Chapter 6, for it to be included as a Text tools function in the Web | Functions module. Now you can search through individual tables, as well as pages, page content, or templates, for example, down to four levels. Via search and replace, all found records are listed with their existing and modified contents, and you can also choose for which records modifications should be carried out.
Softlink 325093
121
3 TYPO3 for Editors
Figure 3.62 The Text tools extension allows a simple search and replace
Integrating Office Documents When generating content, the editor will frequently be involved with files based on Office documents. If parts of the document are to be saved as page content, then you need to decide if details of format are to be included, or if the set Customer Interface of the application should have priority. In theory format details can be taken over in the Rich Text Editor, depending on the influence the developer has in the transformation. If you want to discard them and use specified markings, it is a good idea to save the texts in an ASCII editor, or deactivate the Rich Text Editor before entering the text. Afterwards the text can be edited in the reactivated RTE. Softlink 138944
122
If not only text passages, however, but entire Office documents are to be included, then we recommend that you use the General Office Displayer
3.10 Working Efficiently with TYPO3
extension (in future to be renamed Document Suite). This extension provides a seamless integration of Word 2003, Excel 2003, and OpenOffice Writer documents. The first two formats must explicitly be saved as XML documents, however, but this has already been implemented in the default settings for OpenOffice for the SXW format. Two methods of integration are now available for the editor: In the first case the document is imported to the Rich Text Editor for further processing. The action is carried out via the context menu of the corresponding entry point in the page tree, the menu item Import Office, selecting the appropriate format. The content is saved as a Text content type, and can be edited later on in the Rich Text Editor if required.
Figure 3.63 Import Office via the context menu
The second method integrates the desired document by means of a plugin. In this process the content of the documents is stripped of its own format details and reproduced in the predefined layout of the content elements. But the text here can no longer be edited. Integration is performed with a content element of the Insert plugin type [1] (overleaf), with the extension General Office Displayer [2]. The Office file can now be included via the file system or directly from the local network [3]. The General Office Displayer, published by Robert Lemke, is being further developed as the Document Suite. The range of functions will grow considerably, and a number of handling options will also be added.
123
3 TYPO3 for Editors
Figure 3.64 Office Import using a plugin
3.10.7 Restore/Editing History Softlink 763322
In TYPO3, version 3.3, the (simple) versioning of contents was introduced. With its standard settings, the contents of all tables are stored for seven days (604,800 seconds), and a maximum of ten versions are saved.
Softlink 729572
The administrator can determine this process more precisely for individual tables via TCEMAIN_tables. The editor can return to the last saved version with one click. If you move the mouse over the restore or undo icon, the time when the last modification was made is shown.
Figure 3.65 Undo button to the right of the editing bar
With the Web | Pages | Quick Edit and Web | List module, the editor can have the editing progress for the record displayed, using the appropriate icon. Figure 3.66 Calling the editing progress in the list module
The history gives an overview of the changes to the record concerned. All changes are shown in green; old, or deleted values are shown in red. 124
3.10 Working Efficiently with TYPO3
Figure 3.67 Comparative display of the editing history
All changes up to the current item are revoked with the pencil icon, and with the information icon, an overview of all changes up to this item is displayed.
3.10.8 Multi-language Capability Working with different languages is possible in TYPO3 in a single tree. If the page templates are correspondingly prepared for display, then different language versions will be supplied. A translation option will appear for the editor in the Web | Page module, in the Languages View.
125
3 TYPO3 for Editors
Figure 3.68 Creating a new language version
After selecting the new language version to be included for the page in question, entries are required in the page title fields. Here you can Create page content or can Copy default content elements.
Figure 3.69 Displaying the contents, sorted by language
This last possibility has the advantage that the contents to be translated can be passed to editors with delimited access to linguistic versions. The request "Translate to language" is put in the front.
Figure 3.70 Comparative display of the editing history
126
3.10 Working Efficiently with TYPO3
If you open the whole data record of the page content, see that the values of the output data set are taken over [1] and to the comparison in the green selected areas [2] are preserved.
Figure 3.71 The whole data record
You can also start this translation workflow from the Web | List module 127
3 TYPO3 for Editors
directly. Moreover the check box Localization view can be activated. For missing translations of content elements the provision for providing the respective linguistic version is built in.
Figure 3.72 Missing and alternative translations
The module Info | Localization overview gives you the best overview about whole page branches and the current state of the translation workflows. New page titles of the alternative page language are added by selecting the checkboxes on the respective pages [1]. Page headers as well as contents can be edited. Further options such as Hide default translation of page [2] or Hide page if no translation for current language exists [3] are marked with different colors.
Figure 3.73 Overview of current state of translation workflows
128
4 TYPO3 for Administrators 4.1 Tasks and Targets of Administration All tasks that do not involve installation and programming work for implementation on the one hand, and content production on the other, are assigned to the field of administration. This includes technical maintenance of the system as well as setting up, monitoring, and controlling the results of the content-production process. Opportunities to train to become a content manager have so far been rare, and most people involved in this field have not sought it out actively, rather it found them. And yet this is a business-critical task, because it is not only the image of the company which is maintained here, but also the company itself that is being managed. 1 Seen in this light, "Content Management [...] is a part of both internal company information management and of knowledge management, and combines institutional aspects, company processes and technologies." http://www.nzz.ch/2003/05/23/em/page-article8TPZ8.html. And yet the technology is only the vehicle here: "while the technology simplifies the creation, storage and dissemination of content, it is company processes and workflows which fundamentally enable the successful and profitable use of the technology.” 2 1 People need to realize that the Web is no longer the thing about the thing; it is the
thing itself. The site represents your organization. Content management is, indeed, managing the business." Suzanna Phelps-Fredette: "Content Management—How Can We Stop the Train Wreck?", transcript of a lecture at the IQPC Web Site Content Management Conference, San Francisco 2000, http://www.metatorial.com/papers/aha.asp 2 Same source
4 TYPO3 for Administrators
The administrator plays the role of an architect who is permanently present, designing the information visible to the outside by organizing resources accordingly. Whether the work processes created for this have been designed by the administrator or by a consultant, either way the administrator must be highly familiar with the names and methods of the CMS used, in order to be able to influence the effect of the published information in terms of design, assessment, and optimization. Unfortunately it is often forgotten, when a CMS is introduced, that the main expenditure lies in continuous content production. "While technology is obviously needed to implement a CMS, this investment is the simplest part of a CMS strategy." 3 This experience has been widely documented and been shown to be true for nearly every CMS project. In addition to this, the introduction of a CMS always entails changes in new tasks for people and processes. Even where content was produced previously, widespread changes are probable: with its introduction, an improvement in existing processes should also be implemented, so that replanning and optimizing cannot be avoided. The administrator thus stands at the center of the introduction and of the running operation; he or she is responsible for the processes involved. The work that needs to be done directly on the CMS involves creating the prerequirements for editorial work processes and portraying these with the means available in the system. Actual content managers in the role of administrators watching over the system are frequently less technically-oriented employees, but they are usually responsible for the exterior image of the company, for marketing and PR or communication with customers (B2C), business partners (B2B), and employees (B2E). Most of their tasks in TYPO3 are appropriately supported by graphic wizards. These utilities cover a wide range of configuration options for the user interface and for assigning permissions to groups and users. Even where the use of system parameters is involved, namely with the TSConf system, a wizard is available to help those less technically well-versed to get started. Consequently the administrator is also responsible for ensuring value creation from the CMS processes. The system can help here, both as a production environment and as an analysis tool. In this respect TYPO3 offers several internal information sources for statistical evaluations.
3 Geoff Choo: "CMS strategy: Don't put the cart before the horse", TechRepublic Ins,
11 December 2001, ZDNet Australia: http://www.zdnet.com.au/insight/toolkit/ weboperations/cms/0,39023923,20262306,00.htm
130
4.2 Planning and Implementing the Content Management Environment
Apart from the predefined output options, there is also a powerful database interface where you can define specific queries yourself, which can be saved for later use. This chapter introduces you to the basic problems faced, from the perspectives described, when preparing a content management environment, and illustrates the system of assigning permissions, various configuration options for the back end, as well as introducing tools for control and evaluation.
4.2 Planning and Implementing the Content Management Environment It is a complex task to systematically define targets in new or existing processes using a content management application. This involves defining sources, frequency, and formats of contents, and planning and implementing the work steps associated with this to fulfil the editorial aims of the project. One widespread method for analyzing, developing, and constructing such work processes and implementing them in a content management environment is the Business Process Redesign (BPR), which in combination with a Rapid Application Development (RAD), produces efficient project workflows and successful IT-supported business processes. We would like to briefly explain both these approaches below, providing a basis from which you can get to know these procedures better. For our purposes it is sufficient to understand that every business process can be analytically dissected in the context of the BPR into a chain of elements. This analysis makes apparent the course of a specific task, with all its conditions, transformations, products, and decisions. This allows optimization potentials to be identified, which can frequently be sensibly supported by the use or modification of CMS technology. 4 Deciding on a content management system is often the result of such a process analysis, which can serve here as a simple example of a fundamental optimization of the content production process: without CMS, the creation and maintenance of websites remains the preserve of experts with technical knowledge. The path that leads from the creation of information in the company down to communication with customers, employees, or business partners, has become considerably more effective and quicker through the use of CMS. 4 An extensive theoretical representation with practical examples can be found in: Wil
van der Aalst, Kess van Hee: "Workflow Management: Models, Methods and Systems", The MIT Press, Cambridge Massachusetts, 2002.
131
4 TYPO3 for Administrators
This is because the employees who have the necessary content knowledge available are themselves now in a position to publish this without any technical expertise. The business process for publishing information is simplified and accelerated. Softlink 253617
As a second example, a CMS could automatically replicate product data from a source that can be universally used, and display the annotations made by editors and then make the output available in websites, in the pre-printing stage, or also via Web services. Maintenance of core data would be optimized by the centralization and availability of enriched data in a kind of multipurpose information hub. A corresponding case example can be found via the softlink shown here. Business processes should in general be result-oriented, realistic, and user-friendly. Where possible, information creation and processing should be combined, parallel activities merged, control mechanisms implemented, and information collected at source. 5 These maxims can in many respects be adopted in a content management situation, for example by integrated companywide data storage in a single -source approach, by assigning user permissions intelligently and configuring the editing interface on a task-oriented basis, by transparent and simple procedures and continual performance reviews. With TYPO3, processes planned in this way can be supported and displayed concretely through the permission system, by the optimized configuration of the editing interface, and by predefined workflows and commands. In addition, specialized system extensions can be developed and included, which improve this process support even more. The methodical analysis and conception of the processes results in a description of the planned solution in a finely-detailed concept, which typically contains the following information:
•
The site structure divided into topics
•
The contents, sources, and formats (news, case studies, product datasheets, etc.
•
The users involved, summarized in roles
•
The work processes of these user roles in relation to the individual contents/formats along the information flow in the so-called content life cycle (see section 1.2.2)
5 M. Hammer: "Reengineering Work: Don't Automate, Obliterate", Harvard Business
Review, July-August 1990, S.104-112
132
4.3 Principles of Organizing Permissions in TYPO3
4.3 Principles of Organizing Permissions in TYPO3 While the organization of content flows into the site structure and can be portrayed there directly, distinguishing individual users and permissions through analysis cannot be handled so intuitively, and requires knowledge of how the permission system works. This involves the following three fundamental issues: Users and groups Global parameters can be assigned to these to control editing options. Pages Access permissions for the roles "owner", "group" and "all others" can be defined for each page. Controlling the editing interface The user interface can be configured on the page level or on the user r-/ group level. In practice, the structure of the actual content is crucial in determining how it will be shown later as a page structure in a tree. The permissions of the employees involved are related to this page structure as far as work processes are concerned. An analysis can be made, based on the type of tasks, of which functions are necessary for individual roles and which parts can be modified to simplify the user interface, and to lower the cost of training. The result can be formally displayed in a matrix diagram with users and permissions. In many cases it will be sufficient to convert the corresponding settings directly in TYPO3, and to make these visible there by showing all affiliations via the Tools | User Admin module. This is a sensible and time-saving procedure, especially in the context of the Rapid Application Development approach described below. This approach is based on the premise that it is crucial to the project's success to involve users with the relevant practical knowledge in the creation process. In software development, the method of Rapid Application Development (RAD) has been established for this purpose. This involves checking the conceptual approach of an IT project by regularly using prototypes of the system from an early stage, and in which users are intensely involved later on in testing and improving it. 6 6 James Martin: 'Rapid Application Development', Macmillan Publishing Co., Inc., Indianapolis, USA 1991; Wilhelm Hasselbring: 'Programming languages and systems for prototyping concurrent applications', ACM Comput. Surv. 32(1), 2000, p 43-79.
133
4 TYPO3 for Administrators
This approach ensures that planning and implementation remain closely linked, and that there will be no nasty shocks when putting theoretical ideas into practice in everyday situations. TYPO3 is ideal for creating prototypes early on, for example to test the distribution of tasks with users and the organization of permissions in practice. A further positive result is that the users already become familiar with the options and functional principles, preparing them for the real work to come. Because TYPO3 already enables you to introduce content and create page structures, even without a finished interface, you can start training immediately after installation and configuration. In this way, user orientation and the structure of content will become clear more quickly, and the insight gained can be used appropriately to design the interface, and for the production of applications.
4.3.1 Example Concept The practical examples of this chapter are based on the following scenario. If you want to follow the individual steps in examples, it is important to know what the basic task is, and it is essential that you carry out the settings on pages and conditions as described in the example below. Our example focuses on a situation in which the content management platform is to supply three websites. To the outside, the websites are distinguished by having three different domains, and have different, but related designs. Portal The portal has content that is produced, maintained, and archived only for these pages by the relevant editors. In addition, the portal automatically includes content from the other websites that are present in the system. Websites There is also a series of websites in the system that are edited by other editors. The websites in our example are aimed at different target groups and are named "B2C" (Business to Customer), "B2B" (Business to Business), and "B2E" (Business to Employee) accordingly. Each editor only has access to his or her own area and to the content pool (see following page) and produces news within a predefined workflow.
134
4.4 Back-E End User Administration
Products in the websites As an organizational unit beneath the website level, we are assuming that there are individual product areas, all of which are maintained by separate users (product managers) for this level. Content pool/Media pool:
Content that editors of individual websites can use for themselves is stored in a non-public area; they can also save content there for general use and/or for further processing. The content can be inserted from here with the Insert record content element, or be copied, depending on whether it will be further processed or not. This means that at least one group is necessary for editing the portal and a group each for each of the websites. Assigning permissions in the system by means of workflows and actions enables the workflow of editors to be controlled for news in all sites and ensures that responsibilities for production and publication can be clearly assigned.
4.3.2 Implementation Steps To set up the system, the following steps are now necessary, in the sequence specified: 1. Setting up a basic page tree to which permissions can be assigned 2. Setting up the user groups to which users can be assigned 3. Setting up users who can be assigned to groups 4. Setting up workflows and commands in any order you wish Our example tree has the structure shown in Chapter 3.10. In the next step we will create the user groups as the basis for the permissions system.
4.4 Back-End User Administration Editors and authors work on content behind the scenes of the website. Their perspective is the so-called back end, which in many respects can be adjusted to the tasks of the individual participants—down to moving working options to the website itself.
135
4 TYPO3 for Administrators
4.4.1 Setting up User Groups Permissions that are assigned equally to different users are defined in groups. Groups with fewer permissions become subgroups. This results in a hierarchy, like the one below: Group A:
Filemount a/
Subgroup A.1:
Filemount a/1/
Group A.1 receives all the permissions of group A, as well as its own permissions. If the group is a member of several other groups and these permissions contradict each other, then the overall positive permissions are valid. If group A does not have the permission to edit a page, but group B has this permission, a user belonging to both groups can edit the page. The advantage of nesting groups is that all basic settings for users can be maintained in a small number of groups (just one in our case), so that specific settings in the corresponding record only need to be made for one group. The user groups should be set up in our example as follows: "Global" group Contains all the settings that should apply for all groups; in addition the script can be assigned read and write access for the entire file tree, and the actual access can be sufficiently set via the start points, which define the visible section. These start points are assigned by DBmounts. The "Global" group also contains the DBMount "Content pool". "Portal" group Maintains the portal page and is responsible for the release of news from all levels of the workflow. Groups for each website These contain only the assignment of the respective website branch ("B2C", "B2B", "B2E") of the file tree as well as the filemount for saving their own files. "Products" group This group accesses a part of the website trees and also has its own filemount. To create a user group, change to the List View and click on the name of your installation next to the globe at the top of the file tree, to reach the level named "Rootline" containing the system-wide records. You can add a new back-end user group with the link Create new record. 136
4.4 Back-E End User Administration
The form is divided into different areas: Access Data Enter the name of the group here. You can optionally configure the user group by specifying a domain in the Lock to domain field, so that the members can only log in to the system via a specific address, like www2.yourdomain.de/typo3. This is useful if different domains are pointing to your webserver or if you want to restrict access to TYPO3 to your intranet. Access Lists The Access Lists contain all options for setting the backend interface and access to every single input field and data area for groups. On selecting Include Access Lists, the form is reloaded. All entries that have just been made should therefore be saved. You will see a corresponding warning if you mark the selection field. The Access List contains a selection menu listing all the input fields, each entry can be selected by clicking on it. To select various fields, click entries while holding down the ctrl-key. The individual selection fields are as follows: Modules The menu items on the left-hand page of the back end display are referred to as modules. An editor should see at least the elements Web | Page, Web | List, File, and File | File list. It is useful to provide the possibility to individually adjust the back end, including the chance to change your own password, via User | Settings.
Figure 4.1: After selecting Include Access Lists, the Modules section will appear after the form has been reloaded.
137
4 TYPO3 for Administrators
Tables (listing) Select from this list the database tables that are to be shown to the user. The specified tables grow with the number of extensions installed, some of which also have tables available. After installation the permissions should therefore be checked, where appropriate, in this and in the next selection field.
Figure 4.2: Selecting the database tables that the user may see
Tables (modify) Choose the database tables that should be made available to the user from this table. Page types Here you can specify which page types may be set up by the members of this user group.
138
4.4 Back-E End User Administration
Figure 4.3: Selecting the page types that the user may set up
Allowed excludefields Using excludefields, you can define much more precisely than with the Tables settings exactly which input fields will be seen by a user group. If this field has been defined as an excludefield, and is not explicitly allowed in this list, it will remain invisible to the user who is a member of the edited group.
Figure 4.4: Selecting the fields that the user will be shown for editing
Explicitly allow/deny field values This option has been added in version 3.7.0 as a long-awaited answer to the problem of disabling content types for individual 139
4 TYPO3 for Administrators
groups. Previously those could only be hidden via TSConfigoptions. Selecting any of the content types disables them for the active group. As an absolute minimum “Script” and “HTML” should be selected for security reasons.
Figure 4.5: Disabling content types for individual groups
Limit to Languages The access of groups to language versions of the site can be limited here. Custom Module Options Back-end Module Extensions can add to this section with their own custom selection options. 140
4.4 Back-E End User Administration
DB Mounts Database (DB) Mounts allow an entry point in the page tree to be assigned to the user. If the user belongs to several different groups, and an entry point is defined multiple times, then it will also be displayed to the user multiple times. You should therefore ensure that there are no redundant settings here covering different groups. In our example you should set up the groups as
follows: Group
File
Global
Content pool
Table 4.1:
Portal
Portal
Products
Products
Example groups and associated filemounts
B2C
B2C home
B2B
B2B home
B2E
B2E home
Filemounts/file releases This refers to the directories in the file system assigned to user groups where users can store their data. These assignments are represented by means of so-called filemounts in the database. As records that are valid system-wide, the filemounts are saved in the Rootline, as are the users and groups. They can either be saved there or accessed in the group entry form on the right next to the selection field, via three further icons for "Edit", "Add", and "Show list". To be able to define a filemount, the administrator must have set up corresponding subdirectories in the fileadmin directory, via the File | List module. The actual names of directories in the file system and the names of the filemounts are independent of each other. In our example we will give the following names to the previously created directories, in the File releases dialog:
141
4 TYPO3 for Administrators
Table 4.2: Example groups, filemounts, and paths
Group
Filemount Label
Path
Global
Mediapool
mediapool/
Portal
All Files
files/
B2C
Files B2C
files/files_B2C/
B2B
Files B2B
files/files_B2B/
B2E
Files B2E
files/files_B2E
Product
Files P
files/files_p/
The name that is later shown to users is entered in the Label field. In the Path field the file path is entered relative to the fileadmin directory located in the web directory of your web server. Alternatively an absolute path can be specified. In both cases the pathname must be terminated with a slash. Hide in Lists This option serves to suppress the display of the group in the User | Tasks module as well as in the Web | Access module. In this way it can be avoided that users in the User | Tasks module send ToDos or e-mails to global groups that were only setup for administrative purposes. Subgroups With the Subgroups option, the corresponding group can be assigned to other groups as a subgroup whose permissions and settings are inherited by the current group. In our example we will assign the "Global" group as a subgroup to all groups, so that their settings will be acquired. TSConf The final input field of the dialog enables configuration with TypoScript. This area named TSConf is discussed in more depth in section 4.8. With Save and close the input is finished and the form is closed. If you have used the Include Access Lists option when entering data, the user group just edited is given a red icon in the List View. User groups in which no further settings have been made are marked in blue.
4.4.2 Setting up Users After the groups, it is now the turn for users to be set up, who can be 142
4.4 Back-E End User Administration
assigned to these groups. The dialog for setting up users is different from that for groups only in terms of assigning permissions, with the options for configuring file access in the file module. Users should always have their own user accounts, since apart from managing permissions, these can be used in many places in the system for working together and for administrative purposes.
•
User actions can be traced by a log function.
•
Users can communicate, via the User | Tasks module, using simple groupware functions (news, ToDos, notes).
•
Users can make their own settings in terms of the display and function of the back end, or have customized work environments assigned to them by the administrator.
In the next step we add a user to each group, so that we can later test the configuration. Back in the Rootline view of the system, select Create new record and Backend user. These are the individual sections of the form: Access Data The first form section contains the input fields for user name, password, group affiliation, and the option to bind a user to one domain. User names may only contain letters in lowercase, and spaces are not allowed. When you enter a password, it remains visible until it is saved for the first time, but is then stored as an MD5 hash in the database and is also transferred in this form to the back end when logging in to the web server. The consequence of this is that passwords that have been lost cannot be read out again, but must be newly assigned. User Groups Membership of user groups can be regulated via the selection field. The options on the right link the user dialog with the creation, editing, and display of user groups. The order in which the groups are specified is of significance in assigning permissions. New pages created by the user always belong to the first group in the list. This can be overwritten by TSConfig, just as the permissions of users, groups, and all others can be adjusted. An example of this can be found in section 4.8. The Lock to Domain option helps to ensure, in systems with several Internet domains, that users can only log in under their own domain.
143
4 TYPO3 for Administrators
Admin The next section of the form contains the Admin option, which grants the user unrestricted permissions in the system. Where possible, this configuration should only be available to one user in the system, or at least be used very sparingly. With a few exceptions, a user equipped with administrator permissions is in a position to irretrievably destroy all content and settings. User Data In the next form block, user data should be entered; the user can change this data via the User | Settings module, although he or she has no access to the entire user record. DB Mounts and Filemounts The system of filemounts and DB mounts has already been described in section 4.4.1. While markings for DB mounts and filemounts are removed in the Mount from Groups option, the user is stopped from inheriting the group settings in this respect. In addition the permissions available to the user in terms of files in his or her filemount can also be influenced. TSConf Possibilities of user configuration via TypoScript are described in section 4.8. With Save and close you exit the form, and the user is created. If you now leave the system and log in again as one of the newly created users, you can check your settings.
Example Set up users for the groups "Portal", "B2C", "B2B", "B2E" as follows:
Table 4.3: Example users
User
Group membership
Portal-editor
Portal
B2C editor 1
B2C
B2C editor 2
B2C
B2B Editor
B2B
B2E Editor
B2E
Setting up the previously mentioned product managers will be done later through the functionality of commands (see section 4.10). 144
4.5 Administration of Users with the Tools | User Admin Module
4.5 Administration of Users with the Tools | User Admin Module The Tools module contains an administration and analysis interface, in User Admin, which plays a significant role in the everyday work of the administrator. The tool helps to evaluate the current permissions situation by various criteria, and to make changes where necessary. The current settings for an individual user or group (if you have previously selected groups for display) are shown by clicking on the user or group name. Access permissions in the page tree assigned to this user that are insufficient are also shown here. The other settings correspond to the listing shown overleaf. The options for editing records function in the same way as those in the list module. A special feature is included in the SU option in the list of users. If you click on this icon for Switch User—similarly to the UNIX command of the same name—the current admin user switches to the user account selected. This is very useful for checking settings. However, there is no way back, apart from logging out and logging in again with your own login data. In this way the administrator can slip into any user role he wants, whatever the case, even if he or she doesn't know the current password of the user. The following options are available for displaying users and groups in the evaluation overview, which can be used alone or in combination:
145
4 TYPO3 for Administrators
Table 4.4 User and group display
Option
Meaning
Filemounts
Comparision of users by directories assigned
Webmounts
Comparision of users by entry pages in the page tree
Default upload path
Path for file uploads from page elements
Main user group
First user group membership
Member of groups
Other user groups whose members are users
Page types access
Page types that users may create
Select Tables
Database tables that the users may view
Modify Tables
Database tables that the users may edit
Non-exclude fields
Fields that the user may edit
Explicit Allow/Deny
Page content elements the user may not insert
Limit to Languages
Language versions which group members may or may not edit
Custom Module Options
Permission settings added by a back-end module extension
Modules
Back-end modules accessible to users
TSConfig
TSConfig settings for this user
TSConfig HL
TSConfig settings for this user in highlight mode
If you have followed the entries mentioned in the previous sections, the user administrator will appear as follows after the Main User Group and Member of Groups have been marked:
Figure 4.6: Display of all group membership (right) and of primary group membership (middle)
With this division of users, it is easy to maintain settings via mutual base groups ("Global"), and at the same time assign completely separate work areas and separate page trees. To check settings for individual user 146
4.6 Access Permissions on the Page Level
groups and fine-tune them, you can slip into the respective roles with SU and check the range of functions available to the user concerned. ATTENTION: to be able to edit pages, these must be released for access by the module described below.
4.6 Access Permissions on the Page Level The access module allows you to assign permissions to users, groups, and all others in a similar way to the Linux file system. These permissions are initially set automatically when a page is created, irrespective of who has set up the page. The creator of the page is automatically its owner, and the group that is listed first in the list of groups in which he or she is a member is taken over here as the group. This value, as well as automatically assigned permissions, can be overwritten by TSConf and set individually (see section 4.8). The Web | Access module always relates to the current position on the page tree when it is called, which is displayed in the top left corner. The User overview mode is active when it is run. This display mode shows the pages in the tree to a depth that can be configured. The Permissions mode available for selection shows the pages called with the permissions assigned to the owner, the group, and to all others. After a page is called, on clicking on the pencil icon, a form appears that enables owner and group permissions to be assigned for this page. Finally you can determine the level of child pages down to which the current settings should apply.
Example Change to the access module and click in the page tree on "Content pool". Clicking on the pencil icon there will take you to the editing form. Assign this page and the pages lying below it to the "Global" user group and assign permissions as shown in the following figure. If you save your entries, you are returned to the user overview. Now select the page again for editing and reset the permissions just for this top page, by restricting the levels setting to the current page. In this way you have effectively created a situation in which users of a group can edit all subpages, but not the parent page, without you as the administrator having to edit the configuration for individual pages. The final result should now look like this: 147
4 TYPO3 for Administrators
Figure 4.7: Showing access permissions in the Web | Access module
In order to make all parts of the page tree also available to each of the users, it is best to assign all corresponding permissions to the "Global" group, except for the respective "home" pages and any other pages that should not be changed. The actual access has already been restricted by the entry points into the page tree for the respective groups.
4.7 Front-End Editing for Backend Users One of the greatest advantages of TYPO3 has not even been mentioned yet: we refer to the possibility of allowing users to work directly on the website itself, entirely without, or as an alternative to, the back end. TYPO3 by default supports the possibility that users can edit contents in the preview after a page has been called, and add new pages. Using a simple extension, users configured in this way can also be moved directly to the website, that is, the so-called front end, and even work as "frontendonly" users. A third possibility consists of guiding the editor by hyperlink from another page of your website to the login page and providing this link with a parameter that will take him or her, after logging in, back to the website with editing options, instead of into the back end. The back end therefore remains accessible for the editor, if required. A corresponding link, which leads the user back to the start page of the website after authentication, looks like this: Backend login with redirection to the frontend
The Admin Panel is the switchboard in the front-end editing module, a compilation of the most important editing functions in a simple user interface. Of course the Admin Panel and the options it provides can also be customized individually. Administrators are automatically allowed to use front-end editing. To give a user this possibility as well, the following settings are necessary: 148
4.7 Front-E End Editing for Backend Users
1. The display of the Admin Panel in the front end of the website concerned must be set up. This is done by the following entry in the Setup field of your page template: config.admPanel = 1
2. To now grant individual users of groups access to the front-end editing options and the Admin Panel, the corresponding TypoScript configuration must be added to the TSConf field of the group or the user. To do this, the following is written directly in the TSConf field, or is done using the wizard: admPanel { enable.edit = 1 }
But the options can be made even more precisely. For editors in particular, the following configuration is conceivable, which automatically shows all editing options but keeps the Admin Panel itself hidden: admPanel { enable.edit = 1 module.edit.forceDisplayIcons = 1 module.edit.forceDisplayFieldIcons = 1 hide = 1 }
Each area of the Admin Panel can be individually accessed, so that for an editor, even the options for the cache can be granted, with: enable.cache = 1
The Admin Panel consists of the following areas, with the TypoScript keys next to them:
149
4 TYPO3 for Administrators
Table 4.5: Areas of the Admin panel with TypoScript keys
Name
TS key
Function
Preview
preview
Preview options
Cache
cache
Delete cache and cache options
Publish
publish
Options for static export as HTML pages
Edit
edit
Editing options
TypoScript
tsdebug
Various functions for template development, especially for error search
Info
info
Page information
Each part of the Admin Panel can be switched on separately, but you can also enable all parts, with enable.all = 1
instead of having to make each entry separately. Front-end editing is not just restricted to content elements and pages, and in principle, any database table at all can be configured for editing in the front end, through the corresponding entries in the page template. In this way, front-end editing can also be used if content such as product records, news entries, or other content assigned to pages needs to be edited. Below is a corresponding TypoScript example, which configures the editing of new entries from the tt_news database table. styles.content.editPanelPageRight = COA styles.content.editPanelPageRight { 10 = EDITPANEL 10 { newRecordFromTable = tt_news allow = toolbar,edit,move,hide,delete,new label = page:%s insert new news article edit.displayRecord = 1 line = 4 } }
If you insert this object, with the expression page.20 < styles.content.editPanelPageRight
into a page template, the editing options are shown, with which news can be set up on the current page. 150
4.8 TSconfig—Options and Interface Control
4.8 TSconfig—Options and Interface Control TypoScript is not only used for writing templates. With the same syntax— except for the missing options of Constants and Conditions—values can be defined similarly to the Windows Registry for system configuration. This can be done on two different levels: User TSConfig Per user and per group, TSConfig can be used to influence the display of the back end globally, or just through individual back end modules. Page TSConfig On the page level, TSConfig can be usedto configure individual areas of a website accordingly. A User TSConfig setting can be used to overwrite a configuration value of a page tree specifically to enable an administrator to have a different display, for example, than a user with a restricted task area. Entering Page TSConfig properties in the header of a page will always apply these properties to all subpages of this page as well. To give administrators a chance of working quickly with this system, a tool was developed, called TypoScript Property Lookup Wizard.
4.8.1 TSConfig Wizard: TypoScript Property Lookup If you click on the TS icon to the right of the input field in the page title or in the user or group form, an online help for all TSConfig options available here will open. This online reference is available in every TYPO3 installation, and the TSConfig wizard also allows you to take up values directly into the TSConfig input window. It is very simple to use: one click on the linked value causes the value to be taken over in the TSConfig window of the main input dialog, and the wizard is closed. If you click on "+" instead of the name, parameters are taken up in the entry window of the editor. With Wrap, brackets are placed around the parameter. Indent and Outdent are used to indent lines, in order to increase clarity.
151
4 TYPO3 for Administrators
4.8.2 User TSConfig For each group or user, TypoScript offers a range of configurations using TSConfig. You cannot obtain an overview if you call the wizard in the form for editing users or groups. As with the object tree on the template level, we call this overview the User or Page TSConfig tree. The various sections in the User TSConfig tree refer to the following configuration options: admPanel Settings for the Admin Panel in the front end Options Global settings for the back end Setup Contains the branches Default and Override; the configuration options contained in the User | settings module can also be controlled here via TypoScript. Both branches then contain the same parameters, but differ in their effect. With Default you can, as the administrator, influence the default settings that the user finds in the module. If the user sets the option in this module to restore the default configuration, the system returns to the settings configured by Default. With the Override parameter, parameters can be preset for users in the User | settings module, which cannot be changed. This can be useful from the perspective of the administrator, to prevent the possibility of pages being deleted recursively, for example. Mod The Mod area refers to the modules of the Web area. A series of parameters are available here for configuring the submodules of the Web module. ATTENTION: the configuration options for the Info module are currently not functional!
Example First we indirectly configure several viewing options for all groups, through settings in the "Global" group. Because the layout uses only a middle and right column, the display of the left-hand and margin columns in the column view in the back end is pointless. With the following entry, the columns are selected for display: 152
4.8 TSconfig—Options and Interface Control mod { SHARED.colPos_list = 0,2 }
The columns are controlled as follows: Left=1, Normal=0, Right=2, Margin=3. In order to obtain a matching backend display for all users of this group, you can switch off the display of thumbnails in the back end, for example, and cause the user to be redirected to the User | Tasks module after logging in, instead of to the help page: setup.defaults { thumbnailsByDefault = 0 startInTaskCenter = 1 }
Settings for users can be viewed and compared in the Tools | User Administrator module with the TSConfig and TSConfig HL options. TSConfig calls up the same page view as the Page TSConfig browser of the Info module. TSConfig HL shows the values in the input syntax with colored highlighting.
4.8.3 Page TSConfig Further options on the page level can be added to User TSConfig. The following options can therefore also be assigned to users and groups in their TSConfig fields. Conversely the options of User TSConfig cannot be entered in the pages. On the page level, the following areas are available: TSFE Contains an option allowing a user session to be transferred. Mod Controls the menus of the back-end modules, which can be influenced here TCEMAIN Concerns options that can be set for each system table, such as those for number of entries and time limits for the editing history; it also allows permissions to be assigned for a page tree independently of the user and group settings for creating pages. TCEFORM Refers to settings in the back-end forms; all input fields in the back end can be influenced by this.
153
4 TYPO3 for Administrators
RTE The Rich Text Editor can also be adjusted via TSConfig. Because many options are not compatible with the design guidelines that apply for websites, this is normally restricted.
TCEMAIN Examples TCEMAIN allows permission settings for creating new pages to be configured for groups or for pages. The entry in the homepage of a tree, TCEMAIN.permissions.groupid = 4
specifies that new pages in this tree automatically belong not to the main user group, but to the "Global" group. The group is identified by its UID (in our example, "4") in the database. The UID is also displayed in the back end if you click on the information icon in the Extended List View or move the mouse over the icon in the List View. With the same entry in the "Global" group, to which all other groups belong, all pages are made available to all others for editing, as long as they have access to them; in this way they do not have to be released specifically by the users of the group (or by the administrator) for users of a different group. After new elements have been permanently assigned to a group, the permissions for this group can be set in terms of pages. The permissions.group key is used for this: TCEMAIN.permissions.group = show, editcontent
The available values are Show (show in the back end), Editcontent , Edit (edit page header), New (create new subpages),and Delete. When copying elements in the TYPO3 back end, automatic suffixes are added to the name. Thus "Page 1" becomes "Page 1 (copy)” after being copied and inserted. This feature can be switched off with: TCEMAIN.default.disablePrependAtCopy = 0
A complete list of the TCEMAIN options can be found via the softlink shown here. The TypoScript keys for influencing individual tables can be found via the softlink shown here.
TCEFORM Examples With TCEFORM, all input forms can be influenced in terms of the display and naming of options. The notation used is as follows: 154
4.8 TSconfig—Options and Interface Control TCEFORM.[tablename].[fieldname].[TSConf_key] = value.
The TSConf keys and the values are defined in the reference under the softlink shown here. First we exclude a number of content types from the selection of our "Global" user group, for security reasons: TCEFORM.tt_content.CType.removeItems = search, login, div, script, html
In particular the elements script and html should always be suppressed in every installation, because they represent a serious security risk in the hands of experienced attackers who have gained access to the back end. But they are still available in the wizard, which is automatically displayed if you select the Create new page content option. We will therefore suppress the display of this wizard with the following entry in the "Global" group: mod.web_layout.disableNewContentElementWizard = 1
In the default configuration (without extensions, which expand tt_content), the following elements can be selected, and are added with the expression in the "keys" line:
155
4 TYPO3 for Administrators
Table 4.6: Elements in entry forms
German
English
TS key
Überschrift
Header
header
Text
Text
text
text m/ bild
Text w/image
textpic
Bild
Image
image
Punktliste
Bullet list
bullets
Tabelle
Table
table
Dateilinks
Firelinks
uploads
Multimedia
Multimedia
multimedia
Formular
Form
mailform
Suchen
Search
search
Login
Login
login
Textbox
Textbox
splash
Menu/Sitemap
Menu / Sitemap
menu
Datensatz einfugen
Insert record
shortcut
Plugin einfugen
Insert plugin
list
Script
Script
script
Trenner
Divider
div
HTML
HTML
html
The names in each of the elements can also be adjusted, by being overwritten. To do this, you must know the table and field names as they are written in the database. The field names are taken from the database structure, which you can call via Module | Configuration. The $TCA array contains all the fields of the database table, in the tt_content subitem, in which page content can be stored. Headers can be overwritten with your own names in the following form: TCEFORM.[tablename].[fieldname].[position] = value
The following line of TypoScript thus renames the standard header in the header=type field from "Layout1" to "Middle/Header". TCEFORM.tt_content.header_ textbf{layout.altLabels.0} = Middle/Header
156
4.8 TSconfig—Options and Interface Control
Figure 4.8: Options from the header menu, with your own names
With the removeItems option, values can be completely excluded from the selection lists: TCEFORM.tt_content.menu_type.removeItems = 3,4,5
An integer is added to the value, defining its position in the selection menu. The above line therefore hides the entries in the third, fourth, and fifth positions of the "Menu/Sitemap" page content element.
4.8.4 Adjusting the Rich Text Editor The Rich Text Editor (RTE) is the WYSIWYG editor in the TYPO3 system, which provides users with various formatting options and several wizards, based on Microsoft Internet Explorer technology. In principle, all the options offered by Internet Explorer are implemented, even if most of these options in practice are not compatible with conventional design guidelines in terms of the layout. As a rule, the RTE range of functions is heavily restricted, and where required, can be adjusted to your own format specifications, which are fully configurable in the RTE. The Rich Text Editor essentially has the following configuration interfaces: 1. Configuration of the input fields for which the RTE should be made available; the RTE can be given a different configuration for each of the input fields. 2. Switching on or off the editing options available in the menu bar. 3. Configuration of the options for formatting paragraphs and characters. 4. Influencing the transformation function for entries in the RTE when saving and for output from the database.
Restrictive RTE Configuration Our first example is limited to a very plain variation, for the reasons described, but in our experience it is still the recommended configuration for most cases. 157
4 TYPO3 for Administrators
The RTE can be switched on or off for parts of the page tree via the corresponding Page TSConfig field. First we configure the RTE so that it is only available in the Text and Text w/image content elements, even if extensions are installed that use the RTE: RTE.default.disabled = 1 RTE.config.tt_content.bodytext.types { text.disabled = 0 textpic.disabled = 0 }
In the next step we specify that all existing options, headers, and other formatting should no longer be included in the text field itself, but that only the standard formatting (to make restoring easier for the editor) and a formatting for quotes should be available. Suppressing headers in RTE fields is especially useful, because this forces editors to define text with various sections into separate content elements, which helps to improve clarity in editing and also allows other options, such as section menus, to come into play. RTE.classes { highlight { name = Highlight value = font:bold; color:navy; } quote { name = quote value = font:italic 15px; margin-left:20px; } } RTE.default.classesCharacter = highlight, quote
Via User TSConfig you can only configure which menu options are visible for the respective user or group in whose TSConfig field the entry is made. The options configured here are available to all members of the "Global" group, which is consequently all users of the system, with the following entry in the TSConf field for the group: options.RTEkeyList = class, bold, italic, link
The editors can now see the the menu bar as shown in the following figure.
158
4.8 TSconfig—Options and Interface Control
Figure 4.9: Reduced menu bar with its own formatting
As you can see, the option to insert tables and images through the menu has also been suppressed. As an alternative there are special page content elements for this, which are easier to control in terms of a uniform appearance, and also preferable for reasons of clarity.
Extensive Configuration The Rich Text Editor has several options in the default display that are not yet visible, and have to be added. These included a user object with which you can add your own definitions. With the following entry—for example in the TSConf field of the system administrator—we can switch on all available elements of the RTE: options.RTEkeyList = cut, copy, paste, formatblock, class, fontstyle, fontsize, textcolor, bold, italic, underline, left, center, right, orderedlist, unorderedlist, outdent, indent, link, table, bgcolor, image, emoticon, line, user, chMode
Below is an example for a classes configuration. RTE.default { colors = color1, color2, noColor PROC.allowedClasses = left, right PROC.allowTagsOutside = IMG mainStyle_font = Verdana, sans-serif mainStyle_size = 12px mainStyle_color = #313031 mainStyleOverride_add.P = font-family : Verdana, sans-serif; font-size : 12px; mainStyleOverride_add.H1 = font-family : Verdana, sans-serif; font-size : 18px; mainStyleOverride_add.H2 = font-family : Verdana, sans-serif; font-size : 12px; inlineStyle.img = margin: 5px; hidePStyleItems = H3, H4, H5, H6, pre classesImage = middle, withoutmargin classesCharacter = red, middle, small, large, gray, left classesParagraph = left
The color selection can also be configured: RTE.colors { corporate { name = BT3-Rot value = #BB0000 } variant { name = Burgundy variation value = #6F0311 } } RTE.default.colors = corporate, variation
Figure 4.10: Your own color preferences in the RTE
To restrict the color selection to the colors you have defined yourself, the default palette can be switched off as follows: RTE.default.disableColorPicker=1
A user-defined object as an example with some useful characters that cannot be found on the keyboard: 160
Do not forget to enable the corresponding default element, if you have not enabled all elements in the menu bar: RTE.default.showButtons = user
161
4 TYPO3 for Administrators
The following figure shows the result:
Figure 4.11: Your own extensions via the user object of the RTE
The complete reference, with many further examples on configuring the RTE, can be found via the link shown here. The influence of transformation for developers can also be configured via TypoScript using the options of the PROC key, as described by this softlink.
Alternatives Restricting the RTE to the Internet Explorer from version 5 has caused many people to wonder about alternatives. Several different efforts have been made simultaneously to integrate htmlArea, itself another Open Source project into TYPO3. After one implementation has clearly taken the lead others have become obsolete and are marked accordingly in the Extension Repository and will (hopefully) vanish from the Archives soon. The definitive htmlArea Extension is by Stanislas Rolland. A complete documentation can be found online here: http://typo3.org/documentation/document-library/rtehtmlarea/.
4.8.5 The Web | Info | Pages TSConfig Module Now that your entries in the title forms of individual pages are hidden, it is not so easy to find out which values have been set at which points.
162
4.9 Setting up Simple Workflows
Figure 4.12: Valid TSConfig settings for a random page on the page tree
The Info provides the Pages TSconfig function for this purpose. Here the active configuration is displayed for the currently selected page. You can choose to have all TSConfig entries displayed, or just individual areas.
4.9 Setting up Simple Workflows In the view named "Rootline", which you are shown if you click on the name of your installation next to the globe at the top of the page tree, and select the List View, you can create records of all types. If the workflow extension is installed you can now add a new workflow record to the end of the List View. If this and any other dependent extensions are not yet installed, first change to the Extension Manager. You will find the necessary notes on installing extensions in Chapter 6.
4.9.1 Workflow Configuration Configuring a workflow requires an existing page tree and at least two different back-end user groups, with corresponding members. This 163
4 TYPO3 for Administrators
module, which is currently quite simple, has three different roles: the task manager, who can initiate ToDos and assign users, the author, who writes new content, and the editor, who corrects this content and publishes it. Publishing can be done here in different ways:
•
By default, new content and pages are invisible, and remain hidden until they are released by an editor.
•
New content and pages are created in a non-public part of the website, and after they are approved, are moved by the editor to a part of the website predefined in the workflow.
This makes it easy to put into practice the classical "dual verification" principle of editorial procedures. More complex workflows can be simulated by joining workflows together, but these options still leave a lot to be desired if TYPO3 is to assume a central role in a business process with the corresponding feedback loops. In this respect there is a project which is being put into practice involving the integration of TYPO3 with a WfMC Standard compatible workflow editor and workflow engine compatible with the WfMC standard. When this is introduced, all the options for displaying more sophisticated workflows will be redesigned.
4.9.2 Example: News Workflow The users of the "Portal" group should be able to assign users of the "B2C" group ToDos, by calling a predefined workflow in the User | Tasks module. To be able to create a workflow, the target page, the target user group, and the necessary extensions must be available. Requirements: for our example, create a "News" page in the "Content pool" and add two subpages to it. The page on which the news is to be saved for displaying in the portal and in the websites, we will call "Live"; and the others where they were created and edited until being published in the workflow, we will call "Draft". Now assign the following permissions to the newly created pages, using the Web | Access module:
164
"News":
only administrators
"Live":
only administrators
"Draft":
"Global" group, show page, edit page content
4.9 Setting up Simple Workflows
Figure 4.13: Access permissions for the pages for news production
You must now add the "Draft" page for the "Portal" and "B2C" group to the DBMounts, so that both groups can see and edit the page. If you want the "Portal" group to be able to edit the article after publishing, you must give this group access permissions for the pages and also set them up as DBMount for this group.
Figure 4.14: Creating a new workflow in the Rootline
After installing the necessary extensions, a new record of the workflow type can be added in the Rootline of the system (List View on the top level of the page tree (see the preceding figure). The workflow form consists of several sections: The first part of the form contains the option of disabling the workflow. The second part contains the field for entering the title as it will later be shown to users. The description entered here is later visible in the Details View of the workflow. The next form block now contains the basic settings for the workflow.
165
4 TYPO3 for Administrators
Figure 4.15: Workflow form with entries for the new workflow
With Table, the target format of the workflow is defined. In its original state, and with an installed news extension, the following formats are available here: News, News category, Page, Page content, Website users and groups, Domains, Alternative page languages, and Internal notes. The Draft Page field calls the TYPO3 Element Browser, where you can select the page where the news elements are to be edited. Select the "Draft" page. Groups specified in Groups allowed to assign workflow may start the workflow and assign it to the groups named in the Target groups for workflow dialog. This creates a new entry in the ToDo list of recipients. Review Users are the users who can check and release work. Individual users should be chosen here.
In the next section you should choose if the entry should be moved with publication by the Review User, or be set from hidden to online. If the workflow refers to pages, then further entry fields can be defined, by marking the Set permissions when finalizing option, for specifying the 166
4.10 Defined Procedures with Actions
owner of the entry—together with the group and permissions for owner, group, and all others. After this entry there is an option to set the "News" workflow in motion, in the User | Tasks module under Tasks. This appears to the target user as a new ToDo entry in his or her view of the User | Tasks module. The actual workflow is processed by the status being changed to and fro. In this process, each step is recorded in the task protocol and displayed to the users involved. The task can then be escalated by any of the users and registered for release/publication. The actual release can only be made by the authorized user. This has the consequence in our case that the news entry is no longer marked as hidden, and has been transferred to the "Live" page. After completion, the protocol only remains visible to the user who started the task. The workflow is described from the perspective of the editor, in detail, in Chapter 3.4
4.10 Defined Procedures with Actions Actions are less well known, and stand for a concept that is accordingly
little used, but which has been available in TYPO3 since version 3.3.0. This approach implements predefined procedures, and these can be extended with your own actions. The actions are shown to users in the User | Tasks module (see the following figure).
Figure 4.16: Display of commands in the User | Tasks module
This function came about mainly as a way of giving administrators a chance to create restricted back-end user access. For this purpose, further useful standard action types were created.
4.10.1 Action Types The following functions are predefined: Create Back end User Enables non-administrators to set up back-end users. To do this 167
4 TYPO3 for Administrators
a user must be set up that can be copied with its settings—the socalled template user. This is a very important function in situations where a large increase in back-end users is expected in a user group set up specially for this purpose; it can help the administrator to avoid not only errors, but also very monotonous work. SQL Query Provides a way of making predefined SQL queries available; to do this, a new action is first set up in the Rootline. Give this a name and assign it to one or more groups. The definition of the database query is then created in the Tools | DB Check module under Full Search, using the Advanced Query option. After you have set up a query, you can assign it with the Save option and by selecting the relevant action (Save to Action) from the selection menu. This action is now available to the members of the group specified. Remember that users must have access permissions for the table or page concerned.
Figure 4.17: The SQL Query action is an example that displays data of front-end users
168
4.10 Defined Procedures with Actions
Record List The option for selecting a list of records under a specific page for display and editing; the options appear here as in the Extended List View. This is very useful to enable users to have a direct path for editing records—products, news etc.—after logging in.
Figure 4.18: Example of an action of the Record List type
Edit Record Allows you to display a list of disparate records, which can then be called for editing. If required, a user who is only involved with a very small number of records, which rarely change, could in this way be put into a position of working effectively without the main Web module.
Figure 4.19: List of records to be edited, called by an action of the Edit Records type
169
4 TYPO3 for Administrators
4.10.2 Example: Action for Setting up Users With this type of predefined action, non-administrators can also set up users, an important function to get individual departments and teams in a large corporation, for example, involved in content production. 1. First the sys_action extension must be installed via the Extension Manager. 2. To be able to define an action for automatically setting up users, a user record must be available as a template. This so-called template user is copied by the action and given details such as user name, password, and entry point in the page tree. Set up a "product_template" user. Actions are set up in the List View of the Rootline (Web | Lists module/root, which administrators can also call directly from the User | Tasks module). With Create new record, the New record dialog is called. Here, select Action as the type.
Figure 4.20: Setting up the new action in the Rootline
In the input form, select the Create Backend User option and fill in the following fields (see the following figure): Title/description Enter a title and a description. Assign Action to groups Select groups that are later allowed to run the action via the Task Center. Select the "Portal" group. User prefix Here you can enter an expression, which is prefixed to the user name of all users set up with this action. In our case, enter "pm_" for "Product manager". These users are then grouped together in the list of back-end users and are easier to recognize. 170
4.10 Defined Procedures with Actions
Template user Choose the user from the Rootline that, due to its basic settings (including Allowed Exclude Fields), is to serve as a template and be copied. Select the previously created "product_template" user.
Figure 4.21: Action form with the entries for creating a project manager
Groups which may be assigned through the action In this action the user can select to which group to assign the new user; selection options can be set here. Choose the "Global" group. Create User Home Directory In the All Configuration field of the Install Tool, you can set the two values: $TYPO3_CONF_VARS["BE"]["userHomePath"] $TYPO3_CONF_VARS["BE"]["lockRootPath"]
The directory specified must be writeable, of course. The action is set up when it is saved. Users in the corresponding user groups can now find it in the User | Tasks module. You as an administra171
4 TYPO3 for Administrators
tor can also call the action there to look at the entry fields from the user view and to test the function.
Figure 4.22: Form for editing the user in the User | Tasks module
4.11 Front-End User Administration Front-end users ("FEUser") are visitors to the Internet page who obtain further permissions, by registering or being set up by the administrator, for example to call protected content or run functions that are not available to unregistered users. FEUsers can be combined into groups who are then assigned the said permissions on a page level, or for individual content. The front-end user system provides the basis for assigning access permissions, and if required, editing permissions as well for visitors to the website who have authenticated themselves correctly. TYPO3 provides a series of front-end plugins to make this editing possible. Some simple examples are a guestbook, an eCard application, or something similar. The list of available extensions can be obtained from the central server in the extension manager. In the back end, FEUsers and groups are set up in a page of the Sys_Folder type.
4.11.1 Setting up User Groups For the sake of clarity, users and user groups are set up in a separate record in the page tree. Set up a new page in the page tree for this 172
4.11 Front-e end User Administration
purpose. In the following dialog we select the SysFolder type and give the directory the name "FEUsers". By selecting the Website Users extension in the Contains extension menu, you can assign a suitable icon to the directory. Figure 4.23: Front-end users and groups
Now change to the page view, with Save and close. Via Add new record, you can add a new user group. For our example, enter the name "B2B" in the following input form for the group and confirm the input with Save and close. Repeat the process, create a new directory in the "B2E" tree and in this, a further "B2E" group. In the List View you will now see all groups and users.
4.11.2 Setting up Users In the next step we will add individual users to the user group. For individual tasks in our example we will now set up a "business_1" user and an "employee_1" user in the respective groups and directories. Complete as many fields as possible when doing this, in order to get to know the automatic validation for certain fields, and also so that you can later test the interaction of other applications—such as the DMAIL system—with these database contents.
4.11.3 Login Somewhere in your page tree you must now provide a way for front-end users to be authenticated. To do this, insert a content element of the Login type into a page. Because TYPO3 is client-capable, that is, it can manage several websites in a system, and since you may want to keep website users from different websites separate, the system must be told which record this login refers to. To do this, write the following expression into the constants of the template for the page in which the login is located: styles.content.loginform.pid = 1
"1" here stands for the UID of the SysFolder in which you previously set up users and groups. You can find out this UID by clicking in the List View on the Info icon. The UID for this record appears in the info window in the last line.
173
4 TYPO3 for Administrators Figure 4.24: Information in the extended lists view
Alternatively (and more quickly), the page UID is also displayed briefly if you move the mouse over the folder icon in the page tree. Figure 4.25: UID display per mouse-over
4.11.4 Assigning Pages and Content In order to assign content that you only want to make accessible to this group, call the page title of the desired page or the editing form for any content. In the final form section there is the Access option. Here you can choose from the various user groups that you have previously set up. The Hide at login option hides the content or the page automatically after the user has logged in, Show at every login shows the content if the user is logged in, irrespective of his or her individual user group. With the Include subpages option, access protection is extended across the entire page tree to which this page is attached, and the page icon is displayed with two small arrows.
Example The following steps must now be carried out in our example: 1. Insert login page elements into "B2B Home" and "B2E Home". 2. Assign both pages to the corresponding front-end user groups and enable the Include subpages option.
Figure 4.26: Assigning a record to a front-end user group
3. Add the following line to the Setup part of the existing "B2B Home" and "B2E Home" templates: 174
4.12 Statistics and Logs styles.content.loginform.pid = 1
"1" must be replaced here by the ID for the respective FEUsers directory in which the user groups are saved.
4.11.5 Prospects The front-end user system was recently expanded in many ways through extensions. The possibility was created here—an urgently needed improvement—of making multiple assignments of content and pages to different user groups at the same time. A corresponding extension of the TYPO3 core is also under development, as well as the ability to display groups in nested form in the selection. The front-end user system principally provides the basis for personalization and portal functions, and development is continuing with growing expectations in this direction. It is therefore advisable, depending on the functionality planned in the website, to check what possibilities are already available through the corresponding extensions.
4.12 Statistics and Logs TYPO3 has many different ways to display system parameters providing information on usage on all levels: the work of editors, visitor statistics, and browsers used, down to information on the data storage of TYPO3. While the significance of statistical data on website visitors ought to be sufficiently familiar as far as individual pages, intervals between visits, and system requirements are concerned, TYPO3-specific data will be explained in more depth below. As far as performance reviews of your website utilization are concerned, there are various systems that are suitable for evaluating this data. A good link collection from the Centre for Information Quality Management to renowned (English-language) sources can be found via the softlink shown here.
4.12.1 The Web Info Module This module contains several interesting evaluation options: Page tree overview In the Page tree overview, three display options are available: Basic settings, Cache and age, and Record overview. All essential parameters on the pages in the page tree can be read out here, and can also be directly edited. 175
4 TYPO3 for Administrators
Localization Overview The localization overview option is relatively new and provides an easy and quick option to see which pages have recently been changed in the "default"-language and to check if the alternative language versions have been translated accordingly. Log Shows the same information as the Tools | Log module, but only for the current part of the page tree in each case; to evaluate this, see the description of the module below. Pages TSConfig As already described in section 4.8, this shows the valid entries in the relevant TSConfig data fields for the current page. Access statistics For the sake of completeness we should mention here that TYPO3 has a rudimentary module for displaying page accesses in the Info module. Its completion and further development was halted by the arrival of an external statistics tool, AWStats. Use of this is definitely recommended, and until now is without rivals for evaluating server logfiles in TYPO3.
4.12.2 Integrating AWStats A satisfactory evaluation of website statistics is provided by the AWStats module from our author, Rene Fritz. AWStats is an extension that first needs to be installed on the system—as described in the chapter on the Extension Manager. Because the extension includes the AWStats software, written in Perl, Perl also needs to be installed on the server.
In the file localconf.php you must specify where TYPO3 should write its logfiles for evaluation by AWStats. The following section can be found for this in the Install Tool under All Configuration:
Figure 4.27: Specifying the path for logfiles for evaluation by AWStats
This can be any directory at all, but must be writeable for TYPO3. The 176
4.12 Statistics and Logs
logfiles generated by TYPO3 are written in the Apache format and can be evaluated by tools other than AWStats. The following TypoScript code must now be entered in the base template of the website, to activate the generation of the logfile: config.stat = 1 config.stat_apache =1 config.stat_apache_logfile = domain.txt
You can configure another logfile at any point in the page tree with config.stat_apache_logfile, to create separate statistics for specific areas. It usually makes sense to create a separate logfile for each individual website or domain within a TYPO3 installation. With the expression: config.stat_mysql = 0
saving log data to TYPO3's own statistics table can be switched off. The file domain.txt must now be set up in the specified location. If you have placed it in the fileadmin/ directory, as intended in the example, you can create a corresponding file in the File | List module with the command New. Finally you must run and configure the AWStats module in the back end. After clicking on Edit configuration you will see the .txt and .log files that were found at the location specified. Enter the domains for which these should apply in the corresponding field. If you have several entries, they are separated by a comma. After saving, you reach the statistics due by clicking on the logfile. This module does not update itself, i.e., you must always click on Update now to obtain an up-to-date view. After AWStats has been successfully installed and configured, it will show a clear picture of all important parameters analyzing traffic, such as page impressions and unique visitors, which can be sorted by domain. A glossary of various statistical values can be found on the AWStats web page via the software shown here.
4.12.3 Logfile Evaluation The Log provides a wide range of information on operations in the back end. With the Time, Limit, User, and Type of operation parameters, various types of evaluations can be called from the database. The most important information here is provided by the output of the times and names of logins, which can be complemented by the operations 177
4 TYPO3 for Administrators
performed by a user, if you select All in Type of operation. Apart from the name, time of day, IP addresses, and the ID of the record edited, you can also call up the editing history via the Hist link shown in blue.
Figure 4.28: The log function after it is called from the Web | Info module for a part of the page tree
4.12.4 Front-end Logs Two further extensions are available, which provide information on visitors and front-end users of the system: Carlos Chiari's Visitor Tracking System (extension key: de_phpot) records the path taken by visitors in the website and shows this either via the path or statistically. Login User Tracking (extension key: loginusertrack) by Kasper Skårhøj saves the data of front-end users as data from users authenticated by the FEUser system.
Both extensions are currently in the beta stage at the time of going to press. Current information can be found via the corresponding softlinks.
4.12.5 The DB Checking Module The database checking performs a consistency check, and can become an important tool for complex systems under a heavy load, warning of problems and helping to solve them.
178
4.12 Statistics and Logs
The module provides the following functions: Record Statistics This option analyzes all the entries in the database tables that are relevant for the administrator. Marked-Deleted pages: the first section shows basic data on the number of all unhidden pages, all hidden pages and deleted pages. This is useful because pages deleted in the TYPO3 back end are not deleted from the database; the deleted field in the pages table is merely set to the value "1". So if it was necessary in an emergency to restore a deleted page, this value can be reset to "0" via the phpMyAdmin database tool, to make the page visible again. Under Document Types the frequency of various page types is shown. The Tables area provides information on the number of existing entries, with the name of the table in the system in the middle column. Total Page Tree The Total Page Tree option is particularly interesting in very large installations for viewing the entire file tree, without having to expand (and collapse again) many partial areas. Database Relations This area performs an analysis of the database according to specific criteria.
•
Files with no references at all: The system searches through files
in the Uploads directory where all files that are loaded in the back end unspecifically to the server are stored. The files there are then checked to see if they are referenced from the database. If this is not the case, these files can and should be deleted, since they are no longer used and cannot be called by users in the back end, and they can also use up large amounts of hard disk space in big installations where users store images in this way on the server.
•
Files referenced from more than one record: Database entries that are copied may have multiple references to a file in the Uploads directory. Such multiple links are analyzed and shown here.
•
Missing Files: This option searches the database for links to files
in the Uploads directory which no longer exist.
•
Select Fields/Group Fields: This function searches the database for links in records to no longer existing records. Select and Group 179
4 TYPO3 for Administrators
refer to different ways of displaying assignments of this type in TYPO3. Select is used for assignments of a predefined database table by selection fields (e.g., groups in the user dialog), Group is used for assignments that can contain content from various database tables (e.g. Insert record). Full Search Searches can be made here in the database, without having to go through phpMyAdmin.
•
Raw Search in all fields: In simple mode, you can search through the entire database by entering an expression and sending it off. This is not recommended for very large databases or systems working under very heavy loads.
•
Advanced Search: Offers a series of interesting options. The
output of a search result is initially not restricted to the screen output, but can be changed with the following options: Select Records shows hits in a list where they can be immediately edited. Count Results lists only the hit frequency. Explain Query shows further parameters of the database query. CSV Export shows the result as a comma-separated list with values in double quotes and commas separating results, and shown in rows. This is particularly useful if you want to process results further in spreadsheet programs, statistics programs and the like. The result appears in an entry window beneath which is an option for downloading. XML Export shows the result in XML notation in an entry window,
also with an option for downloading. Make Query: After selecting the database table to be searched, table fields can be chosen in the selection field which are then added to the list of fields to be searched. The sections of the search can be specified beneath this. The table name is shown on the left, the operator in the middle, and the expression which is being sought on the right.
Possible operators are Contains, Starts with, Ends with and Equals. The checkbox to the right next to the input calls a selection of negative operators: Does not contain, Does not start with, Does not end with, Does not equal. Each column has the options Refresh, Remove, and Add. Each further line also has functions to change the sort order and to 180
4.13 TYPO3 and Caching
formulate conditions. With the arrow right for indenting, you have the possibility to define conditions with the "and/or" operators. Under the lines for defining queries there are three functions available for grouping the results. With Group by, results can be summarized according to groups arranged by fields, with Order by results can be displayed arranged by a field, with Descending the output is shown in descending order. With Limit, the number of results can be set. Find Filename This is a simple option to search by name through all the files in the filemount and in the TYPO3 source. Searches can be made using regular expressions; a short introduction on these, with links to further resources, can be found via the softlink shown here.
Figure 4.29: Result of the file search
4.13 TYPO3 and Caching As a CMS based on a database, TYPO3 generates HTML pages from many different sources. From HTML templates, via TypoScript from the database, down to page content from separate applications, pages are assembled when the page is called and transferred to the browser of the visitor. Because the functions of the PHP scripts and the necessary database queries put a heavy load on the webserver, TYPO3 saves pages that have been called and assembled for the first time in a buffer, the so181
4 TYPO3 for Administrators
called cache. This cache takes a considerable strain off the database and web server, especially for large websites with a high amount of traffic. Changes to the page cause the respective cache for this page to expire. Several functions are available to the administrator to delete this cache manually. On the one hand there are two global functions to delete the entire cache, as well as the cache files of the TYPO3 configuration menu at the end of the page tree. More options are provided by the Web | Page module at the end of the columns view. Here the cache of a page can be deleted manually, as well as a configurable number of child pages. The Cache and age view in the page tree overview of the Web | Info module serves as a control instrument. Here you can check not only the current caches of the pages, you can also modify how long they are valid by clicking on the pencil at the top of the Cache column.
Figure 4.30: Setting the page cache via the Web | Info module
4.14 Digital Asset Management 4.14.1 Tasks and Aims of DAM The Digital Asset Management System (DAM) is the response of the TYPO3 community to the need to have image material, documents, and other files (so-called assets), which are intended to enrich the text of the website, provided with metadata. In this context, a digital asset management system is a subsystem without any directly visible functions in the website; it serves to record, index, and manage files. In addition to this, however, it provides a simple interface for extensions that need to use this meta-infor182
4.14 Digital Asset Management
mation for functions in the back end or front end. Another important innovation is the removal of an often criticized weak point in TYPO3: how to handle files when they are referenced from content elements. TYPO3 copies files that are to be published to a separate part of the system file tree, to protect these from being accessed by the user. If a user now deletes a file from the system via the back end, the function of contents displaying these files remains unchanged, and is protected from errors of the user. In many cases it may be desirable, however, to have direct access, to swap a file that is displayed at many locations in the website, for example. This is prevented by the protection function. The DAM provides a way of configuring the handling of files individually, so that you can specify per file, group, or category whether the file should be copied to one of the temporary directories or if it should stay where it is and be included from there directly. A simple application example for the DAM could be a picture gallery showing pictures, independently of where they are stored, and on the basis of a feature of the metadata, such as belonging to a specific category created for this purpose, or based on a keyword or file type occurring. Another application could be the evaluation of the use of images from a pool of pay-per-view material, and which evaluates usage statistically and provides a corresponding billing interface in the back end.
4.14.2 Integration into TYPO3 The DAM is represented in the back end as a separate main module and is also integrated into the page tree. The DAM icon always calls the view of all categories and a list of file types. The Media | List submodule shows all files in a List View. In practice the Media | List and Media | File views should replace the File | File list standard module. Depending on the configuration, this is shown to the editor with all these views included, or is restricted to the DAM integration in the TYPO3 Element Browser. In this case, managing the image data is a task for administration.
183
4 TYPO3 for Administrators
Figure 4.31: The TYPO3 Element Browser with an installed DAM
The Media | List Module The List View allows you to work with and on metadata in files that are already in the DAM, and in its function matches the standard File | List module. Editors use it to change existing metadata, makes selections, and save it. A simplified indexing system enables the metadata of already recorded assets to be edited en masse.
184
4.14 Digital Asset Management
Figure 4.32: Symbolic file tree of the DAM with three physical sections: physical directory structure, categories, and media types
As can be seen in this figure, there are three hierarchy trees in the navigation frame. The top one is a reproduction of the files in the filemount, the middle one shows a hierarchical tree of content categories. The lowest tree is generated automatically from the indexing system. Media objects are listed here, categorized automatically by their file type. Clicking on the name of a tree section displays in the right-hand frame a list of media objects that have been indexed for this directory, category or mime type. The data of media objects can be edited in this list by clicking on the pencil next to the object concerned.
185
4 TYPO3 for Administrators
Figure 4.33: List view of the DAM
Apart from the List View, three other views are available with their own functions after selecting a directory, a category, or a media type:
•
Thumbnails/overview: Images—if available—are shown here as
small previews.
•
Selection: The current selection can be modified here. Individual
files can be excluded from the selection, for example. In addition to this, the selection can be saved and exchanged among editors.
•
Process: Already recorded files can be reprocessed here with modified or added metadata.
The Indexing Module The Indexing module serves as an import dialog to provide new files with metadata and add them to the system. The DAM module creates a media object in the database for each file, which is consequently provided with meta-information. During indexing, the module, depending on the file type, automatically reads various default information into the database (e.g. image dimensions, file size, etc.). The indexing routine is designed to be expandable by means of so-called services, and in future could read out meta-information from PDF or Office files, for example. The following working steps are required for indexing media data: 1. Upload the files to a subdirectory of fileadmin via the File | List module (or upload via FTP). 186
4.14 Digital Asset Management
2. Import via Media | Indexing: selecting the directory to be indexed from the fileadmin hierarchy tree. 3. Follow the instructions of the indexing wizard, as shown in the following figures.
Figure 4.34: Step 1 - Select the directory whose content is to be included in the DAM
187
4 TYPO3 for Administrators
Figure 4.35: Step 2 - select from the (expandable) list of options
Figure 4.36: Step 3 - Enter information for mass processing that you want to assign to all files to be proessed
188
4.14 Digital Asset Management
Figure 4.37: Step 4 - Summary of your entries; these can be saved here as presets for further indexing procedures
Figure 4.38: Step 5 - Display of processed files
189
4 TYPO3 for Administrators
DAM Categories The DAM module sets up a specific page as a directory in the page tree, where it stores its own records (media objects and DAM categories). Categories can be created, edited, and deleted here via the Web | List module. All the DAM media objects are also located on this page, although they can be edited more effectively via Media | List.
4.14.3 Prospects The DAM fills a gap in terms of handling not database-based, but rather file-based information and resources, and will become an important tool, with improved management and increased security, especially where very large amounts of data and critical information are involved. With the DAM, many innovations are introduced into TYPO3 that are not directly involved with its function. The introduction of so-called services, as well as new display possibilities in the back end, are two such examples. In terms of functions, the DAM provides the basis for extensions in the direction of document management functions; in particular linking it to the display and editing of OpenOffice documents could lead to many developments being initiated that will use TYPO3 increasingly for enterprise content management tasks. A further development approach that has moved closer due to the DAM is the introduction of a uniform handling of metadata for files (assets) and content in TYPO3. This is particularly necessary for the requirements of the Semantic Web.7
4.15 Administration: The Future Several developments that TYPO3 will provide in future for administration can already be predicted, in the sense described at the beginning (in addition to the existing range of functions). An important step that is in store is the arrival of a complete versioning system in TYPO3. Based on this, the existing workflow module will be extended. In the medium term, the large dimensions of the workflow project, aimed at integrating external workflow engines, are quite significant. In the long term, the existing user administration system and the assignment of permissions will be heavily influenced by the requirements needed for operating a company portal, insofar as corresponding key workers can be found among the developers, and support can be found from sponsors.
7 http://www.w3c.org/2001/sw/
190
4.14 Digital Asset Management
The perspective of administration therefore has much influence on the future of the TYPO3 core; it represents the revolution on the way from a WCMS towards a broader and more fundamentally usable enterprise content management system.
191
5 TypoScript 5.1 The Role of the Developer 5.1.1 The Production Process I think developers already know but are a little afraid to admit that writing software is a creative activity that requires a lot of interaction with the people who are going to use it-Richard Gabriel. 1 However much time and effort is put into the preparation of a TYPO3based communication platform, in the end it is the concrete steps of implementation that make the plan a reality. Only in the rarest cases does this process have only one possible solution. Designing practical user interfaces and functions always allows room for creativity, but also room for errors. The activity of programming is not only subject to the laws of the respective system, but must also create optimal starting points for the maintenance, extension, and correction of the code, through forward planning. Two weak points that can very frequently lead to applications failing are closely involved with the role of the developer: 1. If the application's goal is not clearly defined to all those involved in the project, task descriptions will become focused on technical aspects of the software. However sophisticated the solutions may be, the success of an application usually depends on simple questions: Was a communication target clearly worked out and afterwards consequently put into practice? Was the software 1
also tested by editors for user-friendliness and acceptance? Ultimately, every application lives from the content that editors can add quickly, and which they must manage. In other words: has the developer thought about the user? 2. Even the task of technical implementation is frequently underestimated. As the demands made on this implementation increase, it must be considered whether an implementation partner might be a more time-efficient and thus more cost-efficient solution, on the basis of their know-how for the application. In short: only someone who knows the conditions and possibilities of the system well can produce solutions that retain value in the longterm and, after a period spent maturing, can serve as the basis for further development steps. This is not to say that the "tools of the trade" for creating new TYPO3 applications cannot be learned by anyone—that is precisely the aim of this book, after all.
5.1.2 Requirements and Overview If you want to implement complex applications with TYPO3, a sound knowledge of TypoScript is a prerequisite. TYPO3 provides various standard outof-the-box templates with which even a beginner can conjure up a website in a short time. These templates can be easily integrated and their appearance (colors, spacing, and logos) can be changed via wizards. But if you want to carry out modifications or implement functionality in accordance with the project requirements, a knowledge of TypoScript is needed. The basic principles of TYPO3's internal configuration language, TypoScript, and how it functions, are what this chapter is about. Some knowledge of HTML and how the World Wide Web functions is also required, of course. Only if functionality that goes beyond the basic provisions of this system and the numerous freely available extensions is necessary, do you need a sound knowledge of PHP and the TYPO3 developer API. This subject is discussed in detail in Chapter 7. This section of the book covers the following: Section 5.2 introduces the concept of TypoScript. The template records and the possibility of cascading is discussed, syntax explained, and principles illustrated in the order of processing and the nesting of objects. TS-objects, functions, data types, and the wrap concept are treated in more depth in section 5.3. Numerous development tools and aids are introduced in section 5.4. 194
5.2 TypoScript—Basic Principles
In its basic installation, TYPO3 already includes a series of standard templates. Section 5.5 gives you an overview and describes the areas in which individual templates are used in practice. Sections 5.6 to 5.9 are dedicated to creating a base layout. Various template concepts are compared and implemented in an example scenario. Alternative content rendering concepts and template switching with type/typeNum also provide background information. The navigation concept in TYPO3 involves varied menu types, based on text, graphics, layers, an image map, or selection menus. Its configuration is explained in section 5.10, using a number of specific examples. Section 5.11 takes a closer look at important functions such as stdWrap, optionSplit, and the GIFBUILDER, which play central roles in TypoScript. Using stdWrap properties and conditions you can insert control structures into TypoScript. The GIFBUILDER allows a wide range of image manipulation. Sections 5.12 and 5.13 deal with the implementation of a site with frames and allow a glimpse of the future with the topics of XHTML, accessibility, and TemplaVoila.
5.2 TypoScript—Basic Principles 5.2.1 What is TypoScript? A content management system must be able to produce various different content in the desired form in each case, due to the separation of content and form. A frequently used procedure is to insert special tags () into an output template to control output. With its help, specific contents, functions, lists, or detailed views are integrated or transformed into the template displayed.
Softlink 387605
At this point TYPO3 goes a crucial step further with the introduction of TypoScript (TS), because in TypoScript you can create the output template yourself, allowing for far greater control of the output format and layout than would be possible with simple HTML templates. With the information defined in TypoScript, not only can dynamic content be inserted into a template, but it is also possible to influence the appearance of the output (front end) in its details. The base layout can be generated entirely with TypoScript, or be taken from an HTML file. For navigation you can use a menu based on texts, graphics, layers, Flash, or a simple selection menu. Menus can be generated dynamically and each 195
5 TypoScript
menu's appearance can be determined individually. You can create graphics from texts and images in run time or control the layout and the contents of the output, independent of time or users. Even the behavior of the back end for individual users and groups is controlled via TypoScript. As mentioned in Chapter 4, you can specify, for example, which editing functions are available to the editor in the Rich Text Editor. TypoScript takes over the role of mediator between information and functions that are implemented in the core of TYPO3 by means of PHP, or added through extensions. In this way, TypoScript can be seen as an intermediate layer for transmitting information to system functions. To avoid misunderstandings, we would like to make clear what TypoScript is not, before getting to work defining what it is. For the technically minded, section 5.2.3 has more in-depth information. TypoScript is neither a programming language nor a script language, so it cannot be compared with Java, PHP, or JavaScript. It is not possible to use loops (for, while,...), for example. TypoScript serves as an "information carrier". You don't have to learn any new, and above all, proprietary languages. TypoScript itself is not run at any time. If TypoScript is not a script language, then what is it? One description that you should keep in mind whenever you want to test TypoScript to the limits, is as follows: TypoScript has a syntax with which hierarchical information can be defined in a tree structure through simple ASCII text. In this way any information can be passed on by TypoScript as the interface to the system. But only the objects and properties queried by the system influence the behavior of the back end and front end. And only the objects and properties described in the documentation for the current version of TYPO3 are available. Users of Windows operating systems are perhaps familiar with the hierarchical structure of system information in the Registry, which arranges values logically as objects.
196
5.2 TypoScript—Basic Principles
Figure 5.1: Diagram of the hierarchy of objects and their values structured by the Registry editor
Similarly, individual objects configured with TypoScript are arranged in a tree structure. The TypoScript Object Browser (Web | Template module) template tool represents this hierarchy in a graphical user interface.
Figure 5.2: TypoScript Object Browser displays nested objects and values
197
5 TypoScript
5.2.2 TSref Softlink 342678
At this point we would briefly like to remind you of the TypoScript reference TSref; it is a kind of bible for those who work daily with TypoScript, because in it, you can find precise descriptions of all available objects, properties, and functions. You should always have the reference close to hand if you are working with TypoScript! The TSref is available online at TYPO3.org and can be downloaded in OpenOffice format or as a PDF. If you don't have the TSref yet, now is the time to download it!
5.2.3 Digression: TypoScript and PHP To acquire a better understanding of the technical background, the following section explains the relationship between TypoScript and PHP. Alternatively you can move on directly to section 5.2.4. Even if in theory you can create output using PHP in any form at all, as a rule TYPO3's own TypoScript Front-end Engine (TSFE) is used when a website is called up via the file index.php (tslib/index_ts.php). It evaluates the information in the individual template records in the page tree of the website. 2 The objects and values of the template records, structured by the TypoScript intermediate layer, are processed here by PHP.
•
The information is placed by the system, using the t3lib_TSparser (t3lib/class.t3lib_tsparser.php) class, into a multi-dimensional PHP array. This is available in certain applications and functions in TYPO3.
•
If information is passed on to the PHP array that is not utilized by functions of TYPO3 classes, it behaves like variables created in PHP that are not queried. They are ignored, but this does not lead to any output errors.
An example to clarify this: In the abstract TypoScript code below, information parsed by PHP is placed in a multi-dimensional array. myObject.property1 = value_x myObject.property2 = value_y myObject.property2.property3 = value_z
In PHP the array would be created directly, as follows: $TS['myObject.']['property1'] = 'value_x'; $TS['myObject.']['property2'] = 'value_y';
2 The detailed front-end rendering process is described in section 5.7 and 7.5.1.
An array can also be displayed with TYPO3's own debug() function, which creates the following output: Figure 5.3: Display of the abstract TS code with the TYPO3 debug() function
TYPO3 provides a tool for displaying and editing TypoScript, the TypoScript Object Browser. This displays the example code in the following way:
Figure 5.4: Display of the abstract TS code in the TypoScript Object Browser
Example: HRULER The interplay between TypoScript and PHP can be illustrated by the very simple HRULER content object (cObject) that draws a horizontal line. Let's take a look at the following TypoScript template:
The third line is of interest, where a TypoScript object of the HRULER type is defined, to which configuration parameters are added in the following lines. The TypoScript values of the lineThickness, lineColor, spaceLeft, and spaceRight properties are placed by PHP into an array. The PHP HRULER() (tslib/class.tslib_content.php) function is then available for processing. Here is the PHP function: 3 function HRULER ($conf) { $lineThickness = t3lib_div::intInRange($this-> stdWrap($conf['lineThickness'], $conf['lineThickness.']),1,50); $lineColor = $conf['lineColor'] ? $conf['lineColor'] : 'black'; $spaceBefore = intval($conf['spaceLeft']); $spaceAfter = intval($conf['spaceRight']); $content = ''; $content.='
This results in an output of a horizontal line with a width of 10 pixels and with the color #e6e6e6. It is indented on the left and right by 100 pixels.
3 To display a horizontal line, TYPO3 uses a table, since an
sufficiently controlled via CSS in older browsers.
200
tag could not be
5.2 TypoScript—Basic Principles
This example clearly illustrates the capabilities, but also the limits, of TypoScript. TypoScript offers developers a secure interface for configuring existing functionality, making errors in handling PHP impossible and guaranteeing correct HTML code in the output. At the same time, a look at the above function shows that the developer determines that when the HRULER object is used, a horizontal line will be drawn using a table construction. This property is not included in the parameters for this special object. This paradigm applies in principle to every TypoScript object: its parameterization can be explained from the parameters that utilize one or more PHP functions.
5.2.4 TypoScript Templates TypoScript templates determine how the TypoScript Front-end Engine will ultimately set up the output, that is, which contents will be read from the database, whether an HTML template will be used, where contents will be inserted, and so on. In addition, the transformation of database content for the front-end output is controlled by the TypoScript template. In general this means which font families, font sizes, colors, and spacings are used in the website output.
Softlink 917652
Figure 5.5: An overview of the front-end rendering process
TypoScript templates control the following areas when generating output: 201
5 TypoScript
•
Cache
•
Logging/statistics
•
HTML header details
•
Page types (e.g. print output)
•
Base layout
•
Content elements (appearance and function)
•
Creating links
•
Integration of extensions and PHP scripts
TYPO3 provides predefined templates for most areas, so that developers do not have to specify all definitions required for the output—such as creating links, for example—for every website. Before these concepts are explained, here are some small exercises using TypoScript, to help you familiarize yourself with the basics of TypoScript.
5.2.5 Hello World!—The First TypoScript Template In order that TYPO3 creates any output at all, a TypoScript template is necessary. If this is missing, the error message "No template found!" will be displayed when the page is called up in the front end.
Figure 5.6: A missing TypoScript template
TypoScript templates are set up as records in the page tree. There are two types of templates: root templates and extension templates. The difference is that root templates are marked as Rootlevel and form the basis for a website, whereas extension templates can be found anywhere in the page tree and extend or modify the root template. Template records can thus be cascaded via the page tree, which means that TypoScript can add templates together or overwrite them. There are two ways of creating a new template: by clicking on one of the 202
5.2 TypoScript—Basic Principles
page icons in the page tree you can create a record of the Template type via the context menu and the New item. It is immediately assigned to the selected page and can also be edited like other records. The second way is with the Template | Info/Modify module. Select the page on the page tree that you intend to be the root page of a website (e.g. "Home"). If no template is yet assigned to the page, this is indicated and you can create one in the CREATE NEW WEBSITE form area with the Create template for a new site button. Optionally, a Standard Template could immediately be integrated here via the selection menu, to be used for the website. But more on this later.
Figure 5.7: New TypoScript template with the Template | Info/Modify module
Assuming you have set up your first root template with Create template for a new site, TYPO3 will have created a template record with the title "NEW SITE". It already contains seven lines of TypoScript code in the Setup field. This TypoScript setup defines the output in the front end produced by a page with the text "HELLO WORLD!".
Figure 5.8: Template record displayed in the Template | Info/Modify module
It is possible to edit the entire record via the link in the footer or to open a selection of the most important fields with the assigned icons.
203
5 TypoScript
The Setup field contains the following details: # Default PAGE object: page = PAGE page.typeNum = 0 page.10 = TEXT page.10.value = HELLO WORLD!
If you only edit individual fields, the cache of the record will be deleted when you save, and the current details will be taken into account when rendering the page. If you edit the whole record, updating is achieved by the Clear all Cache button at the foot of the module area or in the front end via the Admin Panel. If details are not shown immediately when developing a site, this does not necessarily mean that there are input errors. In such cases you should clear the cache. If the whole template record is opened via the Click here to edit whole template record button, an overview is shown in form fields of all existing information so far. It is noticeable that through the action Create template for a new site, Rootlevel was set in the template, and it thus serves as a starting point for a website. In addition, details of Constants and Setup that may have been set until now in the page tree and in TypoScript templates, are ignored by checking the clear boxes. These three settings enable new websites to be defined from any point within a page tree.
Figure 5.9: Partial view of the template record
If the page is now called up in the front end, you will see the following output:
204
5.2 TypoScript—Basic Principles
Figure 5.10: Output in the frontend
Add one line to the TypoScript configuration as shown below, with the <strong> tags to highlight the text. # Default PAGE object: page = PAGE page.typeNum = 0 page.10 = TEXT page.10.value = HELLO WORLD! page.10.wrap = <strong>|
The front-end output now shows "HELLO WORLD!" in bold:
Figure 5.11: Front-end output after the modied configuration
The possibilities of TypoScript go far beyond what this small example has shown. But first, the function of the template record will be illustrated.
5.2.6 Cascading Templates In the following example a second template, "my content", will be created in addition to the "NEW SITE" template. This can be done, for example, through the Template | Info/Modify module with the Create an extension template option. In an extension template the Rootlevel, Clear Constants, and Clear Setup flags are not set by default. Such a template can be placed anywhere in the page tree. This makes it possible on the one hand to set TypoScript for specific page trees, since the template will automatically become active on the page and its subpages. On the other hand, templates can also be placed in SysFolders, to keep them there as libraries and to integrate them into other template records. In this way, templates can be 205
5 TypoScript
better structured, individual functionalities can remain modular as components, and code can be reused. In both cases a nesting of template records takes place. This procedure of nesting templates is also called cascading. Integrating the "my content" template into the "NEW SITE" main template is done via the Include basis template field in the template record. The entire "NEW SITE" template record must be open for editing. The "my content" template is selected and integrated with the Element Browser.
Figure 5.12: Integrating a basis template in ‘‘NEW SITE'
The hierarchy of the templates can be controlled in Template Analyzer. If you select the main template, its dependencies are shown in a tree-like structure. The order, from top to bottom, corresponds to the order in which individual templates are processed by the TypoScript front-end Engine.
Figure 5.13: Template Analyzer in the Web | Templates module
As an example, the temp.myContent object is defined in the "my content" template. temp.myContent = TEXT temp.myContent.value = A text output
Through integration,this object is now available in the "NEW SITE" template and can be used there. page.20 < temp.myContent
5.2.7 Template Records Softlink 917198
206
As illustrated in the previous section, a template record is absolutely essential for generating the front-end output. An individual template record can contain the following information:
5.2 TypoScript—Basic Principles
Template title In the Template title field the name of the template by which it is displayed in the overview of the back end is defined. You can choose any name you like. But since many different template records are frequently used, a name that makes the functions defined in this template record clear should be used. In the extended fields Deactivated, Start, and Stop, the template can generally be deactivated or used on a time-dependent basis, in the same way as other records within TYPO3. Website title The title of the overall website is specified in the Website title field. In the default configuration it is inserted in the header of the front-end output inside the HTML before the respective page title, and displayed in the title bar of the browser window: B2C: Products [Website title]: [Page title]
Constants In the Constants field you set values for constants that replace the corresponding constants in the Setup field. Constants represent values set once or globally, which should be easy to manage in the entire application (font size, fonts, background colors,...). They should not be confused with variables as they are known from programming languages. Constants are replaced in the order in which they are entered, and can overwrite each other. Setup This field contains the actual TypoScript setup code, which defines both the appearance and behavior of the application. Constants (changeable properties or global values) in the Setup field are substituted by the values of the Constant field. Resources This field can contain assets such as images, masks, Truetype fonts, stylesheets, HTML, and text documents. The field can be referenced with TypoScript through the resource data type. When copying a template, the assets of the Resources field are also copied and numbered sequentially. logo.gif becomes logo_01.gif, for example. It is therefore advisable to set references to resources with a wildcard (logo*.gif).
207
5 TypoScript
Clear and Rootlevel The subitems Clear Constants, Clear Setup and Rootlevel form a functional group that needs to be seen in the context of cascading templates. Rootlevel The Rootlevel defines the point inside a page structure that is to be the starting point (root) of a new application (website). The properties of each template are inherited by all subpages (child pages) in the page tree. If new templates are set in individual page areas, their properties are added together hierarchically with those of the overlying pages (parent pages). In this way values can be reset on lower levels overriding those of the parent templates. The root template serves as the starting point for all TypoScript configurations for an application until a template sets a new Rootlevel. A root template is marked with a blue arrow in its icon. Clear Constants and Clear Setup By means of these checkboxes, cascading of constants or the setup within the page tree can be stopped. A template defined in this way does not inherit any constants or setup properties from templates in the page tree lying above. Include static TYPO3 in its basic installation provides a series of standard templates (static templates). These include not only functional configuration packages for representing content elements, but also complete out-of-the box templates with border layouts, as examples for your own use. The various types of standard templates are introduced in section 5.5.
Figure 5.14: Selecting standard templates
If you have included several standard templates from the selection, you can determine the order in which they are processed by clicking on the 208
5.2 TypoScript—Basic Principles
double arrow icon. They are deleted with the garbage can icon. The Include static AFTER basedOn checkbox inverts the order in which basis templates (see below: Include basis template) and standard templates are processed by the TypoScript Engine. In the default setting, basis templates are processed after standard templates. This normally makes sense, because you can overwrite values in the standard templates with your own values. In the example shown, a basis template and the standard content (default) template are integrated by the root template. The TypoScript configurations that contain loaded extensions (default TypoScript from Extensions) behave like standard templates. The Template Analyzer shows a summary of the order in which the individual templates are processed from top to bottom and added together.
Figure 5.15: Template Analyzer shows the effect of the Include static AFTER basedOn option
Include static (from extensions) Extensions can also contain standard templates. They are integrated in the Include static (from extensions) form area. TypoScript configurations containing the extension from ext_typoscript_*.txt (default TypoScript from Extensions), however, are automatically loaded during installation. Examples of extensions that contain standard templates are Office Displayer and CSS Styled Content.
Figure 5.16: Integrating the standard template of the extension with a mouse click
209
5 TypoScript
Include basis template Basis templates represent personal libraries with which the developer can organize the TypoScript code on a modular basis. Basis templates allow TypoScript to be managed in a clearer way and allow code encapsulated according to functionality to be used effectively for further projects. They represent their own template records whose root flags and clear flags are not set. Basis templates can in turn include their own basis templates, in which case a cascading structure is created. They are given an icon with a green "plus" sign. In the example shown, a template with the name Basis Template was integrated with the root template.
Figure 5.17: Integrating a base template
Static template files from T3 Extensions For TypoScript code containing extensions, (Default TypoScript from extensions) the order of integration is also important. In combination with the Include static AFTER basedOn selection, the Static template files from T3 extensions selection field offers numerous possibilities for cascading templates. Default (Include before if Root-fflag is set) With this default setting the standard templates of the extensions are inserted before the root template. This is useful because you can then override values from the extension templates with the root template. The difference between this and the next configuration is that the extension templates are only integrated beforehand if Rootlevel is set. Always include before this template record If the choice has been made, the standard templates of the extensions are read in directly before the corresponding template. The interesting thing here is that the template from extensions can only be modified in this way. Never include before this template record This option prevents the standard templates of extensions from being read in directly before the corresponding template. This means that although the template of the extension is active, it cannot be modified by a separate TypoScript setup. 210
5.2 TypoScript—Basic Principles
In the following example, a basis template (basic -- st Green) was integrated into the root template (main template). This in turn merely integrates a standard template (template; GREEN). The News (tt_news) extension is also installed, which includes its own standard TypoScript code. The order in which it would be sensible for them to be read in is: first the standard templates, and then the template for the extensions, since it might overwrite values in the standard templates, then the basis template, to override values of the predecessors, and finally the root template. In the first case, the default setting Default (Include before if Root-flag is set) is left as it is, both for the root template and for the integrated basis template. The TypoScript of the tt_news extension is read in after basic— st Green and before main template.
Figure 5.18: Static template files from T3 extensions: example 1
If the setting Always include before this template record is enabled and the default setting is retained for the root template, the TypoScript code for the tt_news extension is read in twice—which does not make much sense.
Figure 5.19: Static template files from T3 extensions: example 2
In the last case, the Never include before this template record setting for the root template prevents TypoScript code from the extensions from being read in directly before main template. On the other hand the basis template forces data to be read in directly before basic—st GREEN. 211
5 TypoScript
Figure 5.20: Static template files from T3 extensions: example 3
Template on next level This selection field provides a simple way of integrating a template which should be valid for all following pages in the next levels. Because of this, not every following page on the next level needs to be assigned to its own template record. Layout changes for individual page areas can thus be implemented quickly. Description A description of the template and its functionality helps you or third parties to find their way more quickly into the project at a later point in time. Back-e end Editor Configuration Softlink 626488
The field provides a way of passing on predefined styles to the CSS editor. It is rarely used, and is currently not being maintained.
5.2.8 Constants and Setup The two most important fields of a template record are Setup and Constants. Setup contains the TypoScript setup, that is, the TypoScript that defines all the configurations controlling the appearance and behavior of the website. This is processed during the rendering process. The Constants field on the other hand passes on easy-to-handle values or global values, namely constants, to the setup field. This procedure provides you with an overview when modifying values for individual page areas. Used in the right way, you can, for example, change a color value used across several templates, from a central location, instead of having to search through all the templates used. The notation corresponds to the normal TypoScript syntax: in the setup field the constants are enclosed by {$ and }. In the following example, "Hello TYPOS!!" is displayed in the front end.
If no corresponding constants are defined in the Constants form field for the constants queried in the setup, then {$myText.Content} would be displayed in the front end. The object hierarchy of the TypoScript entries for the Setup and Constants fields can be represented clearly in the TypoScript Object Browser (Web | Template module). To do this, select the page in the page tree whose TypoScript setup you want to display, and select the mode with Browse: Constants or Setup.
Figure 5.21: Displaying constants in the Object Browser
Passing on content through constants for dynamic pages does not make much sense, of course. It is more interesting to use constants for values such as text formats, colors, image properties, etc., that is, for values that are repeatedly used in an application, and should be easy to modify.
5.2.9 Elements and Concepts The NEW SITE template created with the Template | Info/Modify module contains the following lines, which display an HTML page in the front end with the text "HELLO WORLD!": # Default PAGE object: page = PAGE page.typeNum = 0 page.10 = TEXT page.10.value = HELLO WORLD!
213
5 TypoScript
In abstract form, the details can be translated to: # Comment myObject = OBJECTTYPE myObject.PROPERTY = value_1 myObject.subObject = OBJECTTYPE myObject.subObject.PROPERTY = value_2
By means of introduction, the terms will be named using an example, and then will be defined more precisely. # Default PAGE object:
The first line represents a comment, and is therefore ignored by TYPO3. In the following line page is defined by the "=" operator as an object of the PAGE type. page = PAGE
The name page can in principle be freely chosen. But some names are reserved by convention for specific basis objects. While page is used for normal content pages, the name plugin is reserved for plugins (extensions). page.typeNum = 0
An object has properties, to which values can be assigned. typeNum is a property of the PAGE object type, which is assigned the value 0 here. The character sequence page.typeNum defines the path for the property. The following line defines page.10 as an object of the TEXT type. In TypoScript, numerical lists (arrays) are frequently used. In this case the numerical list is a property of the PAGE object type. For objects of the PAGE type, this list can in turn also take in objects. Here 10 is defined as an object of the TEXT type. page.10 is the object path to this object. page.10 = TEXT
Bear in mind that such lists do not always take in objects; this depends on which data type the list belongs to. Relevant information can be found in the TypoScript reference TSref and in the corresponding extensions. page.10.value = HELLO WORLD!
The value property of the page.10 object is assigned the value HELLO WORLD!. Here are the concepts once again, explained in detail:
214
5.2 TypoScript—Basic Principles
Object types TYPO3 provides a whole range of predefined object types for use in your own TypoScript template. Examples of these are PAGE, TEXT, and IMAGE. Most object types create front-end output; these are also named cObjects or Content Objects. Other object types are used for general configuration purposes. Objects page was defined as an object of the PAGE type. Because page is in the top level of the hierarchy, it is also referred to here as a top level object. These can have almost any name you want. Already reserved naming conventions, such as lib, config, constants, styles, or temp are documented in the TSref (see soft link).
Softlink 110843
The page object could also be named monday, but descriptive names help to increase the overall clarity. If you want to define a page with frames, the name frameset might be a good choice. Properties Object types, and therefore objects of the respective type have precisely defined properties, which are described in the TSref. Only these properties are taken into account by the objects. The following line has no effect whatsoever, because the PAGE object has no value property.
Softlink 839954
page.value = Hello World!
No error is created, however, because TypoScript does not run at any point. The properties of an object itself have a specific data type. page.typeNum for example is of the int type, which means that only whole numbers are valid as values. The types and their valid parameters can be found in the TSref. Operators The individual operators are introduced a little later. One of these, for example, is the assignment operator "=". Path and object path Objects and properties can be addressed with their paths. The path is assembled from the overlying objects and properties, separated by a dot. page.10 is the object path to the corresponding object; page.10.value is the path to the value property for this object.
215
5 TypoScript
5.2.10 The Syntax As a rule of thumb, the notation can be summarized as follows: [objectpath].[property] [operator] [value]
The following syntax rules apply for TypoScript setup:
•
Objects and properties are separated by a dot, which at the same time defines the hierarchical dependency.
•
TypoScript differentiates between upper and lower case.
•
Constants have the form {$name} and are replaced with a value before the TypoScript setup is processed.
•
For object names and properties, only the characters A-Z, a-z, 09, the minus character "-", and the underscore "_" are used.
•
The text from the beginning of the line to the operator forms the path to the object or the property. It may not contain spaces.
•
The order of processing for object properties is defined by the object itself; it is not defined by the order of the lines in the TypoScript setup.
•
Numerical lists (page.10, page.20) are processed in ascending order.
Constants The syntax rules for the setup also apply to constants, with the following restrictions:
•
Constants are not objects, and consequently have no properties; therefore no functions such as stdWrap or if are available. They are nevertheless organized hierarchically.
•
The =< reference operator is not available.
•
Multiple line values cannot be used in the same way as in the setup with ().
Values The following rules apply for a value:
216
•
It is not enclosed by quotation marks.
•
It begins after the operator and ends with a new line.
5.2 TypoScript—Basic Principles
•
Multiple line values can be used with the help of ().
•
Spaces before and after the value are removed when it is passed on.
Comments and Comment Blocks /, #, /*, */ Comments can be added to document TypoScript. If you are not too familiar with programming techniques, we can only recommend to you at this point that you include sufficient comments in your projects for you to be quickly able to find your way again in your code, even after a long interval. One-line comments are marked by / or #, and must precede the contents. # Default PAGE object: / a different comment
Multiple line comment blocks begin with /* and finish with */ at the beginning of the final comment line. The completion mark is important, because the following code will otherwise also be treated as a comment. /* a multiple line comment is inserted here. */
Operators {}
The { } operators help you to write TypoScript more clearly and compactly by enabling you to nest several properties together. The following example exactly matches the previous example setup. page = PAGE page { typeNum = 0 10 = TEXT 10 { value = HELLO WORLD! } }
This is introduced with a curly bracket, {. All other details after the operator in the same line are ignored during parsing. The first hierarchically subordinate property must follow in the next line. The indentation only 217
5 TypoScript
improves readability. The nesting of properties is concluded with the } operator. It must be the first character of a line, with the exception of empty spaces. ()
The round brackets () enclose values, which can continue over several lines. This is very useful if a text is to be taken over that is already in structured form, or if values are to be shown more clearly, for the sake of better legibility. The TypoScript example has been slightly changed below, to illustrate this use. The 10 object was defined as an HTML content object. The page.10.value property is passed on as HTML code, which was created in an HTML editor, for example. page { typeNum = 0 10 = HTML 10.value (
<span style="color:#FFFFFF">Small example:
<span style="color:#FFFFFF">Input of multiline values
) }
The front-end output appears as follows: Figure 5.22: The ( ) operators
=
The equals sign, =, stands for an assignment. An object is defined by assigning it to an object type. A value is assigned to a property. The entire string of a line after the operator is treated as a value. Empty spaces before and after it are removed. page.10.value = HELLO WORLD! # corresponds to page.10.value=HELLO WORLD!
218
5.2 TypoScript—Basic Principles < (Copy)
With the < operator, one path can be copied into another. Individual properties or whole objects can be copied. When this is done, both the properties and the values of an object are copied. Objects, properties, and values that already exist in the destination path are overwritten. Now two new objects are assigned to the "HELLO WORLD!" example. page.15 is defined as an HTML content object, and a "break" is set as the output value. The page.10 object is copied into page.20. Inside the curly brackets, the object path can also be accessed using the syntax 20 < .10. page = PAGE page { typeNum = 0 10 = TEXT 10.value = HELLO World 15 = HTML 15.value = 20 < page.10 # or alternatively: # 20 < .10 }
Because there is an identical TEXT object in page.20, the front-end output now creates the text twice: Figure 5.23:
Individual objects and their hierarchy can be illustrated and controlled graphically in the TypoScript Object Browser (Web | Template | TypoScript Object Browser | [Template name]).
Copying an object path with the < operator
219
5 TypoScript
Figure 5.24: TypoScript Object Browser: the properties of the 10 object were transferred to the 20 object
=< (Referencing)
In conjunction with the = operator, < does not copy the object path, but makes a reference to it. Referencing is only possible with objects, not with properties. Please note that apart from this one exception, only one operator is allowed in TypoScript. The following example illustrates the different ways in which copying and referencing work: # The objectXY object objectXY = TEXT objectXY { value = Hello TYPOS?? textStyle.color.default = red } page = PAGE page { typeNum = 0 # Object 10 references the object objectXY 10 = < objectXY 10.value = Hello TYPOS!! (reference) 15 = HTML 15.value = # the current objectXY object is copied 20 < objectXY 20.value = Hello TYPOS!! (copy) } # A property of the objectXY object is changed later objectXY.textStyle.color.default = blue
220
5.2 TypoScript—Basic Principles
In the front end, the text of the copy is shown in red and that of the reference, in blue (but in view of the black and white illustration below, you will just have to take our word for it...): Figure 5.25: A comparison of referencing and copying
The page.10 object points here with the =< operator to the previously defined objectXY object. Since this is a reference to the objectXY object, it is taken on by the page.10 object while the TypoScript setup is being processed. In this way it can be used many times and in different places in the object tree, and is always up-to-date, since changes to the referenced object are valid for all references. In the TypoScript Object Browser you can check to see how the TypoScript setup will be put together. The text "Hello TYPOS!! (reference)" will be shown in blue in the front-end output, since textStyle.color.default in the objectXY object was subsequently overwritten. It is also interesting that properties of the reference can be overwritten locally, in this case with page.10.value. A copy in the page.20 object path does not take on the change in the text color. The properties and values of objectXY were copied when the TypoScript code was read in, which was before the text color was set to blue. The overwritten text "Hello TYPOS!! (copy)" therefore appears in red.
Figure 5.26: TypoScript Object Browser: the 10 object points with a reference to objectXY
221
5 TypoScript >
The > operator deletes all objects and properties existing so far from the respective path. In the following example the page.20 object is deleted again. page = PAGE page { typeNum = 0 10 = TEXT 10.value = HELLO World 15 = HTML 15.value = 20 = TEXT 20.value = Hello TYPOS!! 20 > }
Only the first text is displayed: Figure 5.27: “Hello TYPOS!!” has been deleted
Conditions Softlink 270225
Conditions in TypoScript are enclosed by the [] characters, written on their
own line, and cannot be placed inside properties nested with { }. Conditions are defined that must be fulfilled for the following TS code to be valid. In this way it is possible, for example, to restrict instructions to specific browsers or user groups. If the conditions are identified as fulfilled during parsing, the parser continues interpreting the TypoScript code. Otherwise it will ignore it until the condition has been removed. Conditions are dealt with in more detail in section 5.11. Here we are just interested in the syntax. In the following example, the condition [browser = netscape] means that the page.10 object is only set if the calling browser identifies itself as Netscape. [END] (alternatively: [GLOBAL]) marks the end of the condition. page = PAGE page.typeNum = 0 [browser = netscape] page { 10 = TEXT 10.value = HELLO World 10.wrap = |
If several conditions are defined in one line, they are linked by OR, that is, as soon as a condition is valid, the following TypoScript code is also valid. AND links cannot be implemented yet with TypoScript conditions. In the following example different text is displayed by the page.20 object if the request is from Netscape or if the operating system is Linux. [browser = netscape] [system = linux] page.20.value = You're a Linux or Netscape user [END]
The [ELSE] condition is regarded as fulfilled if a condition set before this is not fulfilled. It must also be terminated with [END] or [GLOBAL]. page = PAGE page.typeNum = 0 [browser = netscape] page { 10 = TEXT 10.value = output for the Netscape browser } [ELSE] page { 20 = TEXT 20.value = output for all other browsers } [END] page { 30 = TEXT 30.value = output for all browsers 30.wrap = | }
The Firefox browser, for example, can be identified as a Netscape browser, and produces the following output:
It must be noted that conditions cannot be nested. So the following example would not work. 223
5 TypoScript [browser = netscape] page.20.value = You're a Netscape user [system = linux] page.20.value = You're a Linux and Netscape user [END] [END]
Includes TypoScript libraries can also be included as external text files. The instruction for this must be on a separate line, but unlike conditions, it can be set within nested properties. It is already processed and inserted before parsing begins. The following example shows the integration of an external file with the help of the instruction. page = PAGE page.typeNum = 0 page { 10 = TEXT 10.value = Output 1 10.wrap = | 30 = TEXT 30.value = Output 3 }
The external file include_1.txt, which was stored in the file system under fileadmin/typoscript/, contains these settings: 20 = TEXT 20.value = Output 2 (integrated via Includes) 20.wrap = |
This produces the following output in the front end:
Figure 5.29: TypoScript integrated via Includes
5.2.11 Order of processing To be able to utilize TypoScript, you must understand the order in which TypoScript is processed. 1. TypoScript constant instructions are read in from top to bottom, 224
5.2 TypoScript—Basic Principles
and conditions are taken into account. 2. Constants are substituted in the TypoScript setup in the same order in which they were set up. 3. TypoScript setup instructions are read in from top to bottom. 4. Conditions are evaluated as they are read in. 5. Copies of objects and properties using the < operator are made while parsing takes place. This means, of course, that only the configuration of an object available at the time of the copy is copied. If changes are made to the output object in the following lines, these are not applied to the copy already created. 6. The TypoScript code is processed and references are resolved. As you can see, the order of TypoScript instructions during parsing is relevant, since the reoccupation of properties in copies and output objects has no effect on the other object concerned in each case. On the other hand, the order during processing does not play any role.
•
Properties are not processed in the sequence in which they are created in the template. Rather, the object itself defines when it will evaluate a property.
•
Objects are processed in the order of the numerical lists in which they are defined.
The following examples will therefore create identical output; it is obvious that the first variation is by far the clearest. Example 1: page = PAGE page.typeNum = 0 page.10 = TEXT page.10.value = I am an page.15 = HTML page.15.value = page.20 = TEXT page.20.value = example text!
Example 2: page = PAGE page.typeNum = 0 page.143 = HTML page.143.value = page.377 = TEXT page.377.value = example text! page.23 = TEXT page.23.value = I am an
225
5 TypoScript Figure 5.30: Front-end output of examples
5.2.12 Nesting of Objects Another essential principle of TypoScript is its ability to nest objects. So far you have seen how objects create contents and display them in the sequence specified in a numerical list. The following TypoScript setup is such an example: page = PAGE page.typeNum = 0 page.10 = TEXT page.10.value = I am a page.10.wrap = | page.20 = TEXT page.20.value = small page.20.wrap = | page.30 = TEXT page.30.value = example text!
This produces the following output: I am a small example text!
The general assumption is that each object in turn gives up its content, so that the output gradually accumulates in the front end. This is only partially correct: objects always pass on content or data created to the object that has integrated them. In the above example, the HTML objects pass on their contents to the overlying PAGE object. Only when all the objects of page have been processed does this return the contents created, after which they are then displayed. This nesting can be continued downwards for as many layers as you like, since many object types possess properties that can take in objects. The following setup, for example, creates the same output as the above example: page = PAGE page.typeNum = 0 page.10 = COA page.10 { 10 = COA 10 {
226
5.2 TypoScript—Basic Principles 10 = COA 10 { 10 = TEXT 10.value = I am a 10.wrap = | } 20 = TEXT 20.value = small 20.wrap = | } 20 = TEXT 20.value = example text! }
The identical setup in a notation without brackets looks like this: page = PAGE page.typeNum = 0 page.10 = COA page.10.10 = COA page.10.10.10 = COA page.10.10.10.10 = TEXT page.10.10.10.10.value = I am a page.10.10.10.10.wrap = | page.10.10.20 = TEXT page.10.10.20.value = small page.10.10.20.wrap = | page.10.20 = TEXT page.10.20.value = example text!
To acquire an understanding of the TypoScript setup, you must know that the COA object type, like the PAGE object type, can take in objects in a numerical list. The procedure is as follows: with page.10 a COA object is called, which in turn, first as page.10.10, calls a COA object, and so on. Eventually a first (TEXT) content object is called up with page.10.10.10.10, which actually creates an output, namely "I am a ". All objects in COA page.10.10.10 have now been processed. The COA object has received the content generated from the embedded TEXT object, which it now passes onto the parent COA page.10.10. This processes its object list, calling the next TEXT object page.10.10.20. The content generated is appended to the content that the COA has received from the child COA, and after the object list has been processed, it is passed on to the calling COA page.10 object. The procedure is repeated until all objects have been processed, the PAGE object receives the contents, and they are displayed. 227
5 TypoScript
This nesting can be illustrated by adding the following to the setup: page.10.10.stdWrap.case = upper
Now this output is produced: I AM A SMALL example text!
The
COA object page.10.10 receives the instruction, with .stdWrap.case=upper, to convert its contents to upper case. The object itself does not create any content at all, but in a nested hierarchy, two TEXT objects are embedded whose contents are received by the COA, thus
converting the content to upper case. So tree hierarchies of objects can be created with TypoScript, where on the one hand the levels are processed in turn, but on the other, the order of processing is simultaneously dependent on the hierarchy. In this way you end up with a powerful configuration tool for the output in the front end.
5.3 TS Objects, Functions, and Data Types 5.3.1 Data Types Softlink 253434
The data types used by TYPO3 are very varied and to a large extent not comparable to the data types of programming languages. Although there are data types such as int, string, and boolean, there are also things like degree and pixels. Just like int, these are also integer values, with the difference that degree defines a number of degrees and pixels a number of pixels. As you can see, the data types help to further describe what sort of data can be expected from a property. Sometimes the functionality of a property only becomes clear through the data type. The complete list of data types can be found using the soft link here. One special feature lies in the fact that a number of data types are actually functions. So far we have shown you how TypoScript is used to set configuration parameters. Apart from the Conditions, this is a purely static procedure. But with the functions available, TypoScript acquires dynamic capabilities and can process and modify data.
228
5.3 TS Objects, Functions, and Data Types
Here is a very simple example: page.10 = HTML page.10.value = kasper page.10.value.case = upper value is in the HTML object type and of the stdWrap data type. This function knows the case property and can be configured with the upper
value to convert the output to upper case. TypoScript provides a number of similar functions, which will be described below in more detail. It is these functions in combination with object types in particular that transform TypoScript into a powerful tool. The data types are listed in the TSref in the reference tables of properties for individual objects. In the assignments, not only data types can be found, but also values such as ->select or ->filelink. In these cases, functions can usually be reached via properties of the same name, or predefined objects of the specified type are available (e.g. TLO config). In the following figure you can see how the if and stdWrap properties point to the corresponding functions.
Softlink 924038
Figure 5.31: The CASE object type integrates the stdWrap and if functions
If +calc was added to a data type value in the TSref, then calculations can be carried out with the value. The +-/* operators used in this have no priorities and are processed in the order in which they appear.
Softlink 034017
As can be seen in figure 5.31, the property is of the string/stdWrap data type. For pieced-together data types like this, you can specify a value (string) or use the specified function (stdWrap). You can also combine both.
Softlink 695668
5.3.2 The Wrap Concept A wrap is a very important concept in many TypoScript objects. It represents a string that is split into parts by the "|" (pipe) character. If the object has the wrap property, it is enclosed by the value of the wrap.
229
5 TypoScript
The TEXT object page.10 with the value Hello World is enclosed in the example by the <strong>| wrap: page.10 = TEXT page.10.value = HELLO WORLD! page.10.wrap = <strong>|
The result is a text highlighted in bold: <strong>HELLO WORLD! Spaces, markers for tabs, and line breaks before and after the individual parts of the wrap are removed when it is passed on.
5.3.3 Functions Softlink 991290
As already described, several data types take on a special capacity. They are used equally by many content objects and provide universal functionalities for them. On the PHP level they are implemented by independent functions, which is why they are also listed as functions in the TSref. They fit in seamlessly, however, with other TypoScript data types into the syntax of objects and properties. But they can only be used if properties are of the corresponding data type, since they are called up explicitly on the PHP level. The TSref documents which property is of which data type. Please bear in mind that functions are not available for constants. stdWrap This function plays a very important role in TYPO3. Depending on how it is used, data can be imported, controlled, and manipulated by it. Many of the functions below can be used from stdWrap. So if the data type of a property is stdWrap, powerful tools are available for processing its contents. imgResource This function defines the source of an image file, subjects the image to simple processing steps, and creates the required HTML code for its output. The function is available under the properties belonging to the imgResource file type of the same name. imageLinkWrap This function allows an image to be edited with the advanced features of the graphic library (GIFBUILDER). In addition you can set a simple link (typolink) or a zoom link with the showpic.php script to open the image in a separate JavaScript window. numRows With this functionality you can determine the number of records
230
5.3 TS Objects, Functions, and Data Types
in a table or in a Select query. select with this function an SQL query can be formulated that will be displayed by the CONTENT cObject. Hidden or deleted records, or ones restricted in visibility by start/stop rules or front-end user groups, are not taken into account in this process. split This function splits a text content on the basis of a specific character or letter, and processes the resulting sections with further functions or content objects. This is helpful, for example, if a menu is to have multiple colors. if The if function imitates the classical IF control structure. If the subordinate conditions are all met, the contents of the child object remain as they are. Otherwise FALSE is returned and the contents of the object are deleted. typolink typolink sets a link around the content passed on. This function should always be used where possible instead of "hard-coded" links, not least because this supports the simulation of static HTML files.
textStyle The somewhat aging textStyle function defines the appearance of text areas when using FONT or other HTML elements. The modern alternative to this would be to use CSS definitions. encapsLines This function inserts paragraphs, for example, into HTML tags for the output. Tags such as P or DIV are added when parsing, and not saved with the content in the database, so that the content remains "clean". tableStyle The content is enclosed by a TABLE tag with tableStyle. Various design details can be defined here. The function is useful, for example, in the planning of the basic layout table, especially for setting up pure TypoScript templates. addParams Using this function, additional attributes (parameters) can be 231
5 TypoScript
passed to HTML elements of existing cObjects. filelink With filelink a file name is converted to a download link. Path details, attributes such as alternative text or title, and icons are added. Advanced features of this function can count the number of downloads or disguise the actual location, for reasons of security. parseFunc An extended postprocessing of the contents is possible with this function. You can, for example, replace markers inserted in the text, define rules for using or substituting HTML elements, or start a recursive processing of nested HTML blocks, while bringing in further functions. In this way you can wrap contents or search terms so they are more easily identified, and determine how links or ordered and unordered lists are generated, or which tags may or may not appear in contents. makelinks makelinks generates complete HTML links from simple web or e-
mail addresses that appear in the content. tags You can use this function to define your own abstract tags. They are saved in the database and are substituted in the output, where required, by various HTML elements that really exist. This function is used in conjunction with parseFunc. One example of user-defined tags in TYPO3 is the element, which is replaced during parsing with a proper HTML link. HTMLparser The HTMLparser function separates the entire HTML input into single HTML elements and their attributes. In doing this, defined rules are applied for the interplay of elements and attributes. The function is especially useful for manipulating imported or alien HTML contents, and when working with the Rich Text Editor. HTMLparser_tags HTMLparser_tags is called by the above-mentioned HTMLparser
function. It defines precise rules for attributes of each single HTML element.
232
5.3 TS Objects, Functions, and Data Types
5.3.4 Content Objects (cObject) Content Objects or cObjects is what TypoScript is all about: they create
Softlink 207606
output from data, using a TypoScript setup. Although other methods of data input and output are possible, in general content objects are used to transform the data of the content types that are available in the back end (Text, Image, Insert plugin,...) and saved in the database, for output in the front end. An array with current data, which can be accessed, is assigned to every cObject while it is being processed. This is usually the data of the current record. If a Text w/image content type is rendered, for example, the data entered (for example the heading on the file names of the inserted images) is available to the TypoScript setup that displays this content element, because the fields of the record can be accessed (cf. section 5.11.3). In the examples so far, we have just used the TEXT, HTML, and HRULER cObjects. But TYPO3 has a large number of possible cObjects.
Example: cObject FILE The cObject FILE integrates content elements from the file system up to a maximum size of 1024 kB. A special feature is that image resources of the types JPG, GIF, JPEG, and PNG are displayed with an tag. All other formats are parsed and their contents displayed unprocessed.
Softlink 036048
In the following example page.10 is defined as a FILE cObject. The file property (data type: resource) points to an image in the GIF format. The page.20 object is also defined as a FILE cObject, but points to a file in the TXT format. As a result the file is parsed and its content displayed. page = PAGE page { typeNum = 0 10 = FILE 10.file = fileadmin/images/layout/logo.gif 20 = FILE 20.file = fileadmin/documents/text1.txt }
Figure 5.32: Accessing the file system with the FILE cObject (output in the front end)
233
5 TypoScript
An Overview of cObjects HTML HTML is used to display HTML content. The value property is of the stdWrap data type, with which properties of the function of
the same name are available. Example: 10 = HTML 10.value = this is an HTML object 10.value.case = upper
TEXT TEXT is very similar to the HTML cObject and is used to display nonformatted texts. The properties of the stdWrap function are
addressed by the basis of the object, however, which is not the general rule. Example: 10 = TEXT 10.value = this is a text object 10.case = lower
COBJ_ARRAY (COA, COA_INT) The COBJ_ARRAY cObject (alternatively: COA) comprises various objects in a numerical list, in one array. If you create an object of the COA_INT type, it behaves exactly like the USER_INT object: it is rendered non-cached! Example: temp.myObject = COA temp.myObject{ 10 = HTML 10.value =
20 = TEXT 20.value = A cObject, created with COA. 30 = HTML 30.value =
}
FILE With the FILE cObject you can access the file system and integrate text, images, or HTML files, for example.
IMAGE Images can be integrated with the IMAGE cObject. The file property of the imgResource data type enables access to the file system or to the resources of the template record. Example: 10 = IMAGE 10.file = header_dealers*.gif 20 = IMAGE 20.file = fileadmin/images/layout/header_products.gif
IMG_RESOURCE The IMG_RESOURCE cObject returns only the reference to the image without an tag. Example: 10 = IMG_RESOURCE 10.file = header_dealers*.gif 10.stdWrap.wrap =
Our Dealers
CLEARGIF The CLEARGIF cObject inserts a transparent GIF image that can be used as a placeholder. Example: 10 = CLEARGIF 10.height = 15
CONTENT With the CONTENT cObject you can display the contents of the database. The Select query is restricted to tables that begin with tt_, tx_, ttx_, fe_, or user_. To display the records, an appropriately configured TLO is necessary with the name of the table that defines the output. The tt_content table, for example, is preconfigured in the Content (Default) standard template. Example: output of the contents of the current page and the "Normal" column:
235
5 TypoScript 10 = CONTENT 10.table = tt_content 10.select { pidInList = this orderBy = sorting where = colPos=0 }
RECORDS With the RECORDS cObject, records from the database can be displayed. This is comparable to the Insert record content type. Records from inaccessible pages (hidden, time-restricted, or access-protected pages) can normally not be selected as long as the dontCheckPid option is not set. Example: here the address records with UID 2 and 3 are read out. 10 = RECORDS 10 { source = tt_address_2,3 tables = tt_address conf.tt_address = < tt_address.default }
HMENU With this cObject you can generate a hierarchical menu. The (1 / 2 / 3 /...) property determines which menu object should be rendered by the different levels. Example: 10 = HMENU 10.1 = TMENU ...
CTABLE The CTABLE cObject creates an HTML table whose contents cell is surrounded by four further cells. Content can be assigned to each of these cells. Example: 10 = CTABLE 10 { tableParams = border=0 width=500 c.10 = CONTENT ... rm.10 = HMENU ... }
236
5.3 TS Objects, Functions, and Data Types
OTABLE This HTML table is used to add an offset to the contents, that is, they are offset from the upper left corner. Example: 10 = OTABLE 10 { offset = 10,70 tableParams = border=0 width=100 10 = TEXT 10.value = Content }
COLUMNS With this cObject you can create a table for which you can specify the number of columns, parameters, number of rows, width, column spacing, and the width of the common dividers. Example: 10 = COLUMNS 10 { 1 = CONTENT ... 2 = CONTENT ... gapWidth = 30 gapLineThickness = 1 if.isTrue.numRows < .1 if.isTrue.ifEmpty.numRows < .2 totalWidth = 500 }
HRULER This simple cObject draws a horizontal line, for which you can specify the thickness and color of the line, and its spacing to the left and right. Example: 10 = HRULER 10 { lineThickness = 1 spaceLeft = 20 }
IMGTEXT The IMGTEXT cObject helps to arrange images and texts. It is normally used to generate the Text w/Image content element. 237
5 TypoScript
The images are placed in a table, which is positioned before or after the text, and to the left or right of it. Example: the extensive IMGTEXT object of styles.content (default) is replaced. temp.imagetext = IMGTEXT temp.imagetext { text < tt_content.text.20 imgList.field = image textPos.field = imageorient imgPath = uploads/pics/ imgObjNum = 1 1.file.import.current = 1 maxW = 150 border = 1 textMargin = 10 } tt_content.textpic.20 > tt_content.textpic.20 < temp.imagetext
CASE CASE provides functionality in case distinction similar to the switch construction in PHP. If the key property matches the name
of another property of the object array, then this object is displayed. The naming of the cObject can be freely chosen but the reserved words key, default, stdWrap, and if cannot be used. If the key property is not defined, then the default object is used instead. Example: for the Text content type, layout 2 is displayed, with a heading with lowercase letters. temp.stuff = CASE temp.stuff.key.field = CType temp.stuff.default < lib.stdheader temp.stuff.text < lib.stdheader lib.stdheader > lib.stdheader < temp.stuff lib.stdheader.text { 10.2.case = lower }
LOAD_REGISTER The register is an internal temporary memory in TYPO3. The variables stored there are globally available and are read out, saved, or overwritten at various points during parsing. With LOAD_REGISTER, temporarily saved values can be overwritten by 238
5.3 TS Objects, Functions, and Data Types
the system through your own definitions, in order to influence the process of content generation. The temporary memory is organized as an array and can take in properties and their values. Example: the time of the last update of the page is overwritten with a fixed date: 10 = LOAD_REGISTER 10.SYS_LASTCHANGED.data = date: U
RESTORE_REGISTER This object undoes the changes in the internal system register made by LOAD_REGISTER. The original register array is restored. If the registry changes are only supposed to have an effect at a specific point, and then need to be replaced again with system values, it is appropriate to use RESTORE_REGISTER. Example: 20 = RESTORE_REGISTER
FORM The FORM object is responsible for the output of forms. Using this, forms can be defined both directly in TypoScript (e.g. the system's own mail and login forms) and in the back end of the system by editors. Example: login form temp.loginform = FORM temp.loginform { dataArray { 10.label = Username: 10.type = *user=input 20.label = Password: 20.type = *pass=password 30.type = logintype=hidden 30.value = Login 40.type = submit=submit 40.value = Login } layout =
###LABEL###
###FIELD###
stdWrap.wrap =
|
hiddenFields.pid = TEXT hiddenFields.pid.value = 123 }
239
5 TypoScript
SEARCHRESULT The SEARCHRESULT cObject controls the output of the hit list via the Standard, Advanced, and Not in menu page types, as a result of a database-based TYPO3 search. Apart from the values for tables and fields to be included in the search, the appearance of the list is determined. The search terms are supplied by an added form with special URL parameters. Database queries are performed in the background and the result list is returned. The search terms are retained in the register described above, so that terms found can, for example, be color marked by other functions. USER and USER_INT These content objects are the recommended instrument for integrating your own PHP scripts. The object calls a PHP function or method of a class, and any individual configurations can be passed on here. Nearly all front-end plugins are based on these objects. The USER_INT object is used especially if dynamic functionalities are involved that cannot or should not be cached. If the user sends a newsletter registration, for example, this data must be dynamically processed for it to be saved in the database. Example: includeLibs.alt_xml = media/scripts/xmlversionLib.inc 10 = USER 10.userFunc = user_xmlversion->main_xmlversion
PHP_SCRIPT PHP_SCRIPT serves to integrate simple PHP scripts. A disadvantage here is that the caching functionality of the page has to be completely switched off, causing noticeable delays when calling the page and increasing the load on the server.
To integrate your own scripts, you should, where possible, make use of USER or USER_INT. This option is ignored if $TYPO3_CONF_VARS["FE"]["noPHPscriptInclude"] = 1; is set in localconf.php. PHP_SCRIPT_INT In contrast to PHP_SCRIPT, this variation does have some improvements in caching, but causes problems in debugging and with global variables. USER or USER_INT should be used instead.
240
5.3 TS Objects, Functions, and Data Types
PHP_SCRIPT_EXT With this object, integrating scripts takes place outside the TypoScript environment. A significant performance advantage is gained in doing this, but the processing is to a large extent "missed" by TYPO3. USER or USER_INT should be used instead. TEMPLATE You can load an HTML template with this cObject. In contrast to FILE you can limit the output of the HTML file to specific areas.
You can specify which content will replace which placeholders. Example: page.10 = TEMPLATE page.10 { template = FILE template.file = fileadmin/templates/test.tmpl workOnSubpart = DOCUMENT subparts { HELLO = TEXT HELLO.value = this text replaces the subpart "HELLO" } marks { TESTMARKER = TEXT TESTMARKER.value = this text replaces the "TESTMARKER" marker } }
MULTIMEDIA This cObject gives you a way of integrating various multimedia files. Some possible file types are: TXT, HTML, HTM, CLASS, SWF, SWA, DCR, WAV, AU, AVI, MOV, ASF, MPG, and WMV. Depending on the file type, you can specify various parameters to be applied to the file. Example: 10 = MULTIMEDIA 10.file = fileadmin/video/test.avi 10.params.width = 200px
EDITPANEL In the context of the "front-end editing" concept, editing options for the page can be made available in the front end to users logged in to the back end. 241
5 TypoScript
Example: temp.editPanel = COA temp.editPanel { 10 = EDITPANEL 10 { allow = toolbar,hide,move,delete label = current page:%s you can create a new subpage here, or edit or move the page. line = 5 } 20 = EDITPANEL 20 { newRecordFromTable = tt_news line = 0 label = New page contents you can create a news article here } }
5.3.5 Top Level Objects Softlink 110842
To create an output page, the page object has been used so far, which was assigned to the PAGE object type. Here the page object represents a top level object (TLO). It lies in the top level of the object hierarchy. You could also say: it is at the far left in the TypoScript setup. TypoScript uses a range of TLOs that can have an influence on the application. In the "setup" area of the TSref, predefined TLOs are listed, together with the properties and objects that they integrate (e.g. FE_TABLE, FRAMESET, FRAME, META, CARRAY). Several toplevel objects such as config, constants, and FEData do not first have to be defined by being assigned a data type, since they are already predefined. types Data type: readonly Reserved for internal use (class.t3lib_tstemplate.php); type=99 is reserved for plain text display, for example. resources Data type: readonly resources is used internally to store resources for the
template hierarchy in a comma-separated list.
242
5.3 TS Objects, Functions, and Data Types
sitetitle Data type: readonly Reserved for internal use to parse the current title of the website from the templates. config data type: ->CONFIG Global configuration values for page generation, caching, debugging, link handling, etc. are defined with config; these values are saved with cached pages, which means that they are also available if a page is called from the cache. constants data type: ->CONSTANTS This defines constants that replace correspondingly marked text passages in the contents for the whole site. This is done when passing the contents with the parseFunc function. Example: constants.WEBMASTER_EMAIL = [email protected]
FEData data type: ->FE_DATA FEData configures how GET and POST data sent by users via the front end is handled. FEData is an old concept and is hardly used by extensions anymore. Example: guestbook.
includeLibs data type: array of strings With this you can integrate PHP files that have their own function libraries into TYPO3, so that these functions can then be accessed. Note that the PAGE object provides properties with the same functionality (page.includeLibs). But these properties are inserted after the TLO includeLibs and can overwrite values in the TLO. Example: includeLibs.gmenu_foldout = media/scripts/gmenu_foldout.php
plugin Plugins from extensions are inserted into the TLO plugin. Loaded plugins can be found via their extension key as subobjects in plugin. 243
5 TypoScript
tt_* The TLO tt_* is used to render contents from tables. The normally used content (default) standard template contains a corresponding definition for the tt_content table, thus controlling the rendering of most content elements. temp The TLOs temp and styles are used for code libraries that you can copy during parsing. They are not stored with the template in the cache, however, but are deleted/emptied before the template is cached! Use temp to store your own temporary data. styles Behaves in the same way as temp, but is not available for your own use, and is used by the included default templates instead. lib Serves to define code libraries to which references are made. ... data type: PAGE The title can be named as you please. But it is recommended that you use the title page for the definition of the TLO of the PAGE type. .... data type: any type Define your own TLOs and assign them to the corresponding data types. The TLOs used and the hierarchy of objects can be displayed clearly in the TypoScript Object Browser:
Figure 5.33: Top level objects of the template, displayed in the TypoScript Object Browser
244
5.3 TS Objects, Functions, and Data Types
Examples config A number of options are globally configured with config. If you set config.simulateStaticDocuments = 1 in the setup of the TypoScript template, for example, the dynamically created output of the front end is simulated as static pages. 4 With config.cache_period = 432000 you set the page’s cache life to five days. config { simulateStaticDocuments = 1 cache_period = 432000 }
constants With the TLO constants you can define constants for the entire application. This enables you, using the parseFunc function and its constants=1 property, to replace the corresponding placeholders with text. If the parser finds the constants of the ###WEBMASTER_EMAIL### example in the content of the application, then [email protected] is displayed as a link. constants { WEBMASTER_EMAIL = [email protected] }
lib The TLO lib is intended for libraries of reusable code that can be referenced. A text like the one in the example is not really ideal for this, of course! lib.welcomingText = TEXT lib.welcomingText { value = TypoScript is simply great. wrap =
|
} page = PAGE page { typeNum = 0 10 = TEXT 10.value = Hello Typos! 20 = < lib.welcomingText } 4 For the prerequisites, see TSref.
245
5 TypoScript
temp and styles Softlink 110841
The top-level objects temp and styles are peculiar in that they are removed from the setup after they have been parsed by TypoScript. This means that it is not possible to use a reference to the temp.myObject object, since temp no longer exists during processing of the setup. The reason for this is that all TypoScript values are generally stored in the cache_hash database table after they have been read in, to increase
performance. If certain parts of TypoScript need to be stored temporarily, the top-level objects temp and styles are intended for this. Their objects, properties, and values can then be copied to different points in TypoScript and reused. After parsing, however, they are deleted, which keeps the cached pages slimmed down. The toplevel object temp is intended for your own general objects, while styles was reserved for the standard templates (static templates) included in TYPO3.
5.4 Development Tools TYPO3 provides a number of tools for the developer to make programming with TypoScript easier. On the one hand the Web | Template module in the back end makes a large range of functions available, and on the other, the Admin Panel can be embedded in the front-end output, providing additional help utilities.
5.4.1 Info/Modify The Web | Template | Info/Modify module can show you a list of existing templates in the page tree. To do this, select the Rootline as the current page by clicking on the title of the globe in the page tree. The list shows the pages with templates, and whether these are root or extension templates. The module also helps in setting up new templates, if the current page selected is one without a template. If required, you can select a static template. In addition you have the possibility of skipping to the template that is closest to the current page.
246
5.4 Development Tools
Figure 5.34: Info/Modify can be used to create new templates
If you have selected a page with a template, the template can be edited, in which case you can select individual fields or the entire record. If you edit single fields, the TS wizard (see next section) is also available. In addition, the cache is automatically deleted.
Figure 5.35: Editing functions for existing template records
5.4.2 TS Wizard Just as editing is supported by wizards for the entry of content for content types such as Table or Form, there is also a wizard for TypoScript, with which object types and properties can be browsed through and selected. In the following figure you can see how a TS setup was opened for editing with the Web | Template | Info/Modify module. With the TS wizard icon, the wizard is opened in a separate window. 247
5 TypoScript
Figure 5.36: Selecting TypoScript objects and their properties with the wizard
First the list of object types is displayed, each of which can be opened in a details view with the [GO] link. In this example the HRULER cObject is opened. The details view shows the properties of the object type with its data types, description, and default values. If you click on the name of a property, the wizard closes and the property is included in the input form. In the example, the desired properties were first collected in the entry field of the wizard, with a click on the "+"-icons. Then the properties were enclosed with the object type, using Wrap. Finally if you click on the Transfer & Close link, the code is taken over. Softlink 090547
Even if the wizard cannot replace the TSref completely, it still has most information available, so that you don't have to worry about it all the time. The data displayed is created directly from the TSref OpenOffice document. Even the properties of extensions are read out from the respective documentation. You can find out how you need to prepare your extension documentation for this from the soft link here.
5.4.3 TypoScript Object Browser The TypoScript Object Browser (Web | Template | Object Browser) has already been used a few times in the previous sections to display TypoScript setup. Apart from just showing constants or the setup, the Object Browser also provides functions for testing conditions and for browsing through and displaying constants in the setup. In addition to this, properties can be edited with the Object Browser. 248
5.4 Development Tools
The Object Browser always works on the basis of the currently selected page or the template contained in it. However, in addition to the data of the current template, all the accumulated template data from the Rootline is also shown. The TypoScript active in the front end when the current page is called is shown. If conditions are defined in the template, these can be activated individually, so their behavior can be tested.
Figure 5.37: TypoScript Object Browser in the Web | Template module
The search function searches through the values of the properties and displays the search results in color. If the Use ereg() option is selected, regular expressions can be used. As shown in the preceding figure, constants can be highlighted in the setup, so that you can choose whether the original constants should be displayed, or the replaced values. 249
5 TypoScript
If you click on the name of a path element (e.g. property), you can edit this with the following form:
Figure 5.38: Editing mode for a property in the Object Browser
When you do this you have the chance to edit the value, add a property, or delete the selected element with >. The modified or added TypoScript is written to the current template, whereby the text line is always attached at the end. It may therefore be the case that after a while a confusing mass of code collects, which has to be sorted out by hand. But this editing option with the Object Browser is a great help, not least because the TS wizard is also available here.
5.4.4 Template Analyzer The Web | Template | Template Analyzer module has already been mentioned in connection with cascading templates, since among other things, it displays the hierarchy of the active template. The Template Analyzer shows the logical hierarchy of the template for the currently selected page—the templates used for front-end rendering. In addition to this, the table shows whether Rootlevel, Clear Constants, or Clear Setup is set for a template—as well as the page ID and the level (Rootlevel) on which the template is located. The last column shows the IDs of templates that were integrated with Template on next level. In the following figure, you can see how Clear Constants is set in the template with the title "One Extension Template", and therefore constants defined in previous templates are deactivated. 250
5.4 Development Tools
If you click on the title of a template, its active code is displayed. In this example we can see the code of the "Main Template" template. Constants are not shown, although some are defined in the template. The reason for this is that we are on a page in which the "One Extension Template", which has Clear Constants set, is active. The constants are therefore deactivated and are not shown.
Figure 5.39: Template Analyzer shows the hierarchy and code of individual Templates
Checking the Syntax TypoScript cannot be tested to see if a non-existent object is addressed or if properties and values were wrongly named. Minor typing errors are frequently to blame if the desired result is not achieved. You can only check to see if entries are syntactically correct. From TYPO3 version 3.6.0, Syntax highlighting is available to developers under Template Analyzer. In the above example an empty space was inserted into the object path. The syntax highlighter then complains that the space after the object path is not followed by an operator.
251
5 TypoScript
5.4.5 Constant Editor As described in section 5.2.8, constants are used in the template record to pass easy-to-handle or global values to the setup code. These constants can optionally be edited in a simple and clear manner with the Constant Editor (Web | Templates | Constant Editor). In this way standard templates, which configure complete web pages, make it very easy for the user to change the appearance and functionality of the site using constants. Standard templates in particular can be conveniently configured with the Constant Editor. In the following figure, a screenshot of the template is shown, as well as a description.
Figure 5.40: Constant Editor editing the GREEN standard template
252
5.4 Development Tools
The Constant Editor returns the preset values (default) for the selected template. If individual values are to be overridden, the checkboxes for the constants must be activated and the form must be reloaded. They are now set in the form fields and saved in the Constants field of the selected template record.
Highlighting Constants for the Constant Editor If you also want to make your constants changeable with the Constant Editor, additional information on the constants is necessary, such as descriptions and value ranges. For this purpose the constant definitions must be preceded by comments with specific syntax rules. Example: # cat=temp.myText; type=string; label= My Text myText.myTextInput = Hello World!
TYPO3 basically ignores comments when parsing templates, but not the Constant Editor. It divides groups up into categories, on the basis of additional data in the special comments, and displays them with a descriptive text (the label) for editing, according to their type. Syntax rules for comments:
•
The comment is set in the line before the constant involved.
•
Each comment line is divided by semi-colons into separate parameters.
Softlink 969386
•
Each parameter consists of a key and a value, separated by an equals sign. TYPO3 provides the following keys: cat (category and possible subcategory), type (type of constant), and label (explanatory text). The following template, my text, serves as an example. The template defines the text and its presentation with the help of constants. Input in the constants field of the mytext template: # cat=mytext/ctext/a; type=string; label= My TextmyTextInput = Hello World! # cat=mytext/ctext/b; type=typo; label= My fontmyTextFont = Verdana # cat=mytext/ctext/d; type=color; label= My text colormyTextFontColor = red # cat=mytext/ctext/c; type=small; label= My text sizemyTextFontSize = 32
253
5 TypoScript
Input in the setup field of the mytext template: temp.myContent = TEXT temp.myContent { value = {$myTextInput} textStyle.face.default = {$myTextFont} textStyle.size.default = {$myTextFontSize} textStyle.color.default = {$myTextFontColor} }
The constants can easily be changed in the Constant Editor, via the additional data for third parties. The following figure shows the current values of the myText template and of the temp.myText category.
Figure 5.41: Constants of the myText template in the Constant Editor
254
5.4 Development Tools
Parameters Categories (cat) Categories can be freely chosen, and bundle together various constants. This is why it is sensible to choose general terms that encompass a grouping. It is also possible to use the following preset categories for standard templates. basic The basic category bundles constants that are of great significance for the template layout. They are some of the basic constants you will probably always be configuring, and include dimensioning and image files, and allowing various properties to be activated. menu Menu settings are dependent on the type; they include font files, sizes, and backgrounds. content Constants that influence the display of content elements. page General configurations regarding the page such as meta tags, link destinations, etc. advanced Advanced functions that are rarely used. plugin.* Constants for individual plugins (extensions). Example: plugin.meta Subcategories Subcategories arrange the constants of a category in the Constant Editor according to areas, and are added to the category with /. Only those constants defined in the list are available. All the others are automatically shown under the Others subcategory. You can specify the order in which the constants are listed by adding a letter from a-z. If none is specified, z is taken as the default value. Example: # cat=basic/enable/b; type=string; label= My constants
255
5 TypoScript
Possible subcategories: enable For constants that are used to switch basic functions of the template on or off. dims For dimensions of all kinds, such as pixels, width, height of images, frames, etc. file Bundles constants that define files such as background images, fonts, etc.; further options concerning the file can be specified here. typo For typography and related constants. color Helps to summarize color definitions; however, many colors are also included in other categories, with related options. links For use with links; typically, target is specified for this. language Language-specific options. cheader, cheader_g, ctext, cimage, cbullets, ctable, cuploads, cmultimedia, cmailform, csearch, clogin, csplash, cmenu, cshortcut, clist, cscript, chtm
These subcategories are based on the predefined content elements of TYPO3 such as text, heading, image etc. Field type (type) With type you specify the field type, which defines the editing options for the user interface of the Constant Editor. int [low-h high] A whole number; optionally the value range can be specified. Example: int [0-10] int+ Positive whole number 256
5.4 Development Tools
color HTML-coded colors wrap A wrap can be edited with this offset [L1,L2,...,L6] Comma-separated list of whole numbers; you can specify up to six titles as comma-separated parameters in square brackets. The defaults are the titles x,y. options [item1, item2, ...] Selection field with titles/values, in which single elements are separated by commas; title and value are separated by =. Example: options [label1=value1, label2=value2] boolean [truevalue] Boolean value; optionally the value for "true" can be specified. The default value is 1. comment Boolean value; selected = "", not selected = "#" This type can be used to comment out, and thus deactivate, TypoScript code with the help of a constant. file [ext-llist /IMAGE_EXT] Helps to select file resources; it is possible to upload directly, to load files into the Resources field of the template record. Optionally this selection can be restricted to specific data types. To do this, a list of allowed data types, e.g. [ttf] or [txt,html,htm] (without spaces), is specified in the list. You can also enter [IMAGE_EXT]. In this case the default image file types are allowed. string Text input field. Header and description (label) With the help of the label type, a header and a descriptive text can be specified. The header and descriptive text are simply separated by a colon: 257
5 TypoScript # cat=mytext/ctext/a; type=string; label= My Text: The text appears on the right... myTextInput = Hello World!
Description for categories (TSConstantEditor) You can also define a general description for individual constant categories. This is used for example to explain the standard templates using a screenshot and additional description. The additional data is defined in the constants TLO TSConstantEditor. This allows you to assign numerical icons to individual constants and to integrate an image--usually a screenshot. Please note that TSConstantEditor is defined in the Constants field of the template. Use of the terms "TLO" or "object" and "property" for constants is not, strictly speaking, correct, since these are not objects. But we will use the terms here just for the sake of simplicity. Example: TSConstantEditor.mytext { header = my text description = my text is a demo // it contains ... bulletlist = List item 1 // List item 2 // List item 3. image = gfx/szenario-1.png 1 = myTextInput,Text 2 = myTextFont,Color }
Here is a summary of the properties of TSConstantEditor: header Data type: string Header for the description; this is shown in capitals. description Data type: string Description of the template itself; new lines are implemented with //. bulletlist Data type: string Displays a bulletlist; individual items are separated with two slashes, //. 258
5.4 Development Tools
image Data type: image You can optionally insert an image to illustrate the connections. Enter the numbers of the constants that you are describing on the picture, and position where they will be visible in the front end. The image must be stored in the gfx/ directory of the Constant Editor module (tstemplate_ ceditor), or integrated with the resources field of the template record. Array, 1-2 20 List of constant names Red-numbered icons are assigned to the listed constants in the Constant Editor via the numerical list. They establish the connection to the specified image.
5.4.6 Admin Panel Apart from the functions for editors, the Admin Panel also provides information for the TypoScript developer. During rendering, TSFE logs the rendering process; the log can be displayed in the Admin Panel. If the Admin Panel is configured accordingly 5, the following options are offered in the TypoScript section: Tree display If this option is activated, the output is displayed as a tree. Display all times 6 This option shows the time in milliseconds needed to render the page elements. Display messages Additional explanations and error messages are shown in the rendering log, which is switched on with this option. Track content rendering Information on the rendering of contents is shown here. Output is restricted to general information and PAGE objects.
5 Setting up the Admin Panel is described in section 4.7. 6 Up to TYPO3 version 3.6 this option was wrongly described as "always show". Other
options are also described more clearly in version 3.7.
259
5 TypoScript
Display content If this option is active, the generated content can also be displayed. In this way you can look directly at the HTML code for the corresponding TS object. Explain SELECT queries SQL queries are shown with this option and analyzed using the SQL EXPLAIN instruction. Due to the introduction of the DB abstraction layer in version 3.6, this does not function, but it was also used very little in Version 3.5. Force TS Rendering If this option is deactivated, it is possible that the page will be loaded from the cache. So if you want to test your TypoScript template, the option should be activated. In the output of the Admin Panel, various elements of the rendering process are highlighted in color in the details column. Messages are shown in black, error messages in red with a preceding icon, file contents (HTML templates) in green, and generated content in blue. TS objects embedded inside generated content are shown at the corresponding positions in red, enclosed by square brackets.
260
5.4 Development Tools
Figure 5.42: TypoScript area in the Admin Panel for displaying the front-end rendering process
5.4.7 Import and Export of TYPO3 pages TYPO3 provides a quite unassuming function in the context menu, in t3d Import and Export, that can also be very helpful for the developer, for example, to import and export templates as files. In addition it is possible to export entire page trees with contents, including directly integrated media such as TYPO3 documents (t3d file), and import them back into other TYPO3 applications.
261
5 TypoScript
t3d Export The export of records is called with the More options ... | Export to .t3d context menu. First you select the page in the page tree from which the export should be started. The following form serves to specify the extent of the export, which can involve entire page trees or just single pages.
Figure 5.43: Calling the t3d export from the context menu
The configuration for the export is specified in the top area of the user interface. Various properties and functionalities are available.
262
5.4 Development Tools
Figure 5.44: Determining export properties
263
5 TypoScript
Page ID Page ID of the page from which the export should be performed. Tree The page tree to be exported, which is selected via the start page and the level depth. Levels The depth of the levels to be exported (beginning with the start page selected) can be specified in a selection menu. Include tables Here you can decide what content of database tables located in the section of the page tree selected should be included in the export. Include relations to tables If the records contain relations to records outside the page tree selected, you can define here which tables should be included. The selected configurations are applied with the Update button . The structure of the records selected for export is shown in detail in the lower area. If relations are lost, they are marked with Lost relation. If the details are correct, the export is started with the Download export button. 7
t3d Import The import of data via a TYPO3 document is in turn called from the context menu with the menu item More options... | Import from .t3d. The starting point is the page on the page tree from which the data should be integrated. Since an import via the Rootline (globe) is not possible, you can start an import via any page, for example, and then move the imported page tree.
7 If you experience difficulties in downloading, we should point out a bug in Internet
Explorer 5.5 which tries to save the page of the back end as a download.
264
5.5 Standard Templates (Static Templates)
Figure 5.45: Calling the t3d import via the context menu
The TYPO3 document (.t3d) must be located directly in the fileadmin/ directory to be imported. You can upload a file directly to this directory with the form displayed, so that it is available for selection for import through the selection menu. Preview shows a preview of the records to be imported.
Figure 5.46: Import interface for a TYPO3 document
5.5 Standard Templates (Static Templates) Every TYPO3 package already contains records in the static_template table that are only readable from the back end, but not directly changeable. These are the so-called standard templates, also known as static templates. You can have the standard templates listed using the Web | List module, for example, if you select the Rootline (globe) in the page tree.
Softlink 546011
The standard templates supplied represent the library and can be used in your own websites. They provide complete site templates; but they also contain some basic individual TypoScript components such as content 265
5 TypoScript (default), which define and format the output of content elements.
Figure 5.47: Standard templates contained in the TYPO3 basic installation listed by the Web | List module
A number of templates are marked with the label [DEPRECIATED], which means they are considered to be old or out of date, and are only included for reasons of backward compatibility. In particular, most plugin.* templates have become redundant since the introduction of the extension system, as corresponding templates are supplied with the extensions. To use the templates, insert them with the Include static field into the template record.
Figure 5.48: Inserting a standard template
As already mentioned, extensions can include their own templates. In this way it is possible that they offer standard templates, which can be selected in the template record under Include static (from extensions). In 266
5.5 Standard Templates (Static Templates)
their function, these correspond to the templates available via Include static. Even entire website templates can be made available in this way. An example of this is the Green template, which was implemented as an extension and can be found in the TER for download. The standard templates are assigned to various categories, depending on the application field, and given corresponding prefixes (template, plugin, content,...). An overview follows of the individual categories.
5.5.1 content (default) This is the most used standard template. As a rule it not only forms the basis for websites and other standard templates, but also defines the basic processing and representation of content entered in the front end. The template applies corresponding content objects to the records of the tt_content table, depending on which content type was specified by the editor (the CType table field). The template is based on styles.content.default, in which individual content types are defined in detail. In addition, styles.sitemap.text and styles.header.gfx1 are also included as basis templates. The template remains at the heart of TYPO3, although more recent developments have gained prominence. content (default) uses TypoScript not only for display but also for program logic, which is not actually the core task of TypoScript. But the demands made on TypoScript have changed, in particular through the increasing acceptance of CSS-based layouts and the need to have access for those with disabilities to Internet sites. It is intended that the code will be slimmed down and that more competence be delegated to CSS or extension functionality. This concept has been continued in the successor template from the extension of the same name, css_styled_content. Many of the standard templates are merely code components integrated into a larger context. These connections between the individual templates can be viewed in the Template Analyzer. Figure 5.49: Content (Default) and the integrated basis templates in the Template Analyzer
This type of template menu provides code fragments for other standard templates. Many of these templates are used in the site templates (template.*), which can be seen from the suffix used, e.g. styles.hmenu.tu, styles.gmenu.bug. Others such as styles.sitemap.text and styles.header.gfx1 are used in the content (default) template. The components have been stored in separate templates so that they can be re-used in other standard templates. They provide preconfigured page objects such as menus, sitemaps, headings, and logos.
styles.content (default) The styles.content (default) template deserves special mention; it contains a selection of predefined TypoScript objects for use in other templates, in particular for basic content rendering in the content (default) template. The most well-known example from this template, often used in practice, is styles.content.get, which selects the contents entered in the back end in the Normal column for display: styles.content.get = CONTENT styles.content.get { table = tt_content select.orderBy = sorting select.where = colPos=0 select.languageField = sys_language_uid }
268
5.5 Standard Templates (Static Templates)
You never need to switch the template on separately, as long as you are using the content (default) template, with which it is automatically integrated. Many settings can be configured in this template with constants (module: Template | Constant Editor | Content).
5.5.3 cSet.* cSet (default) cSet stylesheet
cSet (default) This was introduced as a further step towards effectiveness in creating websites; it continues to be used frequently in practice, although it has been overtaken to a large extent by cSet stylesheet, and more recent concepts such as the CSS styled content extension make it completely superfluous. The template only contains definitions of constants. The core idea of the template is to bundle individual definitions from styles.content.default and to make available new, global constants for these. This makes it possible, for example, to define the font for all content objects with one entry. The definitions bundled in this way can be easily adjusted in the Constant Editor, in the CSET category. cSet stylesheet This is a more modern alternative, but here the focus is on the use of cascading stylesheets (CSS), which was summarized in a separate file (media/scripts/defaultstylesheet.css). After changing the link to a newly created CSS file in the fileadmin/ directory # Example input in the constants field content.stylesheet.file = fileadmin/styles/default stylesheet-modified.css
the existing CSS definitions can be applied and individually adjusted. In contrast to cSet (default), this template not only contains constants, but also changes several settings in the setup. In particular, tags are removed and the headings replaced by native HTML headers (h1-h6), and is replaced by
These documents for frameset-based websites are in part used in the site templates described below. The name implies which layout will be implemented; frameset; top-page-right for example means: one frameset at the top, a central content frameset (page), and a frameset to the right. The size of individual framesets can be set with constants. Some of the frameset templates can also be nested. The template with (+) does not generate a complete page, for example, but serves as an extension for another frameset template. The frameset templates above all have a didactic value, since they make it easier to understand the handling of framesets in TypoScript. In practice, however, layouts are often used that are not covered by these documents.
5.5.5 template;* Templates with this prefix are optional out-of-the-box templates for displaying the website. They are all based on the content (default) standard template for rendering content. Make sure that your desired standard template is listed at the top of the included standard templates. Adjustments can be easily made with the Constant Editor.
270
5.5 Standard Templates (Static Templates)
Figure 5.50: Example page displayed with different standard site templates
The available templates are ideal not only for examples, but also for websites that need to be brought online "in a hurry". The examples are quite ancient and are based either on pure TypoScript templates, on the integration of HTML templates, or on frames. A project group has been formed within the TYPO3 community with the aim of creating new templates with a fresh design, taking into account accessibility. The templates available until now will then be moved to an extension. The current out-of-the-box templates and their functionality: TU TU is a template without frames. You can specify a head image and the background color for the page. The graphic menu on the left side has two levels; it changes the text color for rollover and in an active state. You can add background pictures to individual menu items and define their TrueType font, text color, and size, as well as the offset. There is also an option to insert graphics before and after the menu (so-called clear.gifs as placeholders). RE This template is based on frames. The upper frame contains a graphical menu of the first level, the left frame, a graphical menu of the second level. The third frame contains the page contents. You can define the states Normal, Rollover, and Active for the 271
5 TypoScript
menu items (background images and colors, text color, etc.). If you wish, you can define a background image for each frame and position a graphic beneath the left menu. NEWSLETTER This is a template for a page without menus. As the name suggests, it is intended for sending a newsletter as an HTML email, with the Direct Mail module extension. It is based on an HTML template file, which determines the layout of the page. You have a choice of one or two columns. The head logo is not defined in this HTML template, but is configured directly via TypoScript. HYPER HYPER is a frame-based template, consisting of the head with a DHTML layers menu and a single column frame for the contents. The page title is shown in a picture, and you can specify a logo for the head region. The appearance of pages is influenced by stylesheets.
GREEN This one-page template is based on an HTML template. This means that all elements such as main menu, submenu, head image, logo, page title, and page content are positioned in this file with the corresponding markers. You can modify the HTML template just as you wish. The menu is a DHTML-based popupmenu in which the first level is graphics-based and the second level is text-based. Optionally you can have another text-based menu shown in the third level. If you want you can choose to show the page title beneath the menu. Background images for tables and tables cells can be defined with TypoScript. GLÜCK This standard template is based on a three-column table. The first level of the text-based menu is in the left-hand column, the second level in the right-hand column. Both columns are optional, i.e. they can be switched off via TypoScript. You can define a logo, background image, and contents for each column. Margins, widths, and alignments can be adjusted in detail. The page background and page color can also be defined. This template is configured entirely with TypoScript. FIRST FIRST is a frame-based template in which the frames Menu, Bottom, and Page frame are nested in another frameset, which
centers the page in the browser. The menus are arranged graphi272
5.5 Standard Templates (Static Templates)
cally on two levels. A further, separate general menu from a directory can be found in the bottom frame. You can define the background color and dimensions for each of the three frames, or optionally integrate another column with news from a specified page. CrCPH CrCPH is a single-page template based on an HTML template file. TypoScript is used less here. You can modify large parts of the layout to your requirements by editing this template file with your preferred HTML editor. The two text-based menus are also defined directly in the HTML template.
CANDIDATE CANDIDATE is a single-page template with two content columns and a text-based menu with one level, placed beneath the head image in the main column. The page title (or the subtitle, if it exists) appears on the head image. But you can also switch it off. You can deactivate the right-hand column, or have it shown on the left-hand side instead. You can also place the head image over both columns, or vary this image in certain branches of the website. The first image is displayed for the whole branch, which is assigned to the page on the first level. The width and color of the space between the two columns can be specified or reduced to zero.
BUSINESS BUSINESS is a frame-based template with a very simple two-
column layout. The menu is in the left-hand frame, and the page content in the right-hand frame. You can define background images for each frame and set the width for the left-hand frame. The menu is text-based and shows two levels. The font tags can be adjusted to your requirements for both levels. In the second level you have the option of placing graphics in front of each menu item, which can be changed on rollover. In the page head, the page titles of the overlying pages are shown for the first and second levels of the current page; as with the menu, you can define the font tags of this page title. It is possible to draw a line beneath the page title, the color of which you can define. MM MM is a single-page template with an imagemap-based menu in
the head area. You can define background images and color, as well as the border width and color. Additionally you can specify contents for an optional second column, and determine its 273
5 TypoScript
background color and images, as well as other standard headers and text properties. You can add an offset between the two columns, and the background color and image can be freely chosen. For the imagemap menu, the following configuration options are available: background color, TrueType font, text color, size, and spacing in the image. BUG BUG is a frame-based template. Three frames are available: top,
left, and right. All frames can be configured in terms of their size and background color. In the top frame it is possible to include a graphic, in the left-hand frame you can specify the layout for the graphical menu: background image for the entire menu and for individual menu items, rollover effects (for text color and/or graphics before or after the page title), TrueType font, text color, size, shadowing, spacing.
Plugins are responsible for the display and functionality of special, mostly dynamic contents in the front end, and normally contain their own PHP functions. The standard templates with the plugin. prefix can be divided into two groups. One group is responsible for embedding special contents and functions into the general content flow, e.g. plugin.tt_news or plugin.feadmin.fe_users. The second group (plugin.alt.*) generates 274
5.5 Standard Templates (Static Templates)
complete pages that are processed and displayed differently to normal content pages. Depending on whether a printed version, text version, XML version, or WAP version for mobile phones is involved—content is displayed differently in each case. While the print version, for example, is only implemented with TypoScript modifications, a totally different rendering engine is used for the XML plugin. Through this capacity to display existing content in several alternative formats, the functionality of plugin.alt. templates is moving towards cross-media publishing. Nearly all plugins from the first group are identified with DEPRECATED, because when the Extension Manager was introduced, all templates were moved to corresponding extensions. These templates should not be used for new projects. But they are still to be found in the list of standard templates, for reasons of backward compatibility.
5.5.7 temp.* temp.tt_board (shared) [DEPRECATED] temp templates are helper templates that serve as components or "code snippets" for other templates. temp.tt_board (shared) is part of the
function of the forum plugin and is the basis for two more templates: plugin.tt_board_list and plugin.tt_board_tree. It is responsible
for the general display and functionality of the TYPO3 Forum. The two other forum templates for displaying lists and trees use the basic settings for this helper template. All three templates are out of date, as they have been moved to the Message board, twin mode (tt_board) extension.
This is a method used to directly output records from tables, in this case tt_address. The addresses output do not require a plugin with PHP functionality, but are formatted with the simple use of TypoScript objects. It is also out of date because it was replaced by the template for the Address list (tt_address) extension.
5.5.9 (example) records (example)
This example template shows, like the content.tt_address template, how the output of content from extended tables (tt_address, tt_links, 275
5 TypoScript tt_news, etc.) can be rendered by the simple use of Typoscript. It should not be used in projects, but serves merely as an example of usage.
The language templates help to configure various languages, and are another ancient feature of TYPO3. There is hardly any use left for this type. The reason for this is not only that they were moved to extensions. Even there they are no longer up-to-date, because the entire language control is now stored in special files in the individual extensions. In earlier versions of TYPO3 they served the purpose of supplying translations for plugins and individual content objects, such as login forms or search forms; they are included now for reasons of backward compatibility.
5.6 Base Layout—Template Concepts When developing a web application with TYPO3, you are faced with the choice of which method to use. Depending on your knowledge as a web developer, and on the requirements of the project or customer, the important thing here is to decide if the base layout should be based on HTML tables or cascading stylesheets (CSS), whether frames will be involved, etc. These decisions should be made independently of TYPO3, since all options are open to you with the CMS. In the next step you decide on which method will be used to implement the requirements of the base layout and to mark the contents with TYPO3. There are several ways to do this, which makes it difficult to retain an overview and make the right choice when coming into contact with TYPO3 for the first time. The individual template methods are briefly characterized below and then each implementation is introduced.
276
5.6 Base Layout—Template Concepts
5.6.1 Standard templates (static templates) TYPO3 provides you with complete out-of-the-box website templates, as so-called standard templates. Their appearance and functionalities are already set, but can be adjusted to a certain extent with constants. Above all they are regarded as very good references to study working with TypoScript examples, but they can also be used productively, of course. But if CI guidelines for professional fields and individual requirements need to be considered, the developer will quickly reach the limits of standard templates in terms of being able to adjust them.
5.6.2 Pure TypoScript Templates The entire base layout of a website can be determined completely with the help of TypoScript, without having to use external HTML files. With this method you can work in two ways: 1. It is possible to quickly specify a table layout, using the cObject CTABLE, which will divide a website into areas such as topMenu, leftMenu, rightMenu, bottomMenu, and content-cell. 2. The layout can be controlled entirely via CSS, by wrapping all the page elements with the HTML tag. This technique is ideal for implementing accessibility-compatible websites. Layouts that are controlled by tables or stylesheets can now also be implemented by integrating HTML templates. Pure TypoScript templates could have some advantages:
•
All information controlling the output is located in one place, and is not stored in external HTML files. This provides clarity and full control.
•
The HMTL code can be constructed on a very modular basis using TypoScript with constants and setup. This makes it particularly easy to carry out area-specific modifications to a site.
•
TS templates cascade and HTML templates do not. So you can nest a layout template and spread it over various templates, or overwrite parts of the page tree.
Especially for layouts that are implemented via CSS and do not use tables, the use of an external HTML template is hardly necessary any longer, or has no advantages, since the individual areas of the basic layout are only marked with tags, and everything else is controlled via CSS. 277
5 TypoScript
5.6.3 TypoScript and HTML Templates Even though the methods of pure TypoScript templates are extremely flexible, and thus efficient, models usually gain acceptance due to their simplicity. For this reason developers will also be given the opportunity of integrating external HTML templates through the TEMPLATE cObject. The concept is one of substituting special areas of the HTML template, located with markers (subparts and marks) with contents from the database. Advantages of integrating HTML templates:
•
From the point of view of the web developer, they can be implemented very quickly, with little preparation time needed.
•
The base layouts can be made with external editors.
•
When working in a team, content designers and TYPO3 developers can work in parallel if content areas and functionality have been specified right at the beginning.
5.6.4 Template Auto-Parser Softlink 591606
TYPO3 would not be TYPO3 if it did not continually try to improve and simplify editing procedures. The Template Auto-Parser extension is such a development. Using this it is possible to parse HTML templates to be included, and thus have the corresponding subparts marked automatically. They are identified with the id of HTML elements such as , <span> and
. Moreover all parts of the stylesheets and images in the HTML template are updated to the correct folder within the file system of fileadmin/. Working with the Template Auto-Parser is documented in depth in section 5.9.2 as well as in the tutorial, "Modern Template Building, Part 1" (see soft link). Pros and cons of the Template Auto-Parser:
278
•
The user focus of the method is aimed principally at agencies and web developers from the field of HTML design. Results are achieved quickly without subparts having to be marked by hand. But the subjective feelings of the TYPO3 developer are that the Template Auto-Parser takes over "control" of the proceedings to some extent.
•
If roles are swapped during development, there will be no danger that the screen designer will accidentally remove markers designating subparts in the HTML template.
5.7 Content Rendering Concepts
5.6.5 TemplaVoila The newest method of template integration is called TemplaVoila. This is just one of several extensions (TemplaVoila!), which arose in the context of a rather large project for the Dassault Systemes group in France. It is currently still at the alpha stage, and a large amount of development is still to be done. But even at this point in time it is worth taking a look at the concept and its outlook, if only as a means of comparison to other solutions.
Softlink 003992
TemplaVoila promises to implement the design within minutes (instead of days) provided that an HTML template is available. The area for the page content is divided into zones that can contain different formats of content elements. This technique replaces the organization of content via columns otherwise used in TYPO3. For this purpose, the already great wealth of options for template management has been complemented by a new one. It provides the developer with a GUI for a graphic-based definition of content elements, by selecting HTML design files (point and click). Advantages of TemplaVoila:
•
This approach opens up a new flexibility for the structuring and composition of content blocks and zones, with all the advantages of a CMS and the usual extensive control over the design.
•
New content elements can be made very quickly using templates and used immediately without having to be programmed.
•
Control rules can be defined with the system to determine possible combinations of content elements.
TemplaVoila is still in the development stage. Technical concepts until now linked closely to the organization of content via columns, such as multi-language capability through a page tree, still need to be implemented. But TemplaVoila promises some great advantages for the future. The concept is illustrated more closely in section 5.13.3. For all those who want to try out and use TemplaVoila now, in its current state, we refer to the very detailed tutorial "Futuristic Template Building".
5.7 Content Rendering Concepts Irrespective of how you have implemented the base layout, there are various possibilities of rendering the content. The rendering methods for displaying content for the front end are not at all restricted to HTML. 279
5 TypoScript
Content can also be displayed as simple text or as XML. But even HTML has been transformed over time, so that XHTML and accessibility are important keywords nowadays. Here TYPO3 offers a number of solutions, and you can develop others yourself. Obviously the base layout must match the format of the content, and where necessary it is omitted (for example with pure text output). For a basic understanding of content rendering we must take a step back at this point. As you already know, TypoScript itself is not a programming language, but merely serves to determine the order of processing of PHP functions to be called, together with their parameters. If you define an object of the TEXT type, the function with (in this case) the same name, TEXT(), in the PHP script tslib/class.tslib_content.php, is called while the TypoScript setup is being processed, and the corresponding output generated. The rendering functions contained in the script were developed at a time when the use of CSS was unthinkable, because browsers could either not support CSS at all or the implementation was so full of errors that it was advisable not to use it. So there has been a certain evolution of rendering concepts in TYPO3, which is not yet complete, and will certainly continue as long as technology in the Web continues to change. The various HTML rendering variations are defined in the following already familiar standard templates: content (default) cSet Stylesheet css_styled_content content (default) is the oldest content rendering template and uses tags for output. The cset stylesheet template represents a
transition to rendering using CSS, which merely redefines the values of content (default) so that, for example, no tags are used anymore. Nevertheless the functions from class.tslib_content.php
are used for rendering, but they frequently use tables for positioning, and other techniques which would be more sensible to do with CSS. For this reason the CSS styled content extension was developed. This also uses the rendering functions from class.tslib_content.php, but does replace a number of functions with its own ones. The development of CSS styled content is not yet finished, but can already be used for your own projects. Apart from the HTML output, TYPO3 offers several other predefined alternative formats that can be used for the following standard templates:
The names already hint at what formats will be created using these templates. Frequently the templates own scripts are used for the output, and hardly any use is made any more of the functions from class.tslib_content.php.
5.8 Switching Templates with type/typeNum It is frequently desirable to create front-end output in several different variations or formats. A common example of this is offering a variation for printing. But it is also possible to offer locally used content via XML feed to other websites. In order that different variations of a page can be used at the same time, TYPO3 provides a system with which several page templates can be defined and one single template chosen for rendering. The following TypoScript template should help to illustrate this concept: temp.content = TEXT temp.content.value = HELLO WORLD! temp.content.wrap = | page = PAGE page.typeNum = 0 page.10 = COA page.10 { 10 = IMAGE 10.file = media/uploads/typo3power1.gif 20 < temp.content } plaintext = PAGE plaintext.typeNum = 99 plaintext.config.disableAllHeaderCode = 1 plaintext.10 = COA plaintext.10.stdWrap.stripHtml = 1 plaintext.10 { 10 < temp.content }
281
5 TypoScript
The content to be displayed (HELLO WOLRD!) is defined with the temp.content object, which is used in the two following page setups page and plaintext to make the content available. As you will see later on, typically styles.content.get is used to retrieve the contents from the database. So in page and plaintext, two templates exist for page output. page defines the normal HTML output and also contains a small base layout, namely the output of the TYPO3 logo before the actual content. In the front end, the following HTML output is generated (abbreviated): test plaintext <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <meta name="generator" content="TYPO3 3.8 CMS" /> HELLO WORLD!
The plaintext template on the other hand should display the same content as normal text without HTML markup. It should be pointed out that TYPO3 offers a better option with the plugin.alt.plaintext (99) standard template for outputting pure text, and that this template is just used here as an example. As you can see, it contains a different base layout (without a logo). Moreover, config.disableAllHeaderCode=1 is set for the PAGE object, which stops the output of the HTML header, and with stdWrap.stripHtml=1 all HTML code is removed from the contents created within the COA object. And this template really does only generate the output HELLO WORLD! But how can the plaintext template be addressed or selected? The key lies in the typeNum values. page.typeNum = 0 plaintext.typeNum = 99
If you call the page in the front end and append the parameter type=99 to the URL (e.g. http://www.example.org/?id=36&type=99), TYPO3 selects the matching template that contains the 99 value in the typeNum
282
5.9 Creating TypoScript Templates
property. In this way, any output variation can be used. The same mechanism is used for frames. This is explained in more depth in section 5.12. The numbers specified in brackets in the plugin.alt.* standard templates are the typeNum values used.
5.9 Creating TypoScript Templates Because the foundations for working with templates and TypoScript have now been laid, we can demonstrate the practical development of site templates below. For this purpose, we will use the BT3 scenario that was already set up in section 3.10. What needs to be done now is to give an appearance in the front end to the applications of the scenario. Because the example contains several sites, we will use this to introduce the various possibilities of template development. A template was supplied by the screen designer as a base layout that already has the basic structure and a number of the functionalities to be integrated.
Figure 5.51: The graphic template
The page has several elements: 1. In the header of the application, a Rootline menu should show the path of the current page from the respective root page. A link calls the print version. 283
5 TypoScript
2. The header shows the logo, replaceable images, depending on the area, and the title of the current page. 3. Below this is a horizontal main navigation. 4. The sub-navigation and meta-menu items (such as "Home", "Print", "Sitemap", and "Contact") are located in a column on the left. 5. The area for the actual page content is placed in the middle and is open-ended at the bottom. 6. Optionally, a number of site areas should show additional information or news in a column on the right. 7. Softlink 821706
A footer with a copyright sign, for example, concludes the application visually.
If you want to work through the examples, you can download the templates and required assets via the softlink, as a TYPO3 document (t3d) and a tar archive, and integrate them into your application. Also have the TSref ready at hand, or open the TS wizard in the back end (see section 5.4.2), with which you can conveniently browse through the object definitions.
Template Structure To be able to show as much as possible in the examples, and also to provide you with material to reconstruct the examples, the individual templates are constructed in a very modular fashion. We have used cascading templates here. Various function components are gradually developed and integrated into parent templates. This enables you to work efficiently and use the templates many times in different examples. The cascading of templates can be done in two ways:
•
Traditionally, further templates are integrated within one template, using Include basis template. This procedure was also used in the standard templates supplied by TYPO3.
•
In addition it is possible to nest templates via page areas, that is, to place a template on a page, thus activating it automatically. This is used either to overwrite values for individual areas of the website or to configure a specific functionality for these areas.
An overview of the templates that are distributed across an application can be obtained from the Rootline (click on the name of your installation next to the globe and select the Web | Template module). If you have reconstructed all the examples, it should look like the following figure. 284
5.9 Creating TypoScript Templates
Figure 5.52: Template overview from the Rootline
We have defined only the Website title in each of the root templates of the site ("Portal", "B2C", "B2B",...), the so-called "main templates" (B2C main template, B2B main template,...). The actual TypoScript configuration and inserting standard templates is done in the respective basis templates. We have also done this on the page level. As can be seen in the above figure, templates are created, for example, in the "Dealers" or "Events" pages of the "B2B" website. These also allow for further configuration, via Include basis template. The individual basis templates used in this chapter are all located in the templates system directory and its subdirectories. This procedure allows you to quickly insert, swap, and test different methods, demonstrated via the template records. The following figure shows an example of cascading templates, starting from the "B2C" site.
285
5 TypoScript
Figure 5.53: Template hierarchy in the Template Analyzer
5.9.1 TypoScript and HTML Templates Softlink 905945
We would like to illustrate the use of HTML files for the base layout, based on the "B2C" site. Integrating external HTML templates into the TypoScript template is a simple and frequently used method. We will explain the following:
•
How the HTML document must be prepared
•
How it is inserted with the TEMPLATE cObject
•
How certain marker areas of the template are addressed
•
How dynamic content is displayed in the front end
•
How to use code libraries
The HTML Template The HTML template can be created with any HTML or text editor. In our first example we will implement the site for the "B2C" area, which is based on 286
5.9 Creating TypoScript Templates
an HTML template. This uses a table layout, is built without frames, and corresponds to the graphic template in Figure 5.51. In doing so, the entire layout of the site, including the function and content areas, will be designed to give the TypoScript developer clear instructions for the implementation. In the next step the areas whose contents or functionalities are to be dynamically replaced by TYPO3 will be defined. This involves menus, buttons, individually changeable texts, and the content area. To identify these areas for TYPO3, special placeholders are required in the HTML template. Two types of placeholders are available for this: subparts and markers.
Subparts •
Subparts are always used in pairs and enclose sections of the HTML template that are completely replaced by the output of the TypoScript configuration.
•
The name of the subpart is enclosed by ###; distinction is made between upper and lower case.
•
Subparts themselves can be surrounded by HTML comments.
•
Before content objects of the individual subparts are generated, all subparts of the array are loaded into the register, so that you can access them if required. Example:
Marker •
Markers are only used singly, not in pairs, and are replaced by the output of the TypoScript configuration.
•
The name of the marker is enclosed by ###, and distinction is made between upper and lower case.
•
Markers cannot be set in HTML comments, since these are not removed. Example: ###COPYRIGHT###
287
5 TypoScript
Preparing the HTML Template Because HTML headers and tags are usually created by TYPO3 from the front end, only the part of the HTML template inside the tags should be used. Subpart markers are inserted into the HTML code for this purpose.
The HTML template should also be prepared in such a way that all image paths refer to the directories in the file system in which they are stored, relative to the root directory. They should also be accessible from the File | Filelist module (e.g. fileadmin/images/...). This means that if you place the HTML file in the root directory of the website and access it, the embedded images must be visible. You can therefore also access clear.gif, which can be found in the root directory.
Figure 5.54: HTML template called via the root directory
Prepared in this way, the HTML draft for the template now appears as follows (abbreviated). Here the contents that should have been substituted have been removed, to make it easier for us to read the document. With the exception of the ###COPYRIGHT### marker, only subparts were used. Untitled rootline Print version Header Main navigation Subnavigation Content
In the following figure you can see the template again in a schematic diagram. This is for a typical layout based on tables, with transparent GIFs (dotted) as placeholders. The areas with subparts are marked with broken lines.
Figure 5.55: Schematic diagram of the areas of the HTML template
290
5.9 Creating TypoScript Templates
In this example, the subparts and markers were set generously, so that only the base layout was left in the core. This creates content areas that can still be structured using TypoScript. This has the advantage that you can change the appearance of individual dynamic areas at any time via TypoScript objects and also—specifically in our case—that code libraries can be used again across various templating methods. The HTML template must now be stored in the file system of the TYPO3 application in a directory beneath fileadmin/.... If it is placed in the root folder, the image references will no longer function; but since the HTML template is displayed with index.php as part of the front-end output in the root directory of the website, the references will work.
Creating the Template Record As already described, we are using cascading templates in the examples, which are inserted by a root template. In the Templates/Main Templates/ system directory, create a new template record, html template, and insert it in the root template for the "B2C Home" page (B2C main template) as the basis template. html template represents the actual definition of the page template and includes the content (default) template as well as individual code libraries as basis templates.
Figure 5.56: Future nesting of the TS templates in the Template Analyzer
In the setup of the html template TS template, the TLO page will be defined as a page by assigning it as the PAGE object type, already demonstrated in section 5.2. The property transferred by this, typeNum, is assigned the value 0. Since our site is not based on frames, this is 291
5 TypoScript
sufficient. page = PAGE page.typeNum = 0
Other properties such as bodyTagMargins and noLinkUnderline specify that the tag generated by TYPO3 is displayed with the parameters leftmargin="0", topmargin="0", marginwidth="0", marginheight="0", and that links created in the content are not underlined. page.bodyTagMargins = 0 page.noLinkUnderline = 0
If you now call a page from the "B2C" site you will see that the TS template functions. Although nothing is yet displayed, the correct parameters have been assigned to the tag in the source text.
cObject Template To now insert the HTML template, the PAGE object type is used to take up content objects in a numerical list (array). page.10=TEMPLATE defines an object of the TEMPLATE object type in the object path page.10. The template property that the object page.10 now has is then defined as an object of the FILE object type, and through the file property, refers to the HTML template in the file system. page.10 = TEMPLATE page.10 { template = FILE template.file = fileadmin/templates/html_template.tmpl }
With this, the HTML template is already displayed in the front end, but the subparts and markers are not yet replaced. It is a good idea to reconstruct the definition of the TEMPLATE object, for example by opening the TS setup with the Web | Template | Info/Modify module and using the TypoScript wizard, described in section 5.4.2, to set the properties for the TEMPLATE object type. There it is also clear that the template property can take in a cObject.
Addressing Subparts and Marks First the area of the HTML template that is to be used for the TYPO3 output is defined. Since TYPO3 creates its own header and tag, this is the subpart ###DOCUMENT_BODY###, set in the HTML template inside the tag. This encloses the area of the template to be interpreted, and whose subparts and marks are to be replaced. It is addressed with the workOnSubpart property and the name of the selected 292
5.9 Creating TypoScript Templates DOCUMENT_BODY subpart as the value. The subparts and marks properties of the page.10 object represent lists of cObjects with the names of
the corresponding subparts and markers. To test if the individual placeholders are correctly addressed, they are defined below as objects of the TEXT type, and each of them is assigned an output text as the value. page.10 = TEMPLATE page.10 { template = FILE template.file = fileadmin/templates/html_template.tmpl workOnSubpart = DOCUMENT_BODY subparts.HEADER_IMAGE = TEXT subparts.HEADER_IMAGE.value = area for header image subparts.ROOTLINE = TEXT subparts.ROOTLINE.value = rootline subparts.PRINTVERSION = TEXT subparts.PRINTVERSION.value = print button subparts.CONTENT = TEXT subparts.CONTENT.value = the content area subparts.NAVIGATION = TEXT subparts.NAVIGATION.value = area for main navigation subparts.LEFT = TEXT subparts.LEFT.value = area for subnavigation and metas (e.g.legal information) marks.COPYRIGHT = TEXT marks.COPYRIGHT.value = footer with copyright }
If a page of the "B2C" site is called now in the front end, it can be seen that all the subparts and marks have been replaced with the corresponding texts.
Figure 5.57: Placeholders of the HTML template have been replaced
293
5 TypoScript
Inserting Dynamic Content Now the content for the respective pages should be displayed, of course. Because content (default) as well as styles.content (default) were inserted as basis templates in the TS template html template, this is simple, because it means that the predefined styles.content.get object is available. Extract from styles.content (default): styles.content.get = CONTENT styles.content.get { table = tt_content select.orderBy = sorting select.where = colPos=0 select.languageField = sys_language_uid }
With the help of the styles.content.get object, the contents of the tt_content table in the Normal (colPos=0) column are queried and rendered with the content (default) standard template, because a corresponding TS setup is defined there for the individual content types. The setup is located under tt_content.*, and due to the identical name, is used automatically by the CONTENT object to render the tt_content table. Now
the styles.content.get object is also copied to page.10.subparts.CONTENT, whereby the contents of the Normal column of the current page are rendered and inserted in the subparts with the name CONTENT. The content to be displayed is put in a table by the wrap property of the CONTENT object type. page.10 { ... subparts.CONTENT < styles.content.get subparts.CONTENT.wrap =
|
... }
Please note that CONTENT in the object path page.10.subparts.CONTENT is only the name for the subpart marker in the HTML template; this does not mean that it is automatically an object of the CONTENT type. But in fact, page.10.subparts.CONTENT is defined as a CONTENT object with a copy of the styles.content.get object. The individual pages of the "B2C" application now reproduce the content of the current page in the front end.
294
5.9 Creating TypoScript Templates
Figure 5.58: Content is displayed dynamically
To format the content output, the cSet (default) and cSet Stylesheet standard templates simplify marking with the Constant Editor. Both bundle individual style definitions from styles.content.default with constants, making global changes easy to carry out. The difference between the two is that cSet (default) performs the markings using traditional HTML formatting, while cSet Stylesheet uses cascading stylesheet definitions that are stored in a separate file. Depending on which method you prefer, the appropriate standard template must be integrated as basis template after content (default) in the html template TS template. We have illustrated both variations in turn. cSet (default) If cSet (default) is inserted, the default values can be changed with the Constant Editor. In the example, standard values of the CSET category such as background color, fonts and sizes for various content elements, and headers are overridden. # adjusted constants of the cSet standard template # (default) cSet.pageColor = white cSet.tableCellColor = #E6B800 cSet.color = #666666 cSet.color1 = #0000CC cSet.color2 = #E6B800 cSet.fontFace = Arial cSet.fontFace.text = Arial cSet.size1 = 1 cSet.size2 = 2 cSet.size3 = 3
295
5 TypoScript
The changes are saved by the Constant Editor in the Constant field of the currently selected template. cSet Stylesheet The standard template access is a stylesheet file supplied by the TYPO3 base installation under media/scripts/defaultstylesheet.css. Copy this file and store it in a directory in the file system under fileadmin/. Then specify the new path in the CONTENT category in the Constant Editor.
Figure 5.59: Inserting the new CSS file
The new value of the constant is written in the Constants field of the TS template: # adjusted constants of the cSet standard template # stylesheet content.stylesheet.file = fileadmin/ defaultstylesheet-modified.css
You can now modify styles in the CSS file, or add new ones. Modifications can be carried out either with a special CSS editor or directly with TYPO3 (File | Filelist).
Stages of Construction with Cascading Templates The TS template now inserts the HTML template and displays the contents maintained by the editors in the back end. However, it still contains several placeholders, which so far only contain text for test purposes. These will be individually replaced with code libraries and inserted as a basis template. The menus will all be discussed together in their own section.
296
5.9 Creating TypoScript Templates
The Image in the Header First an image should be added to the HEADER subpart, which, depending on the area of the page tree, can be specified by the editors through the Files field of the corresponding pages. To do this, a separate temp.header_html TS template is created that defines the temporary object header_image of the IMAGE object type. temp.header_image = IMAGE
In order to specify the location from which the images are to be read, the file.import property determines the directory where the images are stored via the Files field. The file property belongs to the imgResource data type. This in turn is a function containing the import property. temp.header_image.file.import = uploads/media/
The folder where the images are located is now specified, but not where the images are to be displayed. The import property belongs to the path data type, but it has the stdWrap function available, and therefore the data property of the getText data type. This enables values from the data stored internally by TYPO3 (PHP array) to be read out, including those images that are assigned to individual pages. So data = levelmedia:1, slide reads out data of the levelmedia type from the first level in the page tree; the slide parameter has the effect that TYPO3 goes from the current page in the page tree to level 1, until an image is found and displayed. temp.header_image.file.import.data = levelmedia:1, slide
The stdWrap function will be looked at in more detail, but we have seen here how powerful it is, just by reading out data. The important thing at this point is that, if you have worked through the example with us, you will already have an understanding of handling the TSref (see Figure 5.62). You now only need to insert the prepared images into the respective page headers (page type: Advanced) of the first level via the Files field.
Figure 5.60: Image file inserted in the page header
In the html template TS template the temp.header_image object path is passed to the HEADER_IMAGE subpart so that the object just defined can also be used. 297
In the front end, various images, depending on the page area, are now displayed in the header of the application, via the three lines of TypoScript code.
Figure 5.61: Output in the front end
The Text in the Footer In the footer of the application there is editable text reproducing the copyright. A separate TS template is also created here (temp.copyright_html) and inserted as a basis template in the html template template record. marks.COPYRIGHT < temp.copyright_html
The code component temp.copyright_html generates an object with the same name, of the TEXT object type. Its value property is passed a constant as a value, and the output of the object is wrapped with an HTML tag. temp.copyright_html = TEXT temp.copyright_html { value = {$copyright} wrap = | }
Figure 5.63: The html template TS template: only the menus and print function are missing
It is not obligatory to use the copyright constant, but you should be able to change the copyright sign using the value of a constant. The application is extended further in sections 5.10 and 5.11.
5.9.2 The Template Auto-Parser Softlink 543497
300
Use of the Template Auto-Parser is demonstrated in the "B2E" area of the website. It is similar to the integration of HTML templates in the way it is used, except that here the marking of subparts and markers, as well as the resolving of image and resource paths, is taken over by the Template Auto-Parser (automaketemplate) extension. It must already be installed and loaded. You should also install the CSS styled content (css_styled_content) extension, which will be used instead of the content (default) standard template.
5.9 Creating TypoScript Templates
The HTML Template In order to bring some variation into the application, the layout of the HTML template in the "B2E" area is not based on tables, but is marked with the help of tags whose appearance is defined entirely by cascading stylesheets (CSS). 8 These few tags can also be created with TypoScript, as shown in section 5.9.3. The Auto-Parser recognizes areas if it finds the id parameter in HTML elements such as , <span>, and
. The HTML template was prepared accordingly and stored in the file system. If they are included, images, etc. should be stored in subdirectories, relative to their links. The paths to external files such as images do not need to be adjusted in the HTML template.
Configuring the Template Auto-Parser The hierarchy of the template matches that of the "B2C" area. An auto parser template basis template is assigned to a B2E main template root template where the actual page is defined. The latter incorporates the CSS styled content standard template for rendering the contents, via Include static (from extensions). 8 Of course the efficiency of this method only becomes apparent with more complex
HTML templates.
301
5 TypoScript
When you have installed the Template Auto-Parser extension, you will see a new tx_automaketemplate_pi1 object of the USER object type under the TLO plugin.
Figure 5.64: The Template Auto-Parser extension in the Object Browser
Softlink 363442
The Template Auto-Parser can be addressed and configured with this. The possible options can be found in the documentation on the extension (see softlink). Add the following to the setup of the TS template auto parser template: ### Configuration of the auto template parser: plugin.tx_automaketemplate_pi1 { content = FILE content.file = fileadmin/templates/ auto-parser-template.tmpl elements { BODY.all = 1 BODY.all.subpartMarker = DOCUMENT_BODY HEAD.all = 1 HEAD.all.subpartMarker = DOCUMENT_HEADER HEAD.rmTagSections = title DIV.all = 1 } }
###
With the content property you can configure in the Template Auto-Parser which HTML template will be used. It is then instructed, with the elements property, to wrap all HTML tags found of the , , or type with subparts. In all HTML elements of the and type, a subpartMarker (in capitals) is set so that they can be addressed below via the TEMPLATE cObject. Because the title of TYPO3 is generated dynamically, the tag is removed with elements.HEAD.rmTagSections 302
5.9 Creating TypoScript Templates =title. If the relative paths to images and resources of the HTML template are to be adjusted to the TYPO3 environment from the root directory, a prefix to the folder in the file system can be specified. This was not done in the example, because only the CSS file is involved, and the reference already points to the correct directory. #Prefix all relative paths with the value: plugin.tx_automaketemplate_pi1.relPathPrefix =fileadmin/template/
Creating the Page To create the page, the TypoScript code in this case is constructed in more modular fashion, by creating objects in the temp.* object path. The headerTemplate object of the TEMPLATE object type is created to integrate the HTML header data. Its template property is given the plugin.tx_automaketemplate_pi1 object as a reference. The workOnSubpart property specifies that the object only refers to the area of the HTML template that was enclosed by the DOCUMENT_HEADER placeholder. ### cObject for header ### temp.headerTemplate = TEMPLATE temp.headerTemplate { template =< plugin.tx_automaketemplate_pi1 workOnSubpart = DOCUMENT_HEADER }
In the previous example, an HTML file already containing markers was read in by an object of the FILE type, and passed to the TEMPLATE object for processing. Similar things take place with the Template Auto-Parser, with the difference that the plugin.tx_automaketemplate_pi1 plugin sets the markers automatically due to the configuration, also adjusting file references in the process. You can therefore assign an id to the blocks in the HTML file and then access it in the TS setup, without having to insert markers by hand. In the same way the mainTemplate object is now created, except that it refers to the area of the HTML template enclosed by the DOCUMENT_BODY placeholder. Individual subparts are again supplied with output text, for test purposes. The subparts are addressed with the same name (observing upper and lower case) as the ids of the HTML template. ### cObject for body ### temp.mainTemplate = TEMPLATE temp.mainTemplate { template =< plugin.tx_automaketemplate_pi1 workOnSubpart = DOCUMENT_BODY
303
5 TypoScript subparts.rootline = TEXT subparts.rootline.value = rootline subparts.printversion = TEXT subparts.printversion.value = printbutton subparts.header = TEXT subparts.header.value = area for header image subparts.navi = TEXT subparts.navi.value = area for main navigation subparts.subnavigation = TEXT subparts.subnavigation.value = area for subnavigation and metas (e.g.legal information) subparts.content = TEXT subparts.content.value = content area subparts.copyright = TEXT subparts.copyright.value = footer with copyright }
The pages created in the final phase, and the temporary objects are copied to the object path page.headerData.10 and page.10. ## Create page ### page = PAGE page.typeNum = 0 page.noLinkUnderline = 0 page.headerData.10 < temp.headerTemplate page.10 < temp.mainTemplate
The application called in the front end already shows the base layout controlled via CSS, and the corresponding subparts with their test contents.
Figure 5.65: Front-end output in the current stage of construction
If you look at the source code for the front-end output, you will see that the link to the CSS file in the header remains intact, and that a number of placeholders for subparts can still be found.
304
5.9 Creating TypoScript Templates
Figure 5.66: Parts of the output in the source code
If creating subplot markers is only desired for certain ids, you can configure the Template Auto-Parser accordingly. plugin.tx_automaketemplate_pi1.DIV.id { rootline = 1 printversion = 1 ... copyright = 1 }
Stages of Construction with Cascading Templates So far only example text was displayed using this template. Below, TS objects will be developed for specific areas, displaying appropriate content, which can be inserted into the main template.
Displaying Page Content The output of the Normal content column has already been shown with the content (default) standard template (with the predefined styles.content.get object). The CSS styled content standard template used in this template also contains the same object, and can be used accordingly. temp.mainTemplate = TEMPLATE temp.mainTemplate { ... subparts.content < styles.content.get ... }
Creating the Header In contrast to the example in section 5.9.1, the logo is not contained in this HTML template. We now have to define this using TypoScript together with the image in the header. This is why an object is created, of the same name and of the COA object type, in the template you have created yourself, named temp.header_tswrap_autoparser. 305
5 TypoScript
The COA cObject (also called COBJ_ARRAY) can contain several objects in a list. In this way the 10 object generates an image (object type: IMAGE) that is localized in the file system via the file property. temp.header_tswrap_autoparser = COA temp.header_tswrap_autoparser { 10 = IMAGE 10.file = fileadmin/images/layout/logo.gif
The logo should contain a link to the homepage of the website. This can be done with the stdWrap function, which provides the IMAGE object type as a property. It integrates the typolink function, which states (through its parameter property) which data the link should be created from. Here a link is made to the page with the ID 75. 10.stdWrap.typolink.parameter = 75
The parameter property is of the string/stdWrap data type. As an alternative, it is possible to automatically find out the ID of the root page of the website (level=0) with the data property of the stdWrap function. 10.stdWrap.typolink.parameter.data = leveluid:0
The image and the link are then enclosed, by the wrap property of the stdWrap object, with a tag, which deals with the positioning of the logo via CSS. 10.stdWrap.wrap = | 20 is created as the second object of the COA by the already existing temp.header_image object being copied to this object path. temp.header_image originates from the temp.header_html TS template
of the example in section 5.9.1, and is simply re-used. To do this, the template must be included as a basis template in the auto parser template template record. In addition, the desired images must be selected in the corresponding pages of the first level, via the Files field. Since this application is based on CSS, the object is then wrapped with a tag. # simple image, without GIFBUILDER 20 < temp.header_image 20.wrap = | }
306
5.9 Creating TypoScript Templates
The Text in the Footer In order to display the copyright at the bottom of the page, using the temp.copyright_html TS template, you include it as a basis template and copy the object to temp.mainTemplate.subparts.copyright. The only difference is that the text should not be wrapped with a tag. For this reason the wrap property is deleted with the > operator. temp.mainTemplate = TEMPLATE temp.mainTemplate { ... subparts.copyright < temp.copyright_html subparts.copyright.wrap > ... }
The template has now reached the same level of development as the previous example. Creating menus and special functions is described later on. But first we will show you in the next section how base layouts are constructed without external HTML files. If you enjoy working with the Template Auto-Parser, we would once again like to point out to you the very extensive tutorial, "Modern Template Building, Part 1" (see softlink).
5.9.3 Pure TypoScript Templates In the final method for creating TS templates, we will manage without including HTML templates, and create the base layout entirely with TypoScript. We will show you two examples of this, using the layout of the "B2B" application, one with the wrapper concept, with tags, and the other with the CTABLE cObject. The templates are cascaded in the same way as in the "B2C" and "B2E" applications. A basis template, ts wrap template or ts CTABLE template, is assigned to a root template B2B main template. You define the actual page and integrate the content (default) and cSet stylesheet standard templates, as well as other TS code components, according to the level of development.
Working with Wrap If we refer back to the example of the Template Auto-Parser, the HTML template integrated there can also be created entirely with TypoScript. In this way, when parsing the output, no use is made of an external HTML file marked with placeholders. Work replacing subparts and markers is unnecessary, since all HTML markings required are defined in the TS template. 307
5 TypoScript
In the ts wrap template TS template, again make a page TLO of the PAGE object type and specify with the bodytag and stylesheet properties how the tag should appear, and where the CSS file is to be found in the file system. For all contents of the page, create the relevant contents via a numerical list and enclose them with tags through the wrap property. The appearance of the site is also controlled here with cascading stylesheets (CSS). page { 10 = TEXT 10.value = rootline 10.wrap = | .. }
Already
created
and
reusable
code components of the and temp.copyright_html TS templates are included in the template record with the Include basis template field, and its properties are passed on to the respective objects in the numerical list. temp.header_tswrap_autoparser
So far only content of the Normal column was displayed. A second fixed content area is integrated here with the 60 object, which displays the content of the Right column via the predefined styles .content.getRight object of the styles.content (default) standard template. 60 < styles.content.getRight
The 60 object is now of the CONTENT object type. In order to enclose the content with tags, which is done in the output with CSS, the stdWrap function and its wrap property are used. 60.stdWrap.wrap = |
The wrap is set with the stdWrap function, because the following property also needs to be set: 60.stdWrap.required = 1
If the required property is set, stdWrap will only process the other set properties if a value is passed to stdWrap. In this case it means that the wrap is only displayed if the CONTENT object page.60 generates output— that is, if there is content in the right-hand column. In the front-end output, 308
5.9 Creating TypoScript Templates
a framework is only displayed via CSS if content also exists in the Right column. The setup of ts wrap template in its current stage of development: page = PAGE page.typeNum = 0 page.bodyTag = page.stylesheet = fileadmin/styles/ts-template-wrap.css page { # Top ## rootline 10 = TEXT 10.value = rootline 10.wrap = | ## Header 20 < temp.header_tswrap_autoparser 20.wrap = | ## Main Navigation 30 = TEXT 30.value = area for main navigation 30.wrap = | # Left / Submenu 40 = TEXT 40.value = area for subnavigation and metas (e.g. legal information) 40.wrap = | # Content 50 < styles.content.get 50.stdWrap.wrap = | # Right 60 < styles.content.getRight 60.stdWrap.wrap = | # the framework in DIV elements is only displayed if # content exists 60.stdWrap.required = 1 # Printversion 65 = TEXT 65.value = printbutton 65.wrap = | # Footer ## simple placeholder to enable a CSS line break ## (clear: both)
Working with CTABLE Simple table layouts can be created quickly with TypoScript using the CTABLE cObject. This creates a standard table with up to five cells. One cell for the contents (c) can optionally be surrounded by the cells for a left margin (lm) and a right margin (rm) as well as a top (tm) and bottom margin (bm).
Figure 5.67: Table layout with CTABLE
Even though the layout for the example site is not ideal for conversion with CTABLE, since it contains several lines and frames, it can still be managed. In the ts CTABLE template basis template, again define the page TLO with the properties used so far, typeNum, bodyTagMargins and noLinkUnderline. page = PAGE page.typeNum = 0 page.bodyTagMargins = 0 page.noLinkUnderline = 0
In this example we divided up the layout into several objects with the numerical list property of the PAGE objects type. The 2 object should now create a table that positions the Rootline menu and the button for the print version. The CTABLE object type is assigned to it, via which all properties of the cObjects are made available. First additional parameters in the table are set with the tableParams properties, and with offset the distance from the top left corner is set to 0.
The c, lm, rm, tm, and bm properties are of the CARRAY +TDParams data type, that is, they represent a numerical list of cObjects. Your own parameters can be passed to the table cells themselves. The c content cell for the future Rootline menu is now temporarily defined as an object of the TEXT type; a placeholder text is defined with its value property. c.10 = TEXT c.10.value = this creates the Rootline menu
The content of the cell is centered: c.TDParams = valign="middle"
The left cell lm takes in a cObject of the CLEARGIF object type and serves as a utility to fix the table to a height of 32 pixels. # Height of rootline lm.10 = CLEARGIF lm.10.height = 32
A placeholder text is also set for the right column rm, for the link to the print version of the page. rm.10 = TEXT rm.10.value = printbutton rm.TDParams = valign="middle" align="right" }
The objects page.10, page.20, page.30, and page.40 are defined as further tables. The contents cell page.10.c will display the logo and area image in the header of the page, and consists of several objects in the form of a numerical list (COA). ###### header ###### page.10 = CTABLE page.10 { tableParams = border="0" cellpadding="0" cellspacing="0" width="785" offset = 15,0 # Logo c.10 = COA # Positioning table for logo and Header_Image c.10.5 = HTML c.10.5.value =
5.9 Creating TypoScript Templates c.20.value = area for main navigation c.TDParams = align="left" valign="middle" bgcolor="#FFFFFF" height="40" c.30 = HTML c.30.value =
}
Table page.30 positions the submenu and the content area via page.30.lm and page.30.c. They are encompassed by the HTML objects page.25, which displays the gray line on the left-hand page, and page.35. ###### Subnavigation and Content ###### #Framing table for left and right lines page.25 = HTML page.25.value =
# space so that the cell is also included if content # is missing c.10.stdWrap.ifEmpty = # offset to copyright sign c.20 = HTML c.20.value =
c.TDParams = align="right" valign="top" lm.10 = TEXT lm.10.value = area for subnavigation and meta-information (imprimatur, etc.) # height, so that the content is at least 400 pix # high, even if content is missing. lm.TDParams = width="197" align="left"
313
5 TypoScript valign="top" height="400" } # end of framing table page.35 = HTML page.35.value =
The footer of the output with the copyright is created by the page.40 table object. ###### Copyright ###### page.40 = CTABLE page.40 { tableParams = border="0" cellpadding="0" cellspacing="0" width="785" offset = 15,0 c.10 < temp.copyright_html c.TDParams = align="right" valign="middle" bgcolor="#FFFFFF" height="18" tm.10 = IMAGE tm.10.file = fileadmin/images/layout/1px_gray.gif tm.TDParams = align="left" valign="top" bgcolor="#CCCCCC" height="1" width="785" bm.10 = CLEARGIF bm.10.height = 30 }
You can see that the listing has become quite large, and that CTABLE is better suited, for a simpler layout, to create this clearly using a table. All template methods have now been introduced, and which one you will use to design your application depends on your preferences and skills. In the next section, menus will be introduced that automatically display the current page tree as a means of navigation.
5.10 Menus Menus handle not only the navigation concept in your website, but also provide important design elements. With TYPO3, many different types of menus can be created. Functionalities for creating menus based on text, graphics, layers, an imagemap, or selection menus are already included, and can be addressed via TypoScript, where various logical menu structures are possible. In the front end, menus are created dynamically via the hierarchy of pages in the page tree. If you create a new page in the back end, for example, it 314
5.10 Menus
is automatically shown in the relevant menu once it is released. Inside menus, the page types Standard, Advanced, External URL, Shortcut, and Mount Point are generally displayed, provided no restrictions are set by TypoScript. The Spacer placeholder must be defined separately for it to be displayed. The page types Not in Menu, SysFolder, and Recycler are not included.
Level Because normally only a sitemap displays all the pages of a website, a definition must be made in most menus as to what page the menu is to start on and where it is to finish. One way of defining this exists in the socalled levels. The Rootline of the website, as the first level, corresponds to level 0, the next level to level 1, and so on.
Figure 5.68: Levels in the page tree
The Rootline An important concept frequently used in the context of menus in TYPO3 is Rootline. The term is also used to name the lowest level in the page tree. You can display standard templates, for example, in the Web | List module, by selecting the Rootline (globe). Rather confusingly, this term has another meaning for menus. Here the Rootline is a list of pages, obtained by moving down to the root page, starting from the current page. In Figure 5.68, the Rootline of the "Product 2" page would be: Product 2, Products, B2C Home. We will show below how our various menu types are configured with TypoScript. Inside the BT3 example application, they are saved as individual template records in the Templates/Main Templates/Menus/ SysFolder. For display in the individual websites, "B2C", "B2B", and "B2E", the desired menus are included in the respective main template as basis 315
5 TypoScript
templates. The existing placeholder texts in the main templates are replaced by the corresponding objects. Example: in the "B2C" website, the main template html template defines the page. In the template record here, integrate the menu you have created, with Include basis template. Into the page.10.subparts.NAVIGATION object path, which until now showed a placeholder text, page.10 { ... subparts.NAVIGATION = TEXT subparts.NAVIGATION.value = area for main navigation ... }
the menu object is now copied. Be careful that it is the object of the menu that is copied, and not the template record, which usually has the same name in the examples. ... subparts.NAVIGATION < temp.navigation_html ...
The menu would now already be visible on the website. But first it must be created.
5.10.1 cObject HMENU—Common Properties of Menus Softlink 460074
Whatever menu you want to show on your website, they are all created with the HMENU (hierarchical menu) cObject. Here is a simple example creating a menu for the pages of level 0, in which the entries are shown beneath each other, because in each menu item a wrap is used with a tag. temp.navigation = HMENU temp.navigation.entryLevel = 0 temp.navigation { 1 = TMENU 1.NO.allWrap = | } HMENU takes on the task of gathering the page information. The actual
rendering of the menu entries is performed by subobjects, which are included in a numerical list. In contrast to the PAGE or COA object type, the numbering has a special significance. The properties 1, 2, 3, etc. stand for 316
5.10 Menus
the corresponding levels. The entryLevel property specifies the level in the page tree, seen from the Rootline, from which you start counting the levels for the menu. The above TS setup will therefore create a menu with one level of depth, starting from level 0. In the example, by the way, a menu object that creates simple text links is used in TMENU. As already mentioned, other menu types are also supported by TYPO3. temp.navigation.1 = TMENU # the second level of the menu is a graphical menu temp.navigation.2 = GMENU
The following menu types are available in TYPO3: TMENU Displays a text-based menu. GMENU GMENU stands for "graphical menu". Images are generated automatically from individual page titles.
GMENU_LAYERS/TMENU_LAYERS GMENU_LAYERS and TMENU_LAYERS add further properties to the corresponding GMENU or TMENU menu object and display it with
DHTML layers. Because of different interpretations of the standards by various browser versions, the menu objects cannot be used for older browsers, and can only be used to a limited extent for new ones. GMENU_FOLDOUT GMENU_FOLDOUT extends the GMENU menu object. It creates a menu for two levels, which folds out or back in without the page having to be reloaded.
IMGMENU The IMGMENU menu object creates an ImageMap. JSMENU JSMENU creates a classical foldout menu.
Apart from the entryLevel property, HMENU has several other properties that control menu output. The number of menu entries can be specified with the minItems and maxItems properties, for example, and with begin you can define the first menu entry. With excludeUidList, you can also exclude certain pages from inclusion in the menu. 317
5 TypoScript special is a powerful property that helps you define menus with a different structure from the page tree. Menus can be created that display the Rootline, show pages with specific keywords, or list subpages from selected pages. All possible options are discussed in section 5.10.8. Softlink 401761
The menu objects themselves (TMENU, GMENU,...) have a number of states in common, but also have their own specific ones. They all have the addParams state for example, which passes on further links to the menu link.
Softlink 478459
With the exception of JSMENU, the other menu objects of the series TMENU, GMENU, and IMGMENU also share states that accept menu items. NO (normal) represents the normal case, which always has to be defined as the default configuration. All other states must be activated if they are to be used, and their behavior must be defined individually. NO The menu item in the normal NO state. The definition is obligatory. IFSUB The IFSUB status is active if the menu item has subpages. ACT The menu item has the ACT status if it is located in the Rootline of the current page. ACTIFSUB If the menu item is located in the Rootline of the current page, and if it has subpages to be displayed in a menu, then it has the status ACTIFSUB. CUR The current page has the status CUR. USR The status USR applies to pages for which access is restricted by front-end user groups. It overrides the states IFSUB, ACT, and CUR. SPC The SPC status applies specifically to the Spacer page type and is used especially for the structuring of menus. SPC has no rollover functionalities, since it is not linked.
318
5.10 Menus
USERDEF1 The states USERDEF1 and USERDEF2 can be defined in a separate script (see the properties HMENU/special = userdefined or .itemArrayProcFunc). USERDEF2 See USERDEF1. [RO] With this, a variation for mouse rollovers can be created for a menu item. The RO status is not available for many objects, and must be added to the reference for the respective object. Individual menu items are introduced below, using the example application. Only some of the available properties will be used. Consult the TSref to obtain an overview of all the other properties.
5.10.2 Text Menus (TMENU) TMENU creates a text-based menu from the page or navigation title of the
Softlink 623534
page header. The titles are automatically linked. The appearance is configured by you. The advantage of text-based menus is mainly their fast loading times. We would like to point out a special feature concerning the TMENU menu object: the properties before and after have the same properties as stdWrap. But the field property above it is not directly available. This is due to an error in the design, which has been left in for the sake of backward compatibility in TYPO3. For this reason, you should avoid it and use the data property instead (e.g. before.data=page:title).
Example: "B2C" Main Navigation For the "B2C" site, a TS template with the name temp.navigation _html is created for the main horizontal navigation, and uses the TMENU menu type. The states of the menu items are shown by font colors and various icons in front of the title. The front-end output of the figure shows the active "home" page and the rollover, via the "events" menu item.
319
5 TypoScript Figure 5.69: The main navigation as a TMENU for one level
The menu is defined using the HMENU cObject and entryLevel=0 property. temp.navigation_html = HMENU temp.navigation_html.entryLevel = 0
The object path temp.navigation_html.1 is assigned the TMENU menu type. temp.navigation_html.1 = TMENU
First the behavior of the NO status is specified. ATagBeforeWrap defines that the link will be placed around the wraps; linkWrap encloses the text with the tag, including the CSS class. With the case=lower property of the stdWrap function, the text is displayed in lower-case. An image is placed in front of each link with beforeImg. If it should also be linked, beforeImgLink=1 must be set. For the TMENU, a rollover state is activated with RO=1 and the accompanying image is replaced through the beforeROImg property. temp.navigation_html.1 { NO { ATagBeforeWrap = 1 linkWrap = | stdWrap.case = lower beforeImg = fileadmin/images/icons/navi_no.gif beforeROImg = fileadmin/images/icons/navi_ro.gif RO = 1 }
The behavior of the menu items in the ACT state (which means that they are located in the Rootline of the active page) is ascertained by copying from the NO object. Only the linkWrap and beforeImg properties are overwritten, to give them a different color value or a different CSS class and another image for the active state, via the wrap. The state must be activated via ACT = 1. ACT < .NO ACT { linkWrap = | beforeImg = fileadmin/images/icons/navi_act.gif } ACT = 1 }
320
5.10 Menus
Integrate the TS template and temporary object in the main template of the "B2C" site, and inspect the output in the front end.
Example: "B2B/B2E" Main Navigation The "B2B" and "B2E" sites are based on tags, the layout of which is controlled entirely by cascading stylesheets. They are particularly suitable for accessibility websites. In accordance with this, the main navigation for the two sites is created with the temp.navigation_autoparser_tswrap TS template. Instead of the tags, each menu item is wrapped as a list entry with wrapItemAndSub=
|
. The whole menu is enclosed by the HTML tag for lists, wrap=
|
. The rest of the procedure is the same as the "B2C" main navigation. The properties of the NO state are passed on by copying to the ACT state, and just one CSS class is set for the link, using parameters (ATagParams=). temp.navigation_autoparser_tswrap = HMENU temp.navigation_autoparser_tswrap.1 = TMENU temp.navigation_autoparser_tswrap.1 { wrap =
Now you just need to define the appearance of the menu via the CSS file included in the main template. Open the corresponding file with the File | Filelist module and edit the required styles. ul { margin: 0; padding: 0; } #navi li, #rootline li { display: inline; margin: 3px; } #navi a:link, #navi a:visited { padding: 0 5px 0 10px; background: url(../images/icons/left.gif) no-repeat left; text-decoration: none; color: #666; } ...
321
5 TypoScript
The output in the front end is the same as that for the "B2C" application.
Example: "B2C" Subnavigation A TMENU is implemented in the temp.navigation_html template for the subnavigation. The respective menu items in the first and second levels are arranged via a table layout and separated by various separating lines. The active state of the first level is made clear by writing the page title in capitals. For the second level, small icons are displayed in front of the titles. In the front end, the subnavigation for two levels and rollover appears as in Figure 5.70.
Figure 5.70: Subnavigation as a TMENU for two levels
The subnavigation is to start at level 1, which is achieved with entryLevel=1. temp.subnavigation_html = HMENU temp.subnavigation_html.entryLevel = 1
The meta-pages "home", "print", "sitemap", and "contact" in the Functions SysFolder can be excluded from display by giving the excludeUidList property a corresponding list of page IDs. However, it is better to simply set up the pages as Not in menu type. temp.subnavigation_html.excludeUidList = 122,121,120,119
Level 1 of the menu is defined as TMENU. temp.subnavigation_html.1 = TMENU
The level is wrapped with a three-column table that defines the format. temp.subnavigation_html.1.wrap =
|
The NO and ACT states are configured so that each menu item is displayed, via the allWrap property, as a separate table row and with the separating line as an image. With the wrapItemAndSub property, the submenu items of level 2 would also be included, but this is not wanted. temp.subnavigation_html.1 { NO { linkWrap = | stdWrap.case = lower allWrap =
The second level of the menu is also defined as TMENU. The menu items of the second level are given their own icons and enclosed by an HTML layout with the allWrap property. temp.subnavigation_html.2 = TMENU temp.subnavigation_html.2 { NO { linkWrap = | stdWrap.case = lower allWrap =
Include the TS template in the main template of the "B2C" site and again inspect the result in the front end.
5.10.3 Graphical menus (GMENU) Softlink 193130
GMENU is similar to TMENU in the way it functions, except that it creates a linked image from every page or navigation title, via the internal TYPO3 function of the GIFBUILDER. This structural freedom increases the loading times of the application, however, since all menu items and their states must be included as images.
Example: "B2C" Subnavigation As the second variation, a simple graphical menu is created with the temp.subnavigation_html_gmenu TS template, for the subnavigation of the "B2C" site. The first level arranges the menu items aligned to the left and places two lines around them. The second level is aligned to the right and marked with a line on the right border. The active pages are highlighted in color (see Figure 5.71).
Figure 5.71: Subnavigation as a GMENU for two levels
Create the HMENU cObject with entryLevel=1 and define the first level of the menu as GMENU. temp.subnavigation_html_gmenu = HMENU temp.subnavigation_html_gmenu.entryLevel = 1 temp.subnavigation_html_gmenu.1 = GMENU
First the properties of the NO object are specified; in GMENU objects, this is, by definition, of the GIFBUILDER type. temp.subnavigation_html_gmenu.1 { NO {
324
5.10 Menus
Each menu item is wrapped with a tag. The size of the image, XY=150,40, and the background color, backColor=white, are defined by the properties of the GIFBUILDER function.
Softlink 023806
wrap = | XY = 150,40 backColor = white
Individual objects of the GIFBUILDER are created via a numerical list, each item of which is defined as the GifBuilderObj type. So the menu item of the first level consists of several objects. The 7 and 8 objects each create a GifBuilderObj of the BOX type, which overlap because of the hierarchy. # gray box 7 = BOX 7.dimensions = 16,18,120,20 7.color = #DFDFDF # white box 8 = BOX 8.dimensions = 16,18,119,19 8.color = #FFFFFF
Because the dimensions properties differ by one pixel, you just see a gray line in the horizontal and vertical planes. The 10 object is a GifBuilderObj of the TEXT type and contains the stdWrap data type. This is used to read the page title to be displayed, with 10.text.field=title. The fontFile property points to the TrueType character set to be used for creating the images, and which needs to be loaded into the file system beforehand, under fileadmin/.... Font size and color are defined via the fontSize and fontColor properties, spacing is defined with x/y coordinates, and text alignment, with offset and align. 10 = TEXT 10.text.field = title 10.fontFile = fileadmin/fonts/VERDANAB.TTF 10.fontSize = 11 10.fontColor = #FFFFFF 10.offset = 30,31 10.align = left
The niceText property, which displays smaller letters more clearly, does not always work as intended, depending on the ImageMagick version included, and makes demands on server resources to create the images. #10.niceText = 1
With the GifBuilderObj of the SHADOW type, a shadow is created, whose position can be set with the coordinates of the offset property, and its 325
5 TypoScript
focus and transparency can be defined with blur and opacity. # shadow for the text 10.shadow.offset = 1,1 10.shadow.blur = 80 10.shadow.opacity = 40
The GifBuilderObj TEXT does not have any bold property, but you can simulate this by passing on the text a second time (20 the font gets clearer 20 < .10 }
Another possibility, which usually looks better, consists of including a real bold font (10.fontFile=fileadmin/fonts/VERDANAB.TTF). For the RO=1 (rollover) state for menu items, only the font color is replaced. RO < .NO RO { 10.fontColor = #FFCC66 20 > 20 < .10 } RO = 1
The menu item with an active state, ACT is stored with another GifBuilderObj BOX. ACT < .RO ACT { # shadow 5 = BOX 5.dimensions = 18,20,120,20 5.color = #D3D3D3 } ACT = 1 }
Level 2 of the menu for the second level first takes on all the properties of level 1, by copying them. temp.subnavigation_html_gmenu.2 = GMENU temp.subnavigation_html_gmenu.2 < temp.subnavigation_html_gmenu.1 temp.subnavigation_html_gmenu.2 { NO {
The size of the image to be created is overwritten. XY = 150,24
326
5.10 Menus
The 7 and 8 properties (gray and white box) are deleted. 7 > 8 >
A new GifBuilderObj of the BOX type is created as an 8 object, with a width of 1 pixel and a height of 24 pixels. # right line 8 = BOX 8.dimensions = 136,0,1,24 8.color = #DFDFDF
Several properties are overwritten in the GifBuilderObj 10 of the TEXT type. 10.offset = -25,16 10.fontSize = 10 10.align = right 20 < .10 }
The RO state of Level 2 takes over the properties of the NO object and only overwrites the font color. RO > RO < .NO RO { 10.fontColor = #FFCC66 20 > 20 < .10 } RO = 1
The active ACT state takes over all properties of the RO object. ACT < .RO ACT = 1 }
The menu is now finished. Integrate the TS template and the temporary object in the main template and check the result in the front end.
5.10.4 Layer-Based Menus (TMENU_LAYERS / GMENU_LAYERS) The TMENU_LAYERS and GMENU_LAYERS menu objects function on top of TMENU or GMENU and extend their properties. Both create a navigation for several levels, via DHTML layers and JavaScript. For this, you must integrate their functionalities with media/scripts/tmenu_layers.php
Softlink 620108
327
5 TypoScript
script and/or media/scripts/gmenu_layers.php. When selecting the menu, bear in mind the issue of browser compatibility. Older browsers in particular do not support the latest versions of the W3C Document Object Model (DOM), or only support it to a limited extent. Softlink 599829
Up-to-date browsers such as Opera 7 do support more recent versions of the DOM. If you want to use TMENU_LAYERS, it is advisable to modify the corresponding JavaScript functions in the file /media/scripts/ jsfunc.layermenu.js (see softlink).
Example: "B2C" Main Navigation For the main navigation of the "B2C" site, a graphical layer menu is created in the temp.navigation_html_gmenu_layers TS template. If you roll over the menu items of the first level, the selection of the subpages in a layer should be visible. It remains there if a page of the second level is active. The icons in front of the menu items and the font color change on rollover and in an active state. The result can be seen in the following figure.
Figure 5.72: Main navigation as GMENU_LAYERS
First integrate the functional library, gmenu_layers.php, and create a hierarchical menu as a temporary object (HMENU). The first level will be defined as the GMENU_LAYERS menu object. includeLibs.gmenu_layers = media/scripts/gmenu_layers.php temp.navigation_html_gmenu_layers = HMENU temp.navigation_html_gmenu_layers.1 = GMENU_LAYERS
After this the behavior of the layer is determined. With the layerStyle property, the CSS attributes are assigned to the tag used. In this case the y-position is fixed to 195 pixel. With lockPosition the layers are locked in place, and do not follow the mouse pointer. Select x for horizontal and y for vertical menus. xPosOffset defines the offset of the layer from the menu item on the x-axis. The property refers—depending on whether lockPosition is set or not—either to the top left corner of each menu image or to the position from which it was activated. 328
The expAll=1 property of the GMENU menu object should be set in all cases, so that the second level can also be seen on rollover. Otherwise the layer navigation will not work. expAll = 1
With the displayActiveOnLoad property you can ensure that the layer menu remains visible, even for an active page in the second level. displayActiveOnLoad = 1
Now level 1 of the menu is defined, as already demonstrated in the example of the graphical subnavigation for the "B2C" site, as GMENU. First, we set the normal state NO: NO { backColor = white
The size of individual menu items is automatically calculated, in this case, with the GIFBUILDER property XY, from the length of the images in the GifBuilderObj array. The x,y +calc data allows this access, and sets the values for X to [10.w]+40 pixels and for Y to 30 pixels. [10.w] stands for the width w of object 10 in the numerical list, to which 40 pixels are added. The height of the object could be addressed via [10.h]. XY = [10.w]+40, 30
The other properties are already known. Two overlying GifBuilderObjs 5 and 7 of the BOX type are created. The 10 object reads out the title of the page and formats it. 5 = BOX 5.dimensions = 2,15,5,1 5.color = #666666 7 = BOX 7.dimensions = 4,13,1,5 7.color = #666666 10 = TEXT 10.text.field = title 10.text.case = lower 10.offset = 14,18 10.fontFile = fileadmin/fonts/ARIAL.TTF 10.fontSize = 12
329
5 TypoScript 10.fontColor = #666666 }
The RO state for the rollover is activated, the properties of the NO object are taken over, and a few color values are overwritten. RO < .NO RO { 5.color = #E6B800 7.color = #E6B800 10.fontColor = #E6B800 } RO = 1
The active state of the menu items should display a yellow frame around a minus sign. To do this, two overlaying squares (yellow and white) are added as new GifBuilderObjs 1 and 3 of the BOX type to the numerical list, and the 7 object is deleted (plus becomes minus). ACT < .NO ACT { # box around the sign: yellow or white square 1 = BOX 1.dimensions = 0,11,9,9 1.color = #E6B800 3 = BOX 3.dimensions = 1,12,7,7 3.color = white # no | 7 > } ACT = 1 }
The second level of the menu shows the individual menu items as a GMENU in the layer. It does not hide any new properties and is used here just for purposes of practice. temp.navigation_html_gmenu_layers.2 = GMENU temp.navigation_html_gmenu_layers.2.wrap = | temp.navigation_html_gmenu_layers.2 { NO { backColor = white XY = 120, 19 # left and bottom line 5 = BOX 5.dimensions = 0,0,1,19 5.color = #CCCCCC 7 = BOX 7.dimensions = 0,18,120,1
Observe the menu in the front end, expand the individual submenus on rollover, and keep them open for active subpages.
5.10.5 GMENU_FOLDOUT The GMENU_FOLDOUT menu object is restricted to two levels and generates a navigation that opens dynamically, via JavaScript. For the first menu level you must use a graphical menu, while for the second level you can choose between a graphical and a text-based menu. The functionality is integrated with the script media/scripts/gmenu_foldout.php. Do not forget the restricted compatibility for older browsers when using this type of navigation.
Softlink 623360
Example: "B2C" Subnavigation As an example, the subnavigation of the "B2C" site is examined, which so far has been implemented as a TMENU. Create a new TS template, temp.subnavigation_html_gmenu_foldout. This should result in individual submenu items in the first level opening when clicked on. The layout is the same as that for the text menu, and appears as shown in the following figure.
331
5 TypoScript
Figure 5.73: Subnavigation as a GMENU_FOLDOUT for two levels
The two levels of the menu are implemented with the GMENU menu object. First you should integrate the required function library, gmenu_foldout.php via includeLibs. includeLibs.gmenu_foldout = media/scripts/gmenu_foldout.php
Define a temporary object as a cObject of the HMENU type. With entryLevel=1, the menu starts in the first level of the website. For the first level, the GMENU_FOLDOUT menu object is defined. temp.subnavigation_html_gmenu_foldout = HMENU temp.subnavigation_html_gmenu_foldout.entryLevel = 1 temp.subnavigation_html_gmenu_foldout.1 = GMENU_FOLDOUT
In order for the subpages in the second level to be shown always, you need to activate the expAll property of the menu object. menuOffset positions the first menu level to the top left corner of the page. With the subMenuOffset property, the offset of the subitems to the respective main menu item is defined. The background color is defined with the menuBackColor property, and width and height with menuWidth and menuHeight respectively. temp.subnavigation_html_gmenu_foldout.1 { expAll = 1 menuOffset = 17, 202 subMenuOffset = 14,25 menuBackColor = white menuWidth = 164 menuHeight = 800
If you want the submenu to close when another main menu item is called, stayFolded=0 should be set. The speed with which the submenu opens dynamically can be defined via the number of steps; foldSpeed=1 immediately shows the final state. With displayActiveOnLoad=1, submenus are opened automatically if the current page is located in this submenu. 332
The normal state NO for the first level is defined. The background color and size for it are specified. NO { backColor = #FFFFFF XY = 164, 22
The 3 object of the numerical list inserts an image as a GifBuilderObj IMAGE, which visually highlights the individual menu items. 3 = IMAGE 3.file = fileadmin/images/layout/subnavi1_line.gif 3.offset = 3
The 10 object reads out the title of the page and formats it. 10 = TEXT 10.text.field = title 10.text.case = lower 10.offset = 29,15 10.fontColor = #666666 10.fontFile = fileadmin/fonts/ARIAL.TTF 10.fontSize = 11 }
The active state ACT again takes over the properties of the NO object, and only changes the details insofar that the page title is displayed in capitals (case=upper). ACT < .NO ACT { 10.text.case = upper } ACT = 1 }
In the same way the second level of the temp.subnavigation _html_gmenu_foldout.2 menu is defined. Here, in contrast to level 1, you have a choice between a TMENU and a GMENU. The GMENU was used in the example, and its RO and ACT states are marked with separate icons. temp.subnavigation_html_gmenu_foldout.2 = GMENU temp.subnavigation_html_gmenu_foldout.2 { NO { XY = 150,18 backColor = white 3 = IMAGE 3.file = fileadmin/images/layout/subnavi2_line.gif
Insert the TS template and the temporary object into the main template of the "B2C" site and check the output in the front end. It can be a bit annoying that the pages are reloaded through the call each time the submenu opens. You can avoid this by creating pages in the first level of your application that also have subpages, such as the Shortcut page type, without their own contents. The dontLinkIfSubmenu property causes the second level of the menu to be opened if it has subpages, but not to be linked. The loading process is omitted. ... dontLinkIfSubmenu = 1
Pages without subpages are linked as normal.
5.10.6 ImageMaps (IMGMENU) Softlink 610406
334
The IMGMENU menu object generates an image with an imagemap from the background image and the page title of a menu level to be displayed. For individual menu items, sensitive areas are set with <area> tags, creating links to the individual pages. The menu items consist of GIFBUILDER objects that can be structured as you like. For the individual states, NO, ACT, SPC, etc., GIFBUILDER creates separate images in each case.
5.10 Menus
Example: "B2C" Main Navigation For the "B2C" site, any variation of the main navigation will be implemented with the IMGMENU menu object, via a new temp.navigation_imgmenu TS template. The following output should be generated in the front end.
Figure 5.74: Main navigation as an IMGMENU
The menu represents the main navigation, which is why it starts in the Rootlevel: entryLevel=0. The maxItems property specifies that up to six menu items can be shown. temp.topmenu = HMENU temp.topmenu.entryLevel = 0 temp.topmenu.maxItems = 6
The menu only has one level, defined as IMGMEMU. The background image on which the title is displayed is specified with the main property of the GIFBUILDER data type. As has already been shown, the individual objects of the GIFBUILDER are generated as a numerical list, to each of which a GifBuilderObj is assigned as the data type. With the 10 object, a GifBuilderObj of the IMAGE type is now created, which links to the desired base image with the file property.
The original size of the image is ascertained through the XY properties, and with reduceColors, the color palette of the image is scaled down to 16 colors, thus reducing the file size. main.XY = [10.w], [10.h] main.reduceColors = 16
You define the starting point of the menu from the top left corner of the image, with dWorkArea. dWorkArea = 12,22
The normal state of the menu is defined. The distrib property specifies the distance between menu items. The 10 object in the list reads out the title of the page as a TEXT GifBuilderObj and defines its display. 335
5 TypoScript NO { distrib = textX+25, 0 10 = TEXT 10.text.field = title 10.fontSize = 12 10.fontColor = #666666 10.fontFile = fileadmin/fonts/ARIAL.TTF 10.niceText = 1 10.offset = 2,0
With imgMap, you can access a property of the GIFBUILDER that enables an image map for the image file to be created from the TEXT GifBuilderObj. The explode property enlarges the sensitive area by the x/y-coordinates. 10.imgMap.explode = 3,2
The plus sign before each menu item is implemented via two GifBuilderObjs of the BOX type. # | 20 = BOX 20.dimensions = -5,-6,1,5 20.color = #666666 # 30 = BOX 30.dimensions = -7,-4,5,1 30.color = #666666 }
The active state ACT takes over all the properties of the NO object. Object 20 in the numerical list is deleted (plus becomes minus), and a border is created with the objects 40, 50, 60, and 70. ACT < .NO ACT { 20 > #- below 40 = BOX 40.dimensions = -9,0,9,1 40.color = #666666 # - above 50 < .40 50.dimensions = -9,-8,9,1 # | left 60 < .40 60.dimensions = -9,-8,1,9 # | right 70 < .40 70.dimensions = -1,-8,1,9 } ACT = 1 }
336
5.10 Menus
The menu is finished. Integrate the temp.navigation_imgmenu TS template and the temp.topmenu temporary object in the main template and test the output in the front end.
5.10.7 JavaScript Menus (JSMENU) The JSMENU menu element sets up a navigation in which pages are selected through selection menus that are dependent on each other. Each selection menu represents a website level. The most important feature of this menu, compared to a simple selection menu, is that the lower levels are filled with corresponding entries that depend on the higher level currently selected, without the page having to be reloaded in the browser. A JSMENU can show up to five levels (five selection menus).
Softlink 421175
Example: "B2B" Main Navigation In this example, a variation is created for the main navigation of the "B2B" site with the temp.navigation_tswrap_jsmenu TS template. The following figure shows the finished menu when the "Product 1" subpage is selected.
Figure 5.75: The main menu as a JSMENU
Define the temporary object temp.jsmenu_tswrap as an HMENU cObject and define the first menu level as a JSMENU. temp.jsmenu_tswrap = HMENU temp.jsmenu_tswrap.1 = JSMENU
The number of levels to be displayed is defined with the levels=2 property. temp.jsmenu_tswrap.1 { levels = 2
With the numerical list you define the behavior of individual levels. For level 1 the selector box is distinguished from the following selector boxes using a wrap with an empty space. If you want to select the active page in advance, then set the value showActive=1. If no page is selected, then 337
5 TypoScript
the first selector box normally has no value. A label can be given to the respective selection menu with the firstLabel property. 1 { wrap = | showActive = 1 firstLabel = Menu: }
The values of the first level are passed on to the second one, and only the label is overwritten. 2 < .1 2.firstLabel = Submenu: }
The menu is finished, and you can include it in the main template of the "B2B" site.
5.10.8 ".special" Menus Softlink 743914
The HMENU cObject by default displays the page structure as a tree, but can be made to generate other structures with the special property. A socalled Rootline menu, for example, shows the pages of the Rootline. A simple setup will look like this: temp.navigation = HMENU temp.navigation.entryLevel = 0 temp.navigation.special = rootline temp.navigation { 1 = TMENU 1.NO.allWrap = |/ }
This produces the following output: B2C-Home/ Products/ Product 2/
The special property determines what special structure the HMENU should create. The following types are available. The properties for each of the menu types can be taken from the TSref. directory The directory type generates a menu from the subpages of the specified page IDs or from the current page. list With list you can create a menu for specific pages, determined by their IDs. 338
5.10 Menus
updated If you want to show pages depending on whether they have been updated or not, you can do this with updated. rootline The path from the root page to the currently active page normally helps the user to retain an overview of complex applications. This rootline menu is generated through the rootline type. browse The browse type allows you to browse through pages in different ways (previous, next,...). keywords The keywords type creates a menu of pages that match the current page with one or more keywords in the page header. This makes it easy to show related pages. userdefined With the userdefined type you can also control menus with your own PHP script. The TSref contains a detailed example of this.
Example: Directory Almost every application has pages that are not meant to be shown in the context of the main navigation. In the "BT3" example application, this applies to the meta-menu items "Home", "Imprint", "Sitemap", and "Contact". They should always be present, and they are stored here in the Functions SysFolder for the page tree. Here the directory menu type can be used for the display. The menu should be structured as shown in the following diagram, and be placed beneath the subnavigation on the left-hand page.
Figure 5.76: Meta-information, created with the special.directory property
Create your own temp.metas_html TS template for the "B2C" site and define an HMENU as a temporary object. The special property is assigned the desired menu type with the directory value. The value property 339
5 TypoScript
defines the page IDs to which the menu refers. Because the value refers to the page IDs of the Functions SysFolder, a constant was set as the value, which you have to define accordingly for your application. temp.metas_html = HMENU temp.metas_html.special = directory temp.metas_html.special.value = {$metas.pid}
The menu itself can be configured as you please, and in the example is configured as a TMENU. It is formatted by a table. temp.metas_html.1 = TMENU temp.metas_html.1 { wrap =
|
NO { linkWrap = allWrap =
|
ATagBeforeWrap = 1
Individual images in front of the pages are read out via import.field=media (the files field in the page header of the corresponding pages). # get the image from the page (files field in # pages of the type advanced) beforeImg.import = uploads/media/ beforeImg.import.field = media beforeImg.import.listNum = 0 } }
For the "B2B" and "B2C" sites based on tags, the following variation is produced with the temp.metas_autoparser_tswrap TS template: temp.metas_autoparser_tswrap = HMENU temp.metas_autoparser_tswrap.special = directory temp.metas_autoparser_tswrap.special.value = {$metas.pid} temp.metas_autoparser_tswrap.1 = TMENU temp.metas_autoparser_tswrap.1 { noBlur = 1 wrap =
|
NO { wrapItemAndSub =
|
beforeImg.import = uploads/media/ beforeImg.import.field = media
340
5.10 Menus beforeImg.import.listNum = 0 } }
Now insert the meta-navigation, with Include basis template, into the corresponding main template, and replace the placeholder texts by copying the corresponding temporary objects. Because both the subnavigation and the meta-information are to be shown together in a subpart or in a tag, the COA cObject can be used for integration. Example "B2C": page.10 { ... subparts.LEFT = COA subparts.LEFT.10 < temp.subnavigation_html subparts.LEFT.20 < temp.metas_html
Example "B2B"/"B2E": page { ... # Left / Submenu 40 = COA 40.10 < temp.subnavigation_autoparser_tswrap 40.20 < temp.metas_autoparser_tswrap 40.stdWrap.wrap = |
Example: Rootline A rootline menu is included in the header of the example application. It shows the user the current path. The page titles displayed are linked. Its implementation should appear as in the following figure. Figure 5.77:
First define an HMENU with the special=rootline property.
The Rootline menu shows the path of the current page
With the range property you can specify the level with which it should begin and end. If you omit the end value (or set it to -1), the entire path is displayed. With -2, the current page is not included, with -3, two levels are not included, etc. Note that you may not use spaces in the value. temp.rootline_html.special.range = 0|-2
The menu itself is created in the example as a text-based TMENU. The wrap 341
5 TypoScript
around the whole menu specifies that two colons are displayed in front of the menu items. The normal state NO is provided with a tag through linkwrap. temp.rootline_html.1 = TMENU temp.rootline_html.1 { wrap = ::| target = _top NO { linkWrap = |
A peculiar feature here is that the individual menu items are separated with a slash. But this is not placed after the last menu item, unless allWrap=/ is set. Softlink 819809
The solution lies in the use of the optionSplit function, which makes available all the properties and values of the menu objects. optionSplit is mainly used if values are to be set for a whole series of elements. For menus, one value is normally defined for many menu items. If optionSplit is used, the value is parsed by the function, and depending on the definition, different values are assigned to the elements. It is interesting at the current point in time that three values, separated by the |*| syntax, are passed on with the allWrap property. The last menu item here is not wrapped with the backslash. Syntax and rules of priority in the function are explained later on, in section 5.11.1. # optionSplit: "/" after every item except for the last allWrap = |*| | / |*| |*| ATagBeforeWrap = 1 } }
Finally, here is the variation of the rootline menu from the TypoScript template temp.rootline_autoparser_tswrap for the "B2B" and "B2E" sites. Individual menu items are displayed in the form of a numerical list, and formatted with CSS. temp.rootline_autoparser_tswrap = HMENU temp.rootline_autoparser_tswrap.special = rootline temp.rootline_autoparser_tswrap.special.range = 0|-2 temp.rootline_autoparser_tswrap.1 = TMENU temp.rootline_autoparser_tswrap.1 { wrap =
:: |
noBlur = 1 NO { linkWrap=
|
342
5.11 TypoScript in Detail # optionSplit: "/" after every item except for the # last allWrap = |*| | / |*| |*| } }
Insert the Rootline menus and test the output in the front end. In the current state of construction, the "BT3" application is almost complete. All the menus are set up and integrated. Just a few functionalities are missing, such as the print version. These will be added in the next section. In addition, more cObjects will be introduced and functions will be described in more detail.
5.11 TypoScript in Detail 5.11.1 The optionSplit Function The optionSplit function is available in TS properties marked with the data type of the same name, and is often used in menu objects. It enables distinctions to be made in cases where one value is set for several elements, and passing on different values to individual elements.
Softlink 819808
Syntax The rules are simple, but become more complex when combined. |*| Divides values into the main areas First, Middle and Last || Divides the main areas into a maximum of the first, second, and third sub-area.
1
Values are set by their priority, in the sequence: Last, First, Middle.
2
If the middle value is empty (" "), the last part of the first value is repeated.
3
If the first and the middle values are empty, the first part of the last value is repeated before the last value.
4
The values of the middle main area are repeated.
343
5 TypoScript
Example: COLUMNS With the COLUMNS cObject, a table with several columns and assigned content can be created. It contains, among other things, the gapBgCol property of the HTML-color / stdWrap +optionSplit data type. It defines a background color for individual gaps between the table cells. By accessing the optionSplit function, it is now possible to specify different colors for individual gaps. Figure 5.78: From the datatype you can see when optionSplit is available
A table with seven columns, and thus six gaps, is quickly configured. The tableParams and totalWidth properties set parameters in the
tag and a width of 500 pixels. The gap and line thickness between columns are specified with gapWidth and gapLineThickness, and the number of columns set by rows. Finally, content is assigned to individual columns. 10 = COLUMNS 10 { tableParams = cellspacing="0" cellpadding="0" border="0" totalWidth = 500 gapWidth = 30 gapLineThickness = 1 rows = 7 gapBgCol = red 1 = TEXT 1.value = column1 ... 7 = TEXT 7.value = column7 }
One interesting property we would like to demonstrate using optionSplit is gapBgCol, which so far has only been given the value red: all gaps are a uniform red (we have highlighted the colors in the following figures).
Figure 5.79: Value: red
344
5.11 TypoScript in Detail
If three values are passed on with optionSplit, based on the main areas: gapBgCol = red |*| green |*| yellow
then the first space is red, the last one yellow, and all others repeat the value of the middle space (rule 4). Figure 5.80: Value: red |*| green |*| yellow
The repeat of the middle value (rule 4) can best be seen if it is divided into sub-areas. gapBgCol = red |*| green || fuchsia |*| yellow
Here the colors green and fuchsia are set for the middle area, and, depending on how many elements exist, are shown alternately. Figure 5.81: Value: red |*| green || fuchsia |*| yellow
The main areas First and Last can also be subdivided with separate values. The first area is given three values, the middle area one, and the last one, two values. gapBgCol = red || aqua || grey |*| green |*| yellow || fuchsia
In the output, all gaps are displayed with their corresponding colors. Figure 5.82:
For the First and Last main areas, set three values each (or reduce the number of columns with the rows property):
Value: red || aqua || grey |*| green |*| yellow || fuchsia
gapBgCol = red || aqua || grey |*| green |*| yellow || fuchsia || aqua
Now the sequence in which the main areas are processed is applied, since for seven columns, only six gaps exist. First the values for the Last main area are set, then those for the First, and finally those for the Middle (rule 1). The value of the Middle main area is no longer considered, since 345
5 TypoScript
all gaps have already been defined by the Last and First areas. Figure 5.83: red || aqua || grey |*| green |*| yellow || fuchsia || aqua
If no value is assigned to the Middle main area, gapBgCol = red || grey |*||*| yellow
the last value of the First main area is repeated (rule 2). Note that there should not be a space between the dividers. In the example, the value "grey" is repeated for the gap.
Figure 5.84: Value: red || grey |*||*| yellow
If the First and Middle main area is not filled with values, the first value of the Last main area is repeated (rule 3). gapBgCol = |*||*| yellow || fuchsia || aqua
In the example, first the values of the Last main area are set. The remaining gaps will take the color yellow as the first value of the Last main area.
Figure 5.85: Value: |*||*| yellow || fuchsia || aqua
The optionSplit function has already been used for the rootline menus of the temp.rootline_html and temp.rootline_autoparser_tswrap TS templates. A special feature of this is that it is applied to all objects of the GIFBUILDER before the individual menu items are created. The same applies for the allWrap property used. temp.rootline_autoparser_tswrap.1.NO { ... # optionSplit: "/" after every item except for # the last allWrap = |*| | / |*| |*| ... }
The allWrap property is given three values:
• 346
The First area is empty |*|.
5.11 TypoScript in Detail
•
The Middle area contains, the wrap | / |*| as a repeating value.
•
The Last area contains an empty space, which is why a final |*| divider is set. Otherwise the empty spaces at the beginning and end of the entire string would be removed, according to the TypoScript rules.
The optionSplit function may look rather complex at first, but it is also very powerful, and you can assign different values to a series of elements without any additional programming. For menus in particular, optionSplit is a utility that it would be hard to do without.
5.11.2 Working with Images and the GIFBUILDER If TYPO3 is installed with the recommended graphic libraries, you can carry out extensive image manipulation using the GIFBUILDER function. Graphical menus in particular access this and automatically create images in GIF format from the individual menu items. But they can also produce headers with individual fonts as an image. In this way, layout 5 of the headers for content elements is created as a graphic, with the content (default) standard template and styles.header.gfx1 integrated as a basis template. The Textbox content element also accesses the GIFBUILDER.
Softlink 788778
GIFBUILDER Objects (GifBuilderObj) The GIFBUILDER functions as a series of general properties such as XY, offset, or reduceColors, which specify the size of the image, a general gap for all objects from the top left corner of the image, and the reduction of the GIF image to a specific number of colors. A work area is created inside the image with the workArea property. The actual objects are generated in a numerical list of GifBuilderObj. Be careful: in the TSref, references to individual objects are set exclusively to GifBuilderObj, and not to cObjects with the same name, such as TEXT or IMAGE. The following GIFBUILDER objects can be used directly or through other GifBuilderObjs: TEXT The GifBuilderObj TEXT creates an image from text. Via the stdWrap data type and getText you have the possibility of reading the text out separately. 347
5 TypoScript
SHADOW As a GifBuilderObj, SHADOW is a property of TEXT, and creates a shadow. If it stands alone, a link must be made to the TEXT object to which it refers, via textObjNum. EMBOSS The same thing applies to the EMBOSS GifBuilderObj. It creates two offset copies behind the TEXT object, producing the character of a relief. Using properties, these can be given different colors, made softer, or more transparent. OUTLINE The GifBuilderObj OUTLINE is also a property of TEXT. It strengthens contours and can only be influenced by color value and intensity. The result is usually not too good. It is better to use a shadow with a strong intensity. BOX BOX creates a rectangle whose size and alignment can
be defined. IMAGE The GifBuilderObj IMAGE of the imgResource data type can be referenced to an image, or you can even use the GIFBUILDER function, via which all GifBuilderObjs are available to it. EFFECT With EFFECT it is possible to rotate the image, to turn it upside down, to set grey values, change the gamma values, etc. Values are added with the value property and separated with the pipe symbol, "|". WORKAREA If you set a new WORKAREA in the numerical list of the GifBuilderObjs, the following objects will refer to the newly set work area (e.g. with the offset property). CROP CROP can restrict the display of the image to partial areas. This GifBuilderObj sets the workArea to the new dimensions of the
image.
348
5.11 TypoScript in Detail
SCALE SCALE scales the image with the width and height properties to a new size. This GifBuilderObj also sets the workArea to the new
dimensions of the image. ADJUST With ADJUST you can correct the tone values of the image by defining the input and output grey values. If you have to correct the gamma values, use the GifBuilderObj EFFECT. The properties here are also listed via value and separated by the pipe sign, "|". [IMGMAP] IMGMAP is not a GifBuilderObj, but is used in conjunction with TEXT to create an ImageMap for a GIF file. It is used for the IMGMENU menu object.
+calc If +calc is added to the data type of a property in the TSref, calculations can be performed with the value. The operators used here, +, -, /, and *, do not have any priorities and are processed in the same order in which they are set. However, for the GIFBUILDER you can also refer to values of other objects. This makes it possible, for example, to calculate the width and height of the overall picture, depending on GifBuilderObjs such as TEXT or IMAGE. ... XY = [100.w]+160 , [100.h]+5
For the image dimensions, this means: XY = [width of the GifBuilderObj 100]+160 pixel, [height of the GifBuilderObj 100]+5 pixel
.niceText The Freetype library, integrated in the GDLib and used by PHP, does not always support satisfactory anti-aliasing in all versions. The niceText property helps display small letters more clearly. It provides a workaround by causing TYPO3 to render text in double size on a mask, which is then downscaled to the correct size. In doing so, the combine ImageMagick function is used to place (to mask) the text onto the background. This procedure puts a large demand for resources on the server to create the images, but provides better results, depending on the ImageMagick version used. But since the images are not newly created for each call, but only on the first call after the cache has been emptied, you must 349
5 TypoScript
decide at what point you want to use niceText. Please note that niceText, depending on the versions of GDlib, Freetype, and ImageMagick used, can produce different results, so that your graphical menu on the live server may possibly look different to the one on the production server.
Example: The Image in the Header Softlink 016166
In the section "Stages of Construction with Cascading Templates" onwards, an image had already been inserted in the header area of the output. The IMAGE object type used for this can use two different methods for integrating images, with its file property of imgResource data type.
•
It references a file in the file system or the Files field in the page header.
•
It uses GIFBUILDER, a function that allows you to create an image combining several graphic objects such as images, text, or boxes.
The first method was demonstrated in the temp.header_html TS template. Working with the GIFBUILDER function will now be illustrated using the temp.GIFBUILDER_header_image TS template. If you want to follow and reconstruct the example, you will find it in the Main Templates/ cObjects SysFolder. The header should not only display the current image that was included in the page headers, as was the case until now, but also include the title of the current page as a graphic. The text is given a shadow and the first letter is highlighted in color. Figure 5.86: Including the graphic as a GIFBUILDER object
First we create a temporary object, which is defined as an IMAGE cObject. Through the file property of the imgResource data type, a new image is created with the GIFBILDER function. temp.header_image_gifbuilder = IMAGE temp.header_image_gifbuilder.file = GIFBUILDER
First the size of the image is determined with XY. temp.header_image_gifbuilder.file { XY = 588,125
350
5.11 TypoScript in Detail
The object 10 in the numerical list of GifBuilderObj is of the IMAGE type and gets the respective images, which were assigned to the partial page tree, from the Files field of the page header. The slide parameter causes the page tree to be searched from the current page down to level 1, until the first image has been found. 10 = IMAGE 10.file.import = uploads/media/ 10.file.import.data = levelmedia:1, slide
The object 10 is positioned with the offset property in relation to the top left corner of the overall image (or, if workArea is set, to the work area). 10.offset = 199,0
Next the yellow first letter of the page title is created. The object 18 is defined as a GifBuilderObj of the TEXT type. Its text property is of the stdWrap data type and first tries to read the subtitle of the page, via text.field = subtitle. If none is there, the title is used instead. 18 = TEXT 18.text.field = subtitle // title
The case and crop properties specify that the text will be written in capitals, but only the first letter will be displayed. 18.text.case = upper 18.text.crop = 1
The object 18 is also positioned in the overall picture with offset; it is assigned a font size and color. 18.offset = 62,90 18.fontSize = 40 18.fontColor = #FFCC33
The niceText property improves the font reproduction. 18.niceText = 1
The TEXT GifBuilderObj accesses the EMBOSS GifBuilderObj via its emboss property. The two copies of the letter offset by the value of the offset property are filled with the same color value; blur makes them softer and opacity controls transparency. 18.emboss { highColor = #FFCC33 lowColor = #FFCC33 offset = 2,2 blur = 99 opacity = 50 }
351
5 TypoScript
In the same way, the whole text is generated as object 20. 20 = TEXT 20.text.field = subtitle // title 20.offset = 75,85 20.fontSize = 20 20.fontColor = #333333 20.niceText = 1
Here the TEXT GifBuilderObj, via shadow, accesses the SHADOW GifBuilderObj and produces a silver shadow. It has an offset to the top left corner of the 20 object, via offset; with blur it is softened, with opacity it is set to 60% transparency, and with intensity its brightness is defined. 20.shadow { color = silver offset = 7,8 blur = 70 opacity = 60 intensity = 15 } }
You can extend the example just as you please, of course. With the mask property of the IMAGE GifBuilderObj, the image is given a black and white mask.
Figure 5.87: Mask placed over the image
Add the following line to the TypoScript configuration: 10.mask = fileadmin/mediapool/material_intern/ gifbuilder-mask.png
Only those parts of the image covered by the white areas of the mask will be visible for the GIFBUILDER object 10; the black areas will be invisible.
352
5.11 TypoScript in Detail Figure 5.88: The header image with the mask
Alternatively you can add a new GIFBUILDER object 15. It is a GifBuilderObj of the IMAGE type, which creates a separate picture with the GIFBUILDER function. With the XY property, the size of the image is again specified, and referenced to the image in the file system with its GIFBUILDER object 100. Figure 5.89: The image shows the TYPO3 logo on a gray background
With the offset property, the logo is positioned in the newly created image. 100.offset = 160, 5
The
background
of
the
image
is
set
to
transparent
with
transparentBackground = 1. The same result is achieved via transparentColor = #CCCCCC with the gray color value of the logo. transparentBackground = 1 transparentColor = #CCCCCC }
This results in the TYPO3 logo being seamlessly integrated into the header image.
Figure 5.90: A combination of several images in one
You can see that there are no limits to working with the GIFBUILDER 353
5 TypoScript
function. Ultimately, it is your creative ideas alone that will determine the result.
5.11.3 The stdWrap Function The stdWrap function plays a central role in TypoScript and also mirrors the concept of TS. Much use has already been made of it in the examples. Its functionality grew out of the wrap concept and the fact that TypoScript is not a programming language, and therefore cannot handle control structures (apart from conditions) on its own. With its collection of properties and functions that supply data, change or edit contents, as well as functions that enable conditional processing, stdWrap is the "Swiss Army Knife" for the TypoScript developer. The properties and functions of stdWrap can be used anywhere an object property of the stdWrap data type exists. Frequently objects also have a property with the name stdWrap, which makes precisely this function available. The properties of stdWrap are separated into the three areas Get data, Override/Conditions, and Parse data, depending on their purpose. Please note that the properties are processed in the same order as they are listed in the TSref.
Get data The Get data area of the properties is used to make data available or to read it out. This can be for a title page, the current date, a cObject, a number of rows from a database query, a file list of a directory, or a global variable. The most important properties are data, field, current, cObject, and filelist. data Reads out values from different PHP arrays, with the syntax Type:pointer, such as data records.
Example: ... .data = page:title field Usually returns the contents of a database field from the current data record, as a value. Example: ... .field = title
354
5.11 TypoScript in Detail
current Sets the access to the current content of the data register, as a Boolean value. The data register is an internal buffer in TYPO3 where current values are stored for certain functions. The variables stored there are available globally and are read out, saved, or overwritten at various points during processing. cObject Loads the content of a content object. Example: ... .cObject = IMAGE filelist Reads a file directory and supplies a list of files. The following parameters must be separated with the pipe sign |: 1. Path 2. Comma-delimited list (without spaces) of possible file types (gif,jpg...) 3. The order of sorting: name, size, ext, or date 4. r inverts the order of sorting 5. If this switch is set (not empty), the file list is created with the complete path, and not just with the file name Example: ... .filelist = fileadmin/img/|jpg,png|name||1 As an additional aid, you can have the list of the current data record displayed directly in the front-end output, with the stdWrap debugData property.
355
5 TypoScript
Figure 5.91: Output of the current data record in the front end
Override/Conditions The properties in this area are used to override and compare values. Among other things, you can set a new value that is dependent on other values. The most important properties are: override Overwrites the value of an object if the value of override is not empty "" or 0. Whether the original object already has a value or is empty is irrelevant here. ifEmpty Passes a new value to an object if its value until now is empty "". 0 is treated here as a value. listNum Extracts the desired value from contents that are separated by commas trim Removes empty spaces, tab spaces, and line breaks required If the current value is empty "", the calling object is used. stdWrap properties that follow this are not taken into consideration. 356
5.11 TypoScript in Detail
if Includes the if function of the same name. It is used to query if one or more conditions are met, and values are set depending on this. fieldRequired If the given field of the current data record is empty, the current value is also emptied.
Parse data The Parse data area defines properties for processing data. A wide range of string operations is possible here. HTML content can be filtered via the HTMLparser function, and certain tags can be removed. With split, the contents can be split into individual values, on the basis of specific characters, and processed. Other functions that are included via properties are encapsLines, addParams, textStyle, tableStyle, filelink, and typolink.
Get data and Parse data As stdWrap properties of the Get data function area, field and data have already been used in the examples so far.
field With field, the subtitle or title of the pages ... NO { 10 = TEXT 10.text.field = subtitle // title
or an image from the Files form field in the page header was read out for individual menus. NO { # get the image from the page beforeImg.import = uploads/media/ beforeImg.import.field = media
data The data property was used to obtain the image in the page header not only from the current page, but to search through the rootline down to the top level until the first image has been found. 357
Properties of the stdWrap object from the Parse data area have already been used in the first steps in section 5.2. This simple example displays the text in upper case, with the case property: page.10 = HTML page.10.value = kasper page.10.value.case = upper
Example: Print Version In the example application, the print version is missing. A button that optimizes the relevant page for printing should be included. The base layout is omitted in the print version, and only the content is formatted via CSS styles. The page is called with the URL parameter &type=98, which is reserved internally as typeNum=98 for the print version. In order to create the link for the print view, properties are used from the areas Get data and Parse data of the stdWrap object.
Figure 5.92: The print button calls the page with the &type=98 parameter
Create a new TS template. You will find it in the examples under the name temp.printversion in the Main Templates/Functions/ SysFolder. Here the button for printing is generated, and a page is also defined that is responsible for the output. First you create a temporary cObject of the COA type. temp.printversion = COA temp.printversion {
The button is created with the wrap property over the entire object. wrap = {$printlabel}
358
5.11 TypoScript in Detail
However the current URL with the &type=98 parameter is missing from the button. For this purpose the 10 property in the numerical list of the COA is defined as a TEXT cObject. 10 = TEXT
As a special feature of the TEXT cObject, the stdWrap properties are directly addressed from the basis of the object, which does not match the standard behavior of other objects. In order to now obtain the URL of the current page, the data property is used. The property has the getText data type, which means it is able to read out values from different arrays made available by the system, using the syntax Type:Pointer. The current address can be determined with the getIndpEnv type and the
In the array there is now a value such as /index.php?id=18. It can be further processed with the wrap property, in order to add the &type=98 parameter. 10.wrap = |&type=98
Note that this is only a simple example to create the link for the print output. If you use the TS option config.simulateStaticDocuments, this and the following example will not work—they are used more to display the stdWrap properties. An extension to create corresponding links correctly is available in the TER.
Softlink 463307
A second possibility is to use the split property. With this, the value can be split up into individual parts via the properties of the split function of the same name. 9 10.split.token=/ sets the string to be used as a divider. /index.php?id=18 is now split into two values. The first one is empty, and the second one contains the string after the index.php?id=18 divider. 10.split.cObjNum of the cObjNum +optionSplit data type is
used as a pointer to cObjects in a numerical list. These objects (1, 2, 3,...) are called to process the split values. Which object is called for which split value is defined by cObjNum. If cObjNum=1 is set, each split value is passed to the 1 object for processing. optionSplit can also be used to have each individual split value
9 This would not make sense in the example, since only one value is processed; it is
just used here to demonstrate the split function.
359
5 TypoScript
processed by a different object. The exact way that optionSplit functions is explained in section 5.11.1. In the following setup, the 2 object, which adds the type parameter to the split value taken over with current=1, is only called for the last value (index.php?id=18) All other split values are processed with the 1 object, which sets an empty value with override=. /* Demonstration of the split function 10.split.token = / 10.split.cObjNum = 1 |*| 1 |*| 2 10.split.1.override = 10.split.2.current = 1 10.split.2.wrap = |&type=98 */ }
The result matches the first and shorter variation. You now need to define the template for the page output in the print format, with typeNum=98. Switching templates, using type/typeNum, was already discussed in section 5.8. # different page template for the 98 type # (=print version) alt_print = PAGE alt_print { typeNum = 98
Inline CSS style details define the format of the output. CSS_inlineStyle = body, p, h1, h2, h3, h4 { font-family: Arial, Verdana, sans-serif; font-size: 11pt; } h1, h2, h3, h4
Finally the content of the Normal column is displayed. 10 < styles.content.get }
Override/Conditions As we already hinted at the beginning, it is possible to link properties to conditions. stdWrap properties that override values or set conditions have also been used already in the examples.
listNum For the temp.metas_html menu that shows meta-information, the first image from the array was addressed with the listNum=0 property when images were read from the page header. Even if there are several images 360
5.11 TypoScript in Detail
in the files field, only this one is displayed. NO { beforeImg.import = uploads/media/ beforeImg.import.field = media beforeImg.import.listNum = 0
ifEmpty For the base layout of the ts CTABLE template TS template, an empty space was passed on ( ), with the ifEmpty property, so that the table is still displayed even if it has no content. page.30 = CTABLE page.30 { ... c.10 = COA c.10.5 = HTML c.10.5.value =
c.10.10 < styles.content.get c.10.10.wrap =
|
c.10.25 = HTML c.10.25.value =
c.10.stdWrap.ifEmpty =
Example: Using Two Columns Until now, only the content of the Normal column has been displayed in the main templates. Only the ts wrap template TS template was included permanently in the base layout as the Right column. One solution to the optional use of a second column could be to create two different TS templates that are included in the page tree, depending on requirements. But since not all pages should be shown in two columns, a more flexible solution is needed, which only creates the right-hand area in the template if contents are actually available. This will be demonstrated here using the auto parser template TS template. To do this, several objects are created in the temp.* object path. First the styles.content.get object is copied to temp.inhalt, so that this can be used to query the contents of the tt_content table in the normal (colPos=0) column. # left content temp.inhalt < styles.content.get
The second temporary object temp.right reads out the contents of the Right column (colPos=2) with the previously made 361
The stdWrap.required property terminates further processing of stdWrap if the object has not produced any content, which in this case is the content read out from the right-hand column. If content exists in the right-hand column, then this is enclosed by a tag for positioning on the page, using the stdWrap innerWrap property. temp.right.stdWrap.required = 1 temp.right.stdWrap.innerWrap = |
The content of the Normal column is placed in front of this with the preCObject property and also wrapped in a tag. # placing the left content as cObject before the right # content temp.right.stdWrap.preCObject < styles.content.get temp.right.stdWrap.preCObject.wrap = |
The setup temp.right now defines an object that displays the contents of the Normal and Right columns, provided the contents are generated in the right-hand column; otherwise nothing at all is displayed. The Normal column is provided here with the content_left ID instead of content in the tag, which means that the column can be set more precisely via CSS than for a single column output. The output of the temp.inhalt object is overwritten by the temp.right object if content exists in the right-hand column. This is done by the stdWrap override property. override itself has the string/stdWrap data type, and so it can display a string or data via properties of the Get Data function group of stdWrap. temp.inhalt.stdWrap.override.cObject < temp.right
The content of the temp.inhalt object is finally copied to the subpart. temp.mainTemplate = TEMPLATE temp.mainTemplate { ... subparts.content < temp.inhalt }
This results in the base layouts being divided into two content areas, if content exists in the Right column. 362
5.11 TypoScript in Detail
Figure 5.93: Output in the front end
You can see that the stdWrap function is a powerful tool for reading content, following control structures for comparisons, and finally for processing content. If the range of functions is not sufficient for your purposes, there is also the possibility of having content processed with your own PHP functions, with the preUserFunc and postUserFunc properties.
5.11.4 Conditions Conditions have already been introduced. These conditions must be fulfilled in order for the TS code that follows them to be considered. These queries represent another control structure that you can use. You may recall that if several conditions are set, only the first condition to be true is taken into account. They are terminated with [END] or [GLOBAL]. Conditions cannot be set inside the { } operators, that is, inside nested properties. The [ELSE] condition is automatically fulfilled if the condition set before it was not fulfilled.
Softlink 315080
Conditions can also be combined, as the following example shows, where the enclosed TS code is only processed if the calling system can identify itself as a Linux system, or is located in the IP range of 145.153.102.*. [system = linux][IP = 145.153.102.*] ... [END]
363
5 TypoScript
No conditions have been used so far in the examples. We will briefly introduce the conditions listed in the current TSref, and afterwards show how they are put to use in practice in the example application.
Overview Softlink 501292
The following overview names all the conditions that you can set. The exact values can be found in the TSref. browser Syntax: [browser =browser1 , browser2 ,...] [browser = msie] applies to all MS Internet Explorer versions [browser = msie, opera] applies to all MS Internet Explorer and
Opera browsers [browser = opera7] applies to all Opera 7.xx browsers, including
Opera 7.1 etc. Note that browsers can also be identified under other names, so that the request will then not lead to the desired result. version Syntax: [version =value1 ,>value2 ,=value3 , The version must be larger than the specified value. [version = > 5.5] < The version number must be smaller than the specified value. [version = < 5.5]
system Syntax: [system=system1,system2 ] The character string is compared with the first part of the system identification and returns the condition as true if they match. [system = win9] matches Win95 and Win98 [system=win,mac] matches Windows and Mac operating
systems
364
5.11 TypoScript in Detail
device Syntax: [device=device1,device2 ] The condition is true if the character string matches the output device (pda, wap, grabber, robot). useragent Syntax: [useragent=agent ] A check is made to see if there is a match with the variables getenv("HTTP_USER_ AGENT"). The wildcard * can be used at the beginning and/or at the end of the string. [useragent=Lotus-Notes/4.5(Windows-NT)] matches HTTP_ USER_ AGENT "Lotus-Notes/4.5(Windows-NT)" [useragent = Lotus-Notes*] also matches this.
language Syntax: [language =lang1,lang2,...] The variable getenv(HTTP_ACCEPT_LANGUAGE) is compared with a given value; with an exact match the query is fulfilled. IP Syntax: [IP =ipaddress1,ipaddress2,...] The variable getenv("REMOTE_ADDR") is checked for a match with the given value. This can contain the wildcard *, or just consist of one, two, or three parts: [IP = 145.*.*.*] matches all IP addresses that begin with 145.
hostname Syntax: [hostname =hostname1,hostname2,...] The value as a comma-separated list of domain names must match the variable getenv("REMOTE_ADDR"). Wildcards * are allowed, but may not be used in a string. [hostname = YourDomain.*.com] is correct [hostname = YourDomain*.com] is wrong
hour Syntax: [hour =hour1,>hour2,, and , < [globalVar = GP:L=3] applies, for example, to the URL ...index.php?id=45&L=3.
As globalVar, with the difference that values are compared as a string. The wildcard * can also be added at the beginning or at the end. [globalString = HTTP_HOST=www.mysite.com] and
367
5 TypoScript [globalString = HTTP_HOST=*.mysite.com] both match the
value http://www.mysite.com. userFunc Syntax: [userFunc =user_match(checkLocalIP)] With userFunc, your own PHP functions can be used for checking.
Example: Extending the Print Version The button used so far in the temp.printversion TS template to call the print version works very well, but only as long as you do not create static URL addresses with the TS option config.simulateStaticDocuments. This is why the template will be extended below. Depending on the URL type, the string is edited and given various parameters. For the existing temp.* object, first the 10 object is reconfigured for static URL addresses. temp.printversion = COA temp.printversion { wrap = {$printlabel } # simulate Static Version, all included link parameters # will also be processed. 10 = TEXT 10.data = getIndpEnv:REQUEST_URI
The URL read out via the stdWrap property is split into individual strings with the listNum.splitChar property and the "." as a value. With listNum=0, only the first element of the value is taken into account, and is wrapped with |.98.html. (The whole thing works if you have included the parameters with config.simulateStaticDocuments_pEnc_onlyP as an MD5 hash when creating the static URL address.) 10.listNum.splitChar = . 10.listNum = 0 10.wrap = |.98.html }
The already existing temp.printversion.10 object is now given a Condition and only processed if this is met. globalString queries whether the server variable ENV:REQUEST_URI has the value /index.php*. The wildcard * is used to check the string just for the start value /index.php.
368
5.11 TypoScript in Detail # "normal" version, for pages with index.php, with # parameters where required, e.g.: ?id=3434&L=1 [globalString = ENV:REQUEST_URI = /index.php*]
If the condition is met, the current temp.printversion.10 object is deleted and redefined, as in the previous version. temp.printversion.10 > temp.printversion { 10 = TEXT 10.data = getIndpEnv:REQUEST_URI 10.wrap = |&type=98 }
The condition is concluded with [GLOBAL]. [global] ...
The page template remains unchanged. The print version can now be used for both variations.
Example: Language Selection TYPO3 is very well suited for multi-language applications. We have already shown how the editor can maintain the content of several languages in the back end. These should now be selectable via a language selection in the front end, a link that calls the page with the parameter &L=[sys_language_uid], and in front of which a small flag for the chosen language is placed.
Figure 5.94: Language switch: .English is active, .German can be chosen (left) and vice versa (right)
This can be implemented via an included PHP script; but it can be done more simply with TypoScript. 369
5 TypoScript
In the setup of the newly created temp.language TS template, English is first defined as the default language (sys_language_uid=0) for the config TLO with the language=en property. # Setting up the language variable "L" to be passed # along with links config.linkVars = L # English as default language, sys_language.uid = 0 config.sys_language.uid = 0 config.language = en config.locale_all = en_UK
If the URL contains the parameter L=1, the language with ID 1 (sys_language_uid=1), that is, German, is defined as the alternative language. Since this is not a global definition, the GET/POST data is checked with the condition [globalVar=GP:L=1] to see if the condition is met. # German language, sys_language.uid = 1 [globalVar = GP:L = 1] config.sys_language_uid = 1 config.language = de config.locale_all = de_DE [GLOBAL]
The actual link is created as a temporary object via the COA cObject. The 10 object of the TEXT object type should provide the alternative language, depending on the language currently selected. This is why value is set as a constant. A table that formats the output is placed around the whole object with the stdWrap outerWrap property. It contains the flag of the alternative language, which is also included as a constant. temp.language = COA temp.language { 10 = TEXT 10.value = ${languageVersion} 10.outerWrap =
|
With the stdWrap typolink property, a link is generated around the 10 object. The parameter property determines the current ID. With additionalParams, the third constant is added as a value to the &L additional parameter. AtagParams adds a CSS class to the tag. 370
5.12 Working with Frames 10.typolink { parameter.data = page:alias // TSFE:id additionalParams = &L={$foreignLanguageID} ATagParams = } }
You now just need to define the correct constants for the link, depending on the current language. If this is the defined default language, English ([globalVar=GP:L=0]), no condition is required, and the parameter for the link is set with foreignLanguageID to 1. The text and the flag icon are specified with languageVersion and flagSmall. Constants: foreignLanguageID = 1 languageVersion = Deutsche Version flagSmall = fileadmin/images/icons/flagde.gif
If the current language is one other than the default language English, that is, the parameter L of the current URL has a value >0 ([globalVar=GP:L>0]), then set a condition with the globalVar condition in the constants field and redefine the constants. [globalVar = GP:L>0] foreignLanguageID = 0 languageVersion = English version flagSmall = fileadmin/images/icons/flaguk.gif [global]
Insert the language switch into the relevant main template and check the result in the front end. You will see that everything works in a simple way with pure TypoScript.
5.12 Working with Frames Even if working with frames is no longer considered best practice, we want, for the sake of completeness, to demonstrate how frame-based sites can be implemented with TYPO3. Using frames you can divide the browser view into various freely definable segments. Each segment forms separate pages of a web application, which can call each other via links and the target="Name of the Frames" attribute. An HTML file with the following code includes the pages top.htm, menu.htm, content.htm, and bottom.htm via a nested frameset. The Title
If the page is called in the browser, it will clearly show the individual frames. Content is provided by individual pages.
Figure 5.95: Output of the HTML example in the browser
5.12.1 Creating Frames Softlink 234280
To create a site with frames in TYPO3, you must define a number of pages in a TS template. myframeset = PAGE top = PAGE menu = PAGE content = PAGE bottom = PAGE
372
5.12 Working with Frames
Each of the pages is assigned to a separate value via the typeNum property. myframeset.typeNum = 0 top.typeNum = 1 menu.typeNum = 2 content.typeNum = 3 bottom.typeNum = 4
A content object of the TEXT type is created for each of the individual pages, with the exception of myframeset. top.10 = TEXT top.10.value = header menu.10 = TEXT menu.10.value = left menu content.10 = TEXT content.10.value = content area bottom.10 = TEXT bottom.10.value = footer
You can already call pages individually in the browser via the id and the corresponding type parameter. The concept of template switching using type/typeNum has already been introduced in section 5.8. Figure 5.96: Addressing individual pages with the type parameter
If you call a page without the type parameter, it will be set to the default value 0, thus calling the myframeset template. This is now defined as a frameset, in order to construct the HTML example. As a top-level object of the PAGE object type, myframeset has the frameset property of the FRAMESET object type. It creates the tag and the respective frames or framesets nested in each other, via the individual objects of the numerical list. For the sake of clarity, their attributes were standardized as constants and moved to the constants field.
Setup The number and size of frame rows and columns is specified with the 373
5 TypoScript rows and cols properties; params is set as a constant. myframeset.frameSet.rows = 205,*,50 myframeset.frameSet.params = {$frameSetParams}
The frames and the nested framesets are now defined via the numerical list. The 10 object is of the FRAME object type, and its obj property is a pointer to the top pages already created as TLOs. The attributes of the frame for the params property are also passed on as constants here. myframeset.frameSet { 10 = FRAME 10 { obj = top params = {$frameParams} }
The 20 object is of the FRAMESET object type and represents a frameset within a frameset. With the objects 24 and 26, two frames are created in this way, and display the pages menu and content in the middle frameset. 20 = FRAMESET 20.cols = 195,* 20.params = {$frameSetParams} 20 { 24 = FRAME 24 { obj = menu params = {$frameParams} } 26 = FRAME 26 { obj = content params = {$frameParams} } }
Finally the frame 30 is created, which includes the bottom TLO. 30 = FRAME 30 { obj = bottom params = {$frameParams} } }
If you again call the page in the browser without the parameter, the output will match that of the HTML example.
374
5.12 Working with Frames
5.12.2 The Example Site with Frames To create the example site with a frameset, we have chosen a simple division into three vertical frames in the ts wrap template (frames) TS template. In the middle content area content, the left menu, the actual content, and the right column are integrated. This makes it easier to address individual target frames with the menus. On the left they all have the attribute target="content". The result is shown in the following figure. border was set to 1 in order to highlight the individual frames.
Figure 5.97: Output of the example site with frames
So that you do not have to keep on repeating the same frame parameters, they have again been set as constants and defined in the constants field.
For page objects that are intended to display content, the CSS file is inserted with the stylesheet property, which is responsible for formatting the output. top.stylesheet = fileadmin/styles/ts-template-wrap.css content.stylesheet = fileadmin/styles/ ts-template-wrap.css bottom.stylesheet = fileadmin/styles/ ts-template-wrap.css
The frameset itself is called via the myframeset TLO with the typeNum=0 property. It is again defined with the frameSet object and its properties. The number and size of the frames is determined with rows; params integrates the attributes as constants from the constants field. The separate frames themselves are generated as objects of the numerical list. myframeset.frameSet.rows = 205,*,50 myframeset.frameSet.params = {$frameSetParams} myframeset.frameSet { 10 = FRAME 10 { obj = top params = {$frameParams} } 20 = FRAME 20 { obj = content params = {$frameParams} } 30 = FRAME 30 { obj = bottom params = {$frameParams} } }
The frameset is already complete, and only the content for individual pages still needs to be included. At this point we will assign the pages top, content, and bottom by copying temporary objects that still need to be 376
To define the content, we can take advantage of the fact that existing TS templates can be used repeatedly. The menus and functionalities included in the following listing, must, of course, be included in the template record with Include basis template. The same applies for the content (default) basis template, which is integrated with Include static. Each of the temporary objects is defined as a COA. They must be placed at the beginning of the setup so that they already exist when individual page objects are parsed. The desired TS objects are copied to the individual objects in the numerical list and wrapped with tags. The menus are adjusted here at the same time and 10.1.target, for example, is set to the content page. If you are not sure about addressing properties for nested objects, the TypoScript Object Browser will be of further help to you.
Figure 5.98: TypoScript Object Browser
temp.top summarizes the contents for the top frame. The rootline menu (10), the button for the print version (40), the header image (20), and the main navigation (30) are displayed. temp.top = COA temp.top { ## Rootline Menu 10 < temp.rootline_autoparser_tswrap ## adjust menu
Objects for the contents of the subnavigation (100), meta-information (200), the Normal column (20), and the Right column (30) are copied to the temp.content object for the content frame. You can see that within the COA temp.content the object 10 of the numerical list was in turn defined as COA. temp.content = COA temp.content { # Left / Submenu + Metas 10 = COA 10 { 100 < temp.subnavigation_autoparser_tswrap ## adjust menu 100.1.target = content 100.2.target = content 200 < temp.metas_autoparser_tswrap 200.1.target = content } 10.stdWrap.wrap = | # Content-Left 20 < styles.content.get 20.stdWrap.wrap = | # Content-Right 30 < styles.content.getRight 30.stdWrap.wrap = | 30.stdWrap.required = 1 }
The temporary object temp.bottom for the bottom frame takes over the properties of the temp.copyright_tswrap_autoparser object with the 20 object, to display the copyright sign at the footer of the application. temp.bottom = COA temp.bottom {
378
5.13 Future and Prospects # Footer 10 = TEXT 10.value = ## Copyright 20 < temp.copyright_tswrap_autoparser 20.wrap = | }
Finally the target frames are defined in the constants field so that the forms and content links address the correct frame. They are inserted via content (default) as constants with the default value page, and can also be edited with the Constant Editor.
Figure 5.99: Attributes for links are set to content
This should suffice for the example on frames. If you view the result in the front end, it will be the same as those of the other example sites. Some functionalities still need to be adjusted. The Rootline Menu, for example, does not yet show the path of the current page, but you could make this into one of your first tasks.
5.13 Future and Prospects 5.13.1 XHTML and Accessibility The need to separate content from design not only contributed to the creation of content management systems, but also influenced the under-
10 HTML is derived from SGML, which was developed as a pure mark-up language.
XML originated from this, and in turn efforts are being made to re-establish XHTML as a pure mark-up language.
379
5 TypoScript
lying technologies. HTML was originally developed as a markup language 10 with layout elements, to bring structure into documents (to split up documents), to embed other media such as images into the text flow, and to enable documents to be connected via links. The rapid spread of websites, especially in the commercial area, had an influence on the fact that design became more important as a means to differentiate or customize websites. For a long time tables intended for list type content were used for this purpose, as the main design tool. More and more tricks like this were used to implement layouts with HTML to meet the expectations of a visual medium. Many tricks and workarounds, as well as the dialects of different browsers, have led to the consistency of HTML syntax being heavily compromised, and as a consequence, the ability of programs such as browsers for the disabled to logically interpret it. The WWW consortium headed by the HTML developer Tim Berners-Lee made several attempts to meet design demands by extending HTML specifications and making them more consistent, at the same time standardizing syntax and allowing less room for interpretation by browsers. The basic idea behind HTML, and even its predecessor SGML, was to precisely separate form and content. 11 Cascading stylesheets (CSS) were developed fairly early on as a technology suitable for this, but in practice their acceptance by browser manufacturers and web developers was very slow. The change in ideas in recent years has been accelerated by the following facts:
•
The maintenance of content and changes to the design require a large amount of work, because the two are interwoven.
•
Documents are unnecessarily large and use up valuable bandwidth and loading time.
•
Output to alternative devices is not possible, or possible only with large modification costs.
•
New technologies such as XML were developed, which are considerably more flexible and efficient.
•
Laws have been passed in many countries that prescribe
11 "Many credit the start of the generic coding movement to a presentation made by
William Tunnicliffe, chairman of the Graphic Communications Association (GCA) Composition Committee, during a meeting at the Canadian Government Printing Office in September 1967: his topic—the separation of information content of documents from their format." From: Charles F. Goldfarb, "The Roots of SGML, a personal recollection", http://www.sgmlsource.com/history/roots.htm
380
5.13 Future and Prospects
the separation of form and content as a component of accessibility information, at least for websites of public institutions or authorities. XHTML plays an important role as a specification and as the successor to HTML, and forms the connection between HTML and XML. With the introduction of XHTML at the latest, design elements were to a great extent removed from the language. Where possible, design should be controlled exclusively by CSS, to achieve stricter separation of content and design. In addition, fault tolerance is also heavily reduced. The stricter syntax means that browsers need to use less resources for error correction, and they can therefore function extremely efficiently on many different devices, down to smartphones. Advantages of standard conformity in general, and XHTML in particular:
•
Low costs: shorter loading times and server loads, better performance; simplification of website maintenance due to more nimble code, and the separation of content and design.
•
Investment security: standard conformity ensures compatibility to newer output devices and extendibility to other XML-based languages.
•
Longer range: improved accessibility from different platforms, browsers, and assisting technologies; not least, a better positioning with search engines.
From the last mentioned point, it becomes clear why XHTML and accessibility are often mentioned in the same breath: the Web Content Accessibility Guidelines (WCAG) or the German Barrierefrei Informationstechnologie-Verordnung (BITV), assume a standard conformity, because this enables a broader technical support of assistive technologies such as screen readers, voice browsers, and Braille line readers for people with physical disabilities. So by complying with (X)HTML standards, we are already halfway towards a content accessible website.
Softlink 895351
In version 3.6.0, TYPO3 conforms with "XHTML1.0 Transitional". All the source code of the core was cleaned up in this respect and adjusted to the newer standard. The extensions are initially not involved in this, and will be brought up to date gradually by the respective authors. These are the essential reforms of XHTML1.0:
•
Well-formed: Elements may not overlap and must display closing tags.
•
Element and attribute names must be written in lowercase.
•
Attribute values must always be placed in quotation marks, e.g. 381
5 TypoScript border="0". Attributes may not appear in minimized form, but must be written out in full, e.g. checked="checked" instead of just checked.
•
Empty elements must be terminated, e.g. or .
•
The content of script and style elements must follow a specific syntax or better, be moved to external script or style documents.
Softlink 570674
You can check whether your webpages are XHTML conformant or not with the (X)HTML validator of the WWW Consortium (see softlink). The techniques for generating accessibility-compatible webpages described in the following section work in harmony with XHTML and should be seen in this context.
Softlink 728651
These are the most important TypoScript definitions concerning XHTML, which are set via config: doctype Data type: string Example: xhtml_trans | xhtml_frames | xhtml_strict | xhtml_11 | xhtml_2 | none
Declaration of the document type. Shows to which standard the browser should comply. doctypeSwitch Data type: Boolean/string Example: 1 Is used to set the XML prolog under the Doctype declaration—a workaround for some browsers. xmlprologue Data type: string Example: none Serves to remove the prolog
htmlTag_setParams Data type: string Sets attributes of the tag; when the doctype is set, every thing is already correctly defined. This property can be used for any inconsistencies. 382
5.13 Future and Prospects
htmlTag_langKey Data type: string Example: en{-US} Enables the language value to be set for the xml:lang and lang attributes in the tag, if config. doctype= xhtml has been set. htmlTag_dir Data type: string Example: rtl | ltr Sets the direction of the text flow, e.g. for Arabic or Hebrew. removeDefaultJS Data type: boolean/string Example: external | 1 JavaScript is either moved elsewhere or removed completely. inlineStyle2TempFile Data type: boolean Example: 1 The inline style definitions are moved to separate files. xhtml_cleaning Data type: string Example: all | cached | output Provides a workaround, e.g. for extensions.
5.13.2 Accessibility In Germany, for example, the BITV (Barrierefreie InformationstechnikVerordnung Ordinance on Barrier-Free Information Technology) came about as a consequence of the Act on Equal Opportunities for Disabled Persons. The BITV applies initially only to Government Offices. On a Federal level, this Ordinance has to a large extent been put into practice. By the end of 2005, all Federal and many State institutions must have accessibility websites, accessible for the physically impaired. The primary aim is to provide physically impaired people with equal possibilities of accessing information. Even those with minor impairments, 383
5 TypoScript
such as being short-sighted or color-blind, should benefit from this. A further positive side effect is the general improvement in the usability of websites, which is for the good of all. Here is a summary of these guidelines, in accordance with the most recent accessibility guidelines of the W3C Consortium WCAG2.0 (not yet officially released). Accessibility websites must, for people with disabilities, be:
•
Perceptible (alternative content such as alt attributes for images)
•
Usable (with a wide range of devices and physical restrictions, navigable, orientation aids)
•
Comprehensible (language, abbreviations)
•
Robust (conform to standards)
In practice, these guidelines concern all those involved in contributing to the creation of a TYPO3-based website: core code developers, extension developers, website developers, and editors. Much has already been done in the core, but there remains much to be done for extensions. But a great deal of responsibility lies in the hands of web developers and editors. The most important practical adjustment for web developers is the banning of layout control from (X)HTML. One of the consequences of this technique is managing without tables as a layout method. Both basic layout and highlighting and other design techniques are primarily implemented on the CSS level. HTML merely takes over the structuring of the document, which is why the source code of all accessibility pages looks surprisingly similar. Example: On a conventional HTML page, many web developers mark headers with elements such as font-size and font-weight. A screen reader does not know what to do with such markups. But if the headers are marked with h1-h6 elements, screen readers recognize them as such, and for better orientation in a large document, for example, might only read out the headers at first. Apart from the properties already mentioned above regarding standard conformity and declarations, there are also a number of special control options on the TypoScript level that concern accessibility. Here are a few examples: The following settings should switch off the JavaScript function in menus, in order to prevent the ugly border around linked images that can be seen when they are clicked on. 384
5.13 Future and Prospects noBlur = 1
The function is quite harmless in itself. Unfortunately it has the effect that you can no longer navigate with the tab keys, so it must be removed. The link from form labels to the respective form elements must be clearly structured. XHTML provides a label element for this. With the form property accessibility = 1
we activate the functionality that automatically create labels and links them to the corresponding input elements. An example of the result: Your Email:
Inconsistencies with the predominant language can be specified in the TypoScript code: parseFunc.short.Browser = <span xml:lang="en" lang="en">Browser
This results in better legibility when using screen readers. Inside menus, you can use accesskey = 1
to create attributes for defining access keys that enable navigation with keyboard commands. The practical use of this HTML attribute is controversial. In TYPO3, keyboard shortcuts are created with the first letter of the respective menu items. This is a particular problem because many keyboard shortcuts are already reserved by the operating system and the browser. The opinion is widespread that merely the numbers 0 to 9 should be used as access keys for offering central navigation options. This functionality cannot be implemented by this TypoScript property, however, which is why its use is not recommended.
Missing Adjustments in the TYPO3 Core Complex HTML tables and complex forms that meet the Accessibility Guidelines cannot yet be displayed. In such cases the web developers/administrators should store the correspondingly prepared contents statically as HTML content in TYPO3. It can be assumed that standard conformity and accessibility will play a more important role in creating websites in future; the effects of this on TYPO3 are being investigated by the TYPO3 Accessibility Project.
Softlink 563588
385
5 TypoScript
5.13.3 TemplaVoila Softlink 003991
A number of new concepts are introduced in TYPO3 with TemplaVoila 12, which in their interaction represent not just a new template system. Apart from the possibility of preparing HTML templates from a back-end module, new content types can be created that can be used flexibly, and are not restricted by the structure of a database table. In addition, the concept of columns is torn up; areas can be defined so that they only accept certain content types, which is supported by a new page module. As already mentioned, the development of TemplaVoila is not yet complete, but the extension is nevertheless a powerful tool, which has already proven itself in production situations, and which will be introduced here in an overview. A more detailed introduction can be obtained by the softlink to the tutorial "Futuristic Template Building". Even if TemplaVoila may seem to fit like a glove into the application, it consists of many different components, some of which can be used on their own. To illustrate the new possibilities, the components will be introduced separately, but TemplaVoila must nevertheless be seen as the sum of its parts.
Visual Template Mapping A fundamental function of TemplaVoila is the convenient processing and integration of HTML templates. The function is similar to the Template Auto-Parser, except that the areas that are to be used or replaced in the template can simply be chosen by mouse click, using a back-end module.
12 The name is intended as a pun on the fact that an HTML template can be created
in TYPO3 in a very short time. The correct name ought to be "Templat Voilà", which comes out in translation as: "there's your template already!"
386
5.13 Future and Prospects
Figure 5.100: Areas in HTML templates are selected with TemplaVoila by mouse click and configured
Data Structures (DS) and Template Objects (TO) After the mapping of TemplaVoila, the configuration of the HTML template is saved in two XML data structures (DS and TO) and apart from the information on the areas selected, also contains information on what type of objects or data these areas can take in. Data structures (DS) and template objects (TO) are separate definitions, but make use of each other. Data structures contain an abstract definition of areas, fields, and field types, comparable to the definition of the fields in a database—just with a few additional "gimmicks". Template objects refer to a DS and define the output of an element of the DS. A TO, for example, contains information concerning which HTML files are to be used for rendering and which fields from the data structure are to be used at which points in the HTML structure. Multiple TOs can be defined for a DS; the basis for the different output variations. There are still more areas where DS and TO can be used. A DS is used both for the definition of base layouts and of content types. It is also possible to integrate TypoScript into TOs and providing dynamic options for content types that in themselves are rather inflexible.
387
5 TypoScript
The following DS (abbreviated) defines a field for selecting image files () and at the same time includes a TypoScript setup for rendering images (). ROOT <description> <eType>input array <el type="array"> An image <eType>image 10 = IMAGE 10.file.import = uploads/tx_templavoila/ 10.file.import.current = 1 10.file.import.listNum = 0 10.file.maxW = 150 10.params = align="right" group file gif,png,jpg,jpeg <max_size>1000 uploads/ tx_templavoila <show_thumbs>1 <size>1 <maxitems>1 <minitems>0 Bild <section>0
388
5.13 Future and Prospects
Template Selection and Rendering The simplest TypoScript setup for displaying the content of the Normal column looks like this: page = PAGE page.typeNum = 0 page.10 < styles.content.get
A base layout is completely missing here, and only the data records of the normal column are displayed by means of the default configuration for the included standard template (e.g. content (default)). TemplaVoila takes a different approach, taking over the rendering of a page completely. A corresponding TypoScript setup appears as follows: page = PAGE page.typeNum = 0 page.10 = USER page.10.userFunc = tx_templavoila_pi1->main_page
No inclusion of columns is necessary here, because the definition of the content areas (columns or similar) is defined in the DS. This is selected in the page header for the page or for a partial page tree. A TO is chosen that matches a DS, so that the layout of the page is defined. The rendering process with TemplaVoila looks something like this:
•
Search for a DS and TO in the Rootline.
•
Output the template.
•
For the individual areas of the DS that can accept content elements, read information on matching data records from the current page record.
•
Render the content elements and display them in the areas.
•
Because content elements can also contain areas, which in turn can take in content elements, render these as well.
You can define in the page header for each page which DS and which matching TO should be used. In this way you can specify which areas are available for content, and how these areas will then be displayed.
Assigning Content to Pages Surprisingly, content that is entered in a conventional way is not automatically displayed with TemplaVoila. In the page module of TemplaVoila such content appears as "unused records". 389
5 TypoScript
Normally the association of content to a page is defined simply by its records being located on the page (table field pid). TemplaVoila, on the other hand, saves information on the affiliation of a content element to a page in the page record itself. This means that content elements in the page can originate from any other pages, and can be used many times without the need to create a copy of the element or integrate this into the page, with Insert record. But for reasons of clarity, content is saved, as before, in the pages in which it is displayed.
Flexforms Flexforms are another way of entering and saving data in TYPO3. They are already implemented in the core, but are used extensively by TemplaVoila. Apart from the typical CMS use of TYPO3, the system is primarily a webbased database management system. In principle, all kinds of records can be processed with the help of TYPO3. But this is always limited by the structure of the corresponding database table. The tt_content table, which serves to save various content types such as Text , Image, Table, or Form can be used flexibly—different content types show forms of varying sizes—but this is really just a trick, since each record saved contains all the fields of the other content types, even if these are not used. If you want to store additional data in a record, the database table must be extended. Flexforms provide a solution with which you can use practically as many fields as you wish in a record. In addition to this, each record can use other fields. Because TYPO3 is built on a relational database system (e.g. MySQL) that cannot handle such data, a trick is needed here. The trick consists of using a sufficiently large database field in which data can be saved in its own format.
Figure 5.101: Content element with Flexform and RTE
Consequently Flexform data can also be saved in normal records. In extreme cases, the table used could only have one field for content, which 390
5.13 Future and Prospects
is used to save data. However, corresponding fields can also be used several times and mixed with conventional fields. The already familiar data structures (DS) are also used for Flexforms, and they define what field types can be used in a Flexform. The same options as for TCEForms are therefore available in the data structure. The following XML code, for example, shows a corresponding extract from the DS for the definition of a text field with RTE integration. Newstext <eType>text <proc type="array"> 1 text 48 5 Text of mesage <defaultExtras>richtext[paste|bold|italic|underline| formatblock|class|left|center|right|orderedlist| unorderedlist|outdent|indent|link|image] :rte_transform[flag=rte_enabled|mode=ts]
The Flexform data itself is also saved in an XML format. As you can see, the basic components for XML processing already exist in TYPO3. A question that one may ask is whether only Flexforms should be used for data processing. The answer is that the data in the database cannot be easily browsed or selected. The database cannot handle the stored XML data, and cannot distinguish content from the surrounding XML code. So Flexforms are not really suitable for data that needs to be selected on the basis of its content. Flexforms are also available independently of TemplaVoila.
Flexible Content Possibilities of visually mapping HTML templates, the use of DS, and the possibilities of Flexforms are used by TemplaVoila to introduce new and flexible content types, in addition to the static types, Text , Text w/image, 391
5 TypoScript
etc. Here the developer can define a new content type quite easily from an HTML template that is immediately available for processing, and is also displayed correctly in the front end. In addition to this it is possible to define areas so that they can occur multiple times, such as for content elements, in which up to three links with descriptions can be created. Flexible content types can also be used without an output template and even without TemplaVoila—in this case just the Flexforms are used. Only a data structure (DS) is necessary for this; a template object (TO) is not needed. Because TemplaVoila is dependent on an HTML template to create data structures, it is a good idea to make a simple template, even if this will not be required later.
Restrictive Content Although the new content type is called Flexible content, the same concept can be used for very restrictive content types. Together with TemplaVoila's new Web | Page module, a content area of the template can be defined in such a way that only two specific content types should be created there, for example. If these two content types are defined specifically for this area, you have a solution that will show up defective content input, thus guaranteeing a universal layout for the entire website. This is the opposite concept to what TYPO3 has used so far, in which editors had much freedom. Both methods can be combined in any way you like, of course.
Content Areas Instead of Columns Even if the concept of columns continues to seem practical and satisfactory, with TemplaVoila you are no longer restricted to this division. Even without TemplaVoila you are certainly in a position to edit and include content for specific areas, since any number of columns can be added and used. But it becomes more and more difficult for editors to retain an overview, the less the layout is based on columns.
392
5.13 Future and Prospects
Figure 5.102: Editing content with the page module
For this reason, TemplaVoila contains a new page module, which, in its last extension stage, is intended to display the layout of the page schematically, so that individual areas can easily be chosen for editing. In addition, rules can be set up to control the use of certain content types in individual areas.
Using TemplaVoila If you look at these capabilities as a whole, it can easily be seen that TemplaVoila is especially well suited for websites that frequently have changing layouts or whose layouts are divided more into areas and columns, and which use many different content types. TemplaVoila in fact originated in the context of just such a project. The project contained a workflow in which a web designer had to produce precisely defined custom content elements in a WYSIWYG procedure, on the basis of HTML templates. A case study was made of this project, which can be reached through the softlink shown here.
Softlink 673845
As you can see in Figure 5.103, a fixed column is not used in the website. The possibility of using various templates, each with different content areas, is used extensively in the website.
393
5 TypoScript
Figure 5.103: TemplaVoila in productive use
TemplaVoila is a powerful tool for content and template design, and for an alpha version, is not bad at all. It will certainly be developed further, so that missing functions will be included and new functions added, but even now its development has created several basic innovations that can be used purposefully, even without TemplaVoila.
394
6 Extensions 6.1 Overview An essential feature of the TYPO3 framework is its extendibility using socalled extensions. These are easy-to-install packages that can contain modules, plugins, TypoScript, and much more. Extensions are installed online, by means of the Extension Manager, from a central directory, the Extension Repository. Extensions were introduced in TYPO3 version 3.5. Even before this version, it was possible to expand the system via interfaces. Those extensions whose database tables begin with tt_ originate from this period. Although these extensions were available, installing them was a costly business, involving different configurations in various system files. There was also a danger that extensions might clash with one another. With the introduction of the extension system, a clear interface for installing extensions was created. In addition, the already existing interfaces were bundled, allowing decentralized further development of TYPO3 for the first time, giving this a shot in the arm. Since the extension architecture and the Extension Repository have been available, the number of such extensions has increased rapidly. Extensions are published both by ambitious hobby developers and by professional web service providers, and are freely available. In part, these are small functions and improvements, but in many cases, there are also entire applications such as a press archive, library administration, event calendar, or hotel booking system. The extension system provides not only the convenience of being able to install extensions easily via an administration interface—the already mentioned Extension Manager—but also security and a clear structure for developers, one which also guarantees the update capability of the core. Extensions play a central role for users and developers in TYPO3.
6 Extensions
6.2 The Extension System The Extension system consists of several interlinking components: Extension API Interface to the TYPO3 core, enabling integration of extensions into the TYPO3 system Extension Manager Back-end module for the administration and installation of extensions Extension Repository Central online directory allowing extensions to be uploaded and downloaded These components form the basis for extensions—but what do they look like in concrete terms?
6.2.1 The Structure of Extensions An extension consists of several files within a directory. The name of the directory is simultaneously the extension key for this extension. Subdirectories are used for components (plugins, modules etc.) of this extension. Here is the directory tree for the mininews extension. mininews/ doc/ manual.sxw wizard_form.dat wizard_form.html ext_emconf.php ext_icon.gif ext_localconf.php ext_tables.php ext_tables.sql ext_typoscript_setup.txt icon_tx_mininews_news.gif locallang.php locallang_db.php pi1/ ce_wiz.gif class.tx_mininews_pi1.php class.tx_mininews_pi1_wizicon.php clear.gif locallang.php tca.php
396
6.2 The Extension System
Only the developer is confronted with the individual files, however, if he or she needs to make direct modifications to the extension. An administrator or website developer does not even get to see these files, or does not need to worry about them, since extensions are installed as packages, as we are about to see.
6.2.2 Extension Key The directory name of an extension defines its extension key, and this key in turn forms the basis when naming files and program code within the extension; this means that renaming the directory (or the key) would also entail renaming files, as well as modifications to the program code. Because extensions also share an installation directory, an extension key must have a unique name. At the same time, a unique namespace is defined by the key, helping to avoid conflicts in the system. To guarantee extensions their unique namespace, the extension keys have to be registered in the TYPO3 Extension Repository (TER). This will be explained later on.
6.2.3 Extension Components An extension may contain the following components and expand the system accordingly: •
New database tables * 1
•
Extension of existing database tables *
•
Database tables with static data
•
Front-end functions
•
TypoScript *
•
Content elements *
•
Front-end menu *
•
TypoTags *
•
Front-end plugins of various types *
•
Back-end functions
1 Components marked with * can be created with the Extension Kickstarter, simplify-
ing the development of such extensions to a large extent. The Kickstarter is described in detail in Chapter 7.2
397
6 Extensions
•
Back-end modules *
•
Context menu entries *
•
PAGE and USER TSConfig *
•
Services *
•
Libraries
•
System configuration
•
Back-end skins (colors and icons)
•
Extension/modification of each PHP class in the system
6.2.4 Extension Categories Extensions are arranged in certain basic categories, according to their place in the TYPO3 architecture. These categories are shown in the Extension Manager and basically correspond to how they are divided up technically. A further categorization is applied in the Extension Repository, describing the usage of the extension. These are categories such as communication, eCommerce, skins, administration, and others. Back end Extensions listed in this category expand the functionality of the back end, but do not appear as separate modules. Back-end Modules Back-end modules are listed here; these are new main modules (e.g. Web, Tools), modules (e.g. Web | List) or submodule functions (e.g. Web | functions | Import). Front end Extensions from this category contains small front-end functionalities or configurations (meta-tags, new TypoTags). Front-end Plugins This category contains all extensions that expand the display and functionality of the front end, for example content elements, menus, text borders, or complete front-end applications (guestbook, news, etc.). Miscellaneous Here you will find everything that doesn't fit into other categories, such as static database tables, functions for creating PDF files, or programming libraries. 398
6.2 The Extension System
Services This category contains functions that can be used by other extensions or by the system and represents a further extension interface that can be categorized beneath extensions in terms of complexity. Templates Complete TypoScript site templates as extensions are grouped together in this category. These correspond to the site templates included in TYPO3, which can be found in template records under Static templates. Examples Category for examples of all types; usually extensions that are constructed in tutorials or which illustrate the use of an API. Documentation This category contains pure documentation extensions based on OpenOffice documents.
6.2.5 Installation: System, Global, and Local Extensions can be installed in three different directories in the system: typo3/sysext/ (type: System) System extensions such as cms and lang can be found here. No extensions can be installed here with the Extension Manager. typo3/ext/ (type: Global) This is where global extensions are kept. These are normally ones that are supplied by TYPO3. These extensions contain mostly back-end modules and provide basic or extended functionality that is required or useful for most TYPO3 applications. It is possible to set the option allowGlobalInstall with the Installation Tool to allow extensions to be installed in this directory. This is not possible with the default settings, because version conflicts could arise in an environment where several TYPO3 websites share a TYPO3 installation. typo3conf/ext/ (type: Local) All extensions are normally installed in this directory. These are referred to as local extensions, since they are only valid for the 399
6 Extensions
local TYPO3 instance. In fact they even have precedence over global extensions. This means that where an extension is installed both globally and locally, the local one is always included in the system, even if it has a lower version number than the global extension. Multiple TYPO3 instances (websites) can share a TYPO3 installation by using symbolic links, through which they also share global extensions. But local extensions are always only visible for that particular website.
6.2.6 Extension Repository Softlink 617220
In the TYPO3 Extension Repository (TER), extensions are stored centrally and can be downloaded to your own TYPO3 installation and installed. The Repository can be found at TYPO3.org. Developers can transfer an extension to the Repository with just a few mouse clicks in the Extension Manager. The extension is then available for download to specific users, or to the public, depending on its configuration. Downloading an extension is just as simple, and can also be done with just a few mouse clicks.
FIgure 6.1: Overview of extension categories in the TER on TYPO3.org.
400
6.2 The Extension System
When an extension is downloaded and installed, the list of available extensions in the Extension Repository of TYPO3.org is obtained and displayed, using the Extension Manager module in your own TYPO3 installation. When an extension is selected and downloaded, the Repository sends a single file (file extension .t3x), containing the complete extension directory with all the necessary files, to the Extension Manager in the local installation. This unpacks the package into the extension directory. It is now ready to be installed by the Extension Manager. During installation, certain files within the extension directory are detected, read, and included in the system. The Extension Manager also provides installation functions for setting up the required database tables or offering the user a selection of configuration options. The reverse path, that is, uploading an extension to the Repository, functions in a similar way and is explained in Chapter 7, in section 7.3.3. The installation process is very simple and convenient for the user: if an extension is installed he or she can find information on the files contained, but this is not necessary. You can see that an extension is installed from the green icon in the Extension Manager in the Loaded Extensions view or Extensions available to install. At the time of going to press, over 900 extensions are freely available. A large number of registered extensions in the Repository are not public, however. This may be because they were never completed properly, because developers are still improving the code, or because no documentation exists. We would like to point out, however, that Open Source projects live from the active contributions of users, and that it is a shame about some of these unpolished diamonds, which, if they were published, could indeed be given a sparkle by many different hands! It is also much easier to find help and sponsors if you already have a corresponding beta version or a project description. 2
6.2.7 Documentation In the TER you will also find the entire documentation of TYPO3, kept in the form of OpenOffice documents. These are extensions that only contain documentation, and which belong to the Documentation category. The documents are available on TYPO3.org as HTML pages in the "Documentation" area, and you can also add comments there.
Softlink 280413
2 Project descriptions can be found in the Projects area on the TYPO3.org website along
with present projects that are still looking for help and sponsors. Project descriptions can be written by anyone and are an effective way of introducing ideas and concepts and getting them moving on TYPO3.org.
401
6 Extensions
Apart from these documentation-only extensions, which usually contain references and tutorials, there may, and should, be specific documentation for every extension. The same system is applied here as for the documentation extensions, except that these extensions also contain a plugin, module or other data. The extension-specific documentation can, if required, be downloaded from the Repository, together with the extension. This can then be found in the OpenOffice file manual.sxw in the doc/ subdirectory of the extension. Using OpenOffice documents has some advantages over other options, such as HTML, PDF, or DocBook: •
It is easy to write, using a powerful and freely available word processor.
•
Printout of OpenOffice .SXW files in the desired format is possible
•
PDF files can be created directly from OpenOffice.
•
The open, XML-based file format of OpenOffice is simple to read and convert (to HTML, for example).
•
Documentation can be displayed directly as HTML within TYPO3.org, using the Document Suite.
6.3 Extension Manager The Extension Manager (EM) is a back-end module for the administration of extensions. The module is located in the Tools main module, which means it is normally only accessible for administrators. The functionality of the Extension Manager includes: •
Listing the installed extensions
•
Listing available extensions
•
Installing and removing extensions
•
Transferring extensions via a T3X file to your own installation
•
Transferring extensions from the online repository (TER) to your own installation (download)
•
Uploading your own extensions to the TYPO3 Extension Repository
•
Developing your own extensions (Kickstarter)
In the following section we will introduce individual views and their functions. 402
6.3 Extension Manager
6.3.1 Listing of Available Extensions This view displays all the available extensions in the TYPO3 installation. They are listed in the table with additional information. The +/- icon at the beginning of each line shows whether an extension is installed (green). Clicking on this icon will install or uninstall the corresponding extension.
Figure 6.2: The extension manager shows the available extensions
Each extension is displayed with its name and its own icon. Some of these have a question mark as an icon if the developer of that extension has not yet made its own icon. The next details displayed are the extension key and version number. In the next column a document icon may appear. This means that an OpenOffice manual.sxw file exists in the doc/ subdirectory of the extension. The documentation can also be obtained from TYPO3.org in the list of extensions. It is possible for an extension to be installed both globally and locally. Such a double installation is marked in the EM as Local GL. In this way, the locally installed extension can be modified to your own requirements, and you can be sure that this will be included in the system, and not the original version.
403
6 Extensions
6.3.2 Importing Extensions from the Repository Extensions can be imported simply from the Online Repository into your installation. To do this, select the Import extensions from Online Repository option in the EM main menu.
Figure 6.3: Connecting to the Repository and transferring an extension package file to the server
Before we look further at transferring extensions from the Repository, we will briefly discuss how an extension package file (*.t3x) under Upload extension file directly is transferred to your server. This is done by selecting the T3X file and installation directory, and then transferring the file to the server by clicking on Upload extension file. The installation itself corresponds to accepting data from the Repository, and is described below. You can access the Repository by clicking on Connect to Online Repository. A connection is made to the Repository and a list of available extensions is obtained. Also, in the lookup input field, you can specify a key with which you can access special versions of an extension. Such a protected extension version is not public, and is only accessible by specifying the key. This is useful if you want to make an extension available to testers in a development team. The list obtained from the Repository contains other information apart from the data already mentioned. The first column shows download icons if this extension is not yet available on the local server or if a newer version is available. In the middle column you can compare version numbers. The Access column shows if you are the Owner of the extension or a Member. Members of an extension can download it, even if it is not freely available in the Repository. The various states (locally available or not available, Owner/Member) 3 are also highlighted by table lines in different colors. 3 Member functions are only present if you have a user account on TYPO3.org and you
have entered access data under Settings in the EM.
404
6.3 Extension Manager
Figure 6.4: Listing the available extensions in the Repository
In all List Views, you can have so-called "shy extensions" made visible, that is, those that make up the basic package and which are available in most installations. Different List Views can be accessed through the menus Order by and Show. If you have decided to download an extension, it is first transferred to your server, but not yet installed. To do this, click on the + icon, which is shown in the view after a successful download. Alternatively you can install the extension in the Available extensions to install view using the + icon.
Details View and Options If you want to take a closer look at the extension before you download it, click on its title. You will now see a precise overview giving details such as title, author, version, but also the files and database tables it contains. In the Details View you can select the version to be downloaded. If the option allowGlobalInstall in the $TYPO3_CONF_VARS (Installation Tool) is enabled, you can also select the path to the global extensions in typo3/ext/ for installation. If the option em_alwaysGetOOManual is also enabled, the documentation for the extension is automatically downloaded as well, which would otherwise have to be enabled separately in this view. With the Include most recent translation option, you can include all available translations in the extension. This is useful if the developer has not yet included the desired translations, which are made available via the TER, in the current version. 405
6 Extensions
Depending on the extension type and the modules and plugins contained, one or more steps are necessary for the installation. Some extensions can be installed with a single click. For others, you are asked if you want to perform the necessary installation steps, when setting up additional database tables or deleting caches, for example. It is sometimes necessary to make and change settings during the installation. Parameters that can be set are explained either then and there or in the documentation for the extension.
Figure 6.5: Details View of the extension with the example of the General Office Displayer
After modules have been installed, however, they are not immediately visible in the back end. For this to happen, the back end must be reloaded, by clicking in your browser on the reload button. Uninstalling extensions is done in a similar way, by clicking on the green "–" icon. Ensure that database tables required only by this extension are not automatically removed. This is an advantage if you want to keep the data. Over time, however, many unused tables could collect in the database. These can be removed with the installation tool, which has already been introduced.
406
6.3 Extension Manager
6.3.3 Extension Kickstarter The Extension Kickstarter is the tool for extension development, enabling the base framework for an extension to be created quickly and simply. The Kickstarter is stored in a separate extension (Extension Repository Kickstarter:kickstarter); if it is not available in your installation, then first load the extension. If it is installed, the Kickstarter appears as the Make new extension menu item in the Extension Manager.
Figure 6.6: Extension Kickstarter is ready to start a new extension
How to use the Kickstarter and functions of the Extension Manager relevant to developers are described in the next chapter.
407
7 Extension Development TYPO3 is a framework for web applications. This framework can be expanded, adjusted, or even completely changed, on the basis of extensions. At its core, TYPO3 is a web-based database management system. This can be seen, for example, by the fact that the CMS is implemented as an extension, that is, it is an application of TYPO3. This separation between core and application reduces complexity and makes it easier to continue developing the system. This is made possible by a defined and structured Extension API. In addition, each extension has its own namespace. Taken together, this prevents conflicts and makes it possible to extend TYPO3 in almost every direction. The Extension Manager has already been introduced in Chapter 6. We showed what type of extensions exist and how these can be installed online. In this chapter we want to look at how you can program the various types of extensions (plugins, modules, ...) yourself. To do this you require a solid grounding in PHP, object-oriented programming, and SQL. Even if your knowledge in these areas is not so extensive, you should not be afraid of reading further, because TYPO3 is very well suited as a basis for delving deeper into PHP and SQL. In this case it is recommended, however, that you have documentation to hand that goes into more detail. We should point out here that this is an introduction to the subject of TYPO3 development, and it can merely provide an overview. Even though the Extension Kickstarter takes over a large part of the work from the developer, it will still be necessary to get to grips occasionally with the documentation. Most sections contain a soft link at the beginning, referring to further literature.
7 Extension Development
7.1 A Visitor Counter in 20 Minutes To explain how quickly and easily TYPO3 can be expanded, we are going to program a simple plugin below. Since this is merely to give a general overview, more detailed explanation will not be given in the example. The example is of a visitor counter, the invention of which probably brought joy to millions of homepage owners, out there in the Web holosphere. The plugin uses a database table to save the status of the counter. The counter should count each visitor exactly once; this is done with the help of the user session, created and managed automatically by TYPO3. This means that a visitor is only counted once, even if he or she calls the same page several times within a session. Normally a plugin is inserted into a page via an Insert Plugin content element and enabled; but we will see that there are other ways of using a plugin. The plugin should be ready in 20 minutes. So let's get started! We have called the back end and now select the Extension Kickstarter, which can be reached in the Extension Manager via the make new extension entry. First an extension key must be specified. We will use user_visitcounter. The form is then updated, with Update. An extension can contain several elements: plugins, modules, database tables etc. First the General Info element is added, which contains general information about the extension under General Info. The form is completed, and a click on Update accepts the entry. The counter needs a database table to be able to count; we create this with New Database Tables.
410
7.1 A Visitor Counter in 20 Minutes
Figure 7.1: General information on the extension under General Info
The table must be given a descriptive name, which is later displayed in the back end. We will call it Visitor Counter. Behind the entry field, the word [English] appears. This reminds us that we want to have descriptions in other languages as well. We add the German language to this extension by clicking on Setup Languages and selecting German.
Figure 7.2: Editing additional languages with the Extension Kickstarter
But the table is not yet finished, and needs further processing. We select the Visitor Counter table from the New Database Tables menu item, which is already listed now as a component of this extension. We can also specify a German title now.
411
7 Extension Development
Figure 7.3: New database table with English and German titles for display in the back end
In addition we add another field to the table, where the counter status will be stored.
Figure 7.4: Adding a field to the table
A few options still need to be set, as can be seen from the following figure, and then the table is finished.
Figure 7.5: Options in the table differing from default values
Now we insert a plugin to the extension, specify the titles in English and German, and set a few more options.
412
7.1 A Visitor Counter in 20 Minutes
Figure 7.6: The plugin and other components are added to the extension
Finally we add Static TypoScript code and have a look at the result with View Result. The extension can then be created in the typo3conf/ ext/user_visitorcounter/ directory, with WRITE.
Figure 7.7: The extension is finished and can be generated
Kickstarter creates the entire code for a plugin and the database table. We can install this extension immediately with the Extension Manager, edit the new table in the back end and select the front-end plugin (which will only display example contents, however). 413
7 Extension Development 3.39
That's it, for starters, at least. In less than four minutes, the basic framework for the visitor counter can be up and running. But the plugin does not count any visitors yet, of course. We now move to a PHP development environment and remove the code and files that are not needed for this simple plugin. The following files should be deleted: pi1/locallang.php and ext_typoscript_editorcfg.txt
In the file ext_localconf.php the code lines integrating the file ext_typoscript_editorcfg.txt are deleted. A file named ext_typoscript_setup.txt is created. This will later contain standard TypoScript code for the plugin. The file tca.php contains definitions that are necessary to be able to edit the table in the back end. In Kickstarter we selected the integer, 10=1000 type for the counter field. This does not quite match what we need, so we will change the field definition as follows: 'counter' => Array ( ... 'config' => Array ( 'type' => 'input', 'size' => '5', 'max' => '10', 'eval' => 'int', 'default' => 0 ) ), 5.20
Then we edit the file pi1/class.user_visitcounter_pi1.php, which contains the PHP code for the plugin, and remove the example code from Kickstarter. We can now start to implement the counter. require_once(PATH_tslib.'class.tslib_pibase.php'); class user_visitcounter_pi1 extends tslib_pibase { var $prefixId = 'user_visitcounter_pi1'; // Same as class name var $extKey = 'user_visitcounter'; // The extension key. /** * Main plugin function **/ function main($content,$conf) { // We do this, because it's a USER_INT object! $this->pi_USER_INT_obj=1;
The function main is later called by the front-end system to create the 414
7.1 A Visitor Counter in 20 Minutes
content for the plugin. First the variable $table is set; this is needed quite frequently and makes the code reusable. $table = 'user_visitcounter';
The counter should create a record on the current page; we leave it to TypoScript to find out the ID of the page through the pid parameter. $pid is set to the current page ID, which is also available via $GLOBALS['TSFE']=>id if this does not work. // any page id configured? $pid = intval($this->cObj->stdWrap($conf['pid'], $conf['pid.'])); // if not use current page $pid = $pid ? $pid : $GLOBALS['TSFE']->id;
We know the page ID and search for a counter record. If none is found, we create a new array and set the counter to 0. // search for counter record $res = $GLOBALS['TYPO3_DB']->exec_SELECTquery('*', $table, 'pid='.$pid, '', '', 1); if ($res) { $row = $GLOBALS['TYPO3_DB']->sql_fetch_assoc($res); } else { // initialize a new counter $row = array(); $row['counter'] = 0; }
We now look to see if the user is already known, and if not, the counter is increased by 1. A check is made to see if the extension key exists in the user session, if not, it is set, and the session data is rewritten. This means that the counter counts visitors per session. // check if this user should be counted $knownUser = $GLOBALS['TSFE']->fe_user-> getKey('ses', $this->extKey); if (!$knownUser) { $GLOBALS['TSFE']->fe_user->setKey('ses',$this-> extKey,1); $GLOBALS['TSFE']->fe_user->storeSessionData(); $row['counter'] += 1; }
415
7 Extension Development
Now the counter record must be updated, or created if it does not exist. // update the counter record if ($row['uid']) { $this->cObj->DBgetUpdate($table, $row['uid'], $row, 'counter', true); } else { $this->cObj->DBgetInsert($table, $pid, $row, 'counter', true); }
To display the counter, we create an instance of tslib_cObj 1, which is the main rendering class of the front-end system and will be explained later in more detail. The method cObjGetSingle() is used to render the content, causing the TypoScript setup renderObj to be passed on. Afterwards the created contents are returned. // render the counter with the TypoScript renderObj $lCObj = t3lib_div::makeInstance('tslib_cObj'); $lCObj->setParent($this->cObj->data, $this->cObj->currentRecord); $lCObj->start($row, $table); $content = $lCObj->cObjGetSingle($conf['renderObj'], $conf['renderObj.']); return $this->pi_wrapInBaseClass($content); } } 17.04
The
following
TypoScript
setup
is
inserted
into
the
file
ext_typoscript_setup.txt, which identifies the page ID and defines the rendering for the counter with renderObj: plugin.user_visitcounter_pi1 { pid.data = page:uid renderObj = COA renderObj { 10 = TEXT 10.field = counter 10.noTrimWrap = || | 20 = TEXT 20.value = visitors on this page } } 19.46 - Finished
Of course, we cut a few corners, since the time for debugging was not 1 Section 7.5.5 explains why an instance is created, instead of $this->cObj being used.
416
7.1 A Visitor Counter in 20 Minutes
included here. But the example still shows how, with Kickstarter and a bit of experience, you can quickly achieve results. The special feature of this counter is that it can be configured by TypoScript. This is a general concept in TYPO3, which ensures as high a level of flexibility as possible. With the TypoScript set up, the plugin is both configured and its rendering defined. Both can be changed, without having to make adjustments to the PHP code. The plugin is configured by defining the page ID on which the counter record should be located, with pid. You could just set the current page ID in the PHP code: $pid = $GLOBALS['TSFE']->id;
Instead of this, an attempt is made to get an ID via TypoScript: $pid = intval($this->cObj->stdWrap($conf['pid'], $conf['pid.']));
The TS setup of pid is passed on to the stdWrap method of the cObj object. This is the very method that the TypoScript stdWrap object provides. If you take a look at the TypoScript reference, you will see what a wide range of options this object has. We will put this to good use. The following two bits of code are equal in their end result: // PHP: $pid = $GLOBALS['TSFE']->id; // TypoScript: pid.data = page:uid
By using TypoScript for the configuration, the plugin can be used in different ways. You can, for example write: pid = 12
Here the plugin does not count visitors per page, but visitors for the entire website, by saving the counter status only on the page with the ID=12. Then you should also change the text that the plugin will display. The TS setup necessary for this adjustment would be as follows: plugin.user_visitcounter_pi1 { pid = 12 renderObj.20.value = visitors on this website }
So it is possible, with the help of TypoScript, to change the functionality of plugins to a certain extent (as long as you use this in the PHP code). You can still make other changes: the counter should display a German text, for example. This can be done by redefining renderObj.20.value, or adding the German text as an option. 417
7 Extension Development plugin.user_visitcounter_pi1 { pid = 12 renderObj.20.value = visitors on this website renderObj.20.lang.de = Besucher auf dieser Website }
If the website is correctly configured for the German language, then the German text is displayed automatically. config.language = de
It is somewhat impractical, of course, that although the counter counts visitors for the entire website, the plugin has to be activated on each page with the Insert Plugin content element. This can be avoided by inserting the plugin at a suitable point in the site template. page.80 =< plugin.user_visitcounter_pi1
The plugin will now be performed on every page. Because the plugin itself does not actually perform the rendering of the counter, but only passes on the TypoScript setup from renderObj to cObjGetSingle(), you can use everything that TypoScript has to offer for the output. So, the visitor counter is automatically graphics-capable. To allow the visitor counter to display the output as shown in the following figure, no change in the PHP code is necessary, just a little TypoScript. Figure 7.8: Example counter
Note that the visitor counter is used here in principle just as an example. There are certainly better visitor counters than this one. Creating the counter with a graphic output was also demonstrated only to make clear the connection between PHP and TypoScript. If the counter had really been used in this way, the server would have generated a total of 135,487 graphics, which would need to be deleted at some point.
7.2 Extension Wizard: Kickstarter As the example of the visitor counter has already illustrated, the Extension Kickstarter creates a complete framework, to which the actual functionality has to be added. All extensions created by Kickstarter can be installed immediately, and you already have a "Hello World" output. A saved extension can be reloaded and edited by Kickstarter, but code already entered manually will be lost when saving, since Kickstarter is not an editor for existing extensions, but is only meant to help you get started. Before we can start creating an extension, an extension key must be created.
7.2.1 Defining an Extension Key Every extension has its own unique namespace, defined by the extension key. This key is a short string and can contain the characters a-z,0-9,_. There are two types of extensions, which are differentiated by the key: on the one hand, normal extensions, which can also be published to the TYPO3 Extension Repository (TER), and on the other, project-specific extensions, which cannot be uploaded to the Repository. These are defined by the prefix user_ in the extension key. Normal extensions can have any key they want, but may not start with tx or u. While project-specific extension keys with the prefix user_ can be named in any way you want, this is not the case for normal extensions. These must be registered for them to be unique (see soft link). After registration you have ten days in which to write the extension to the TER, otherwise the key is deleted. If you have not managed to complete your extension in this time, you can still upload it to the Repository, so that the key is not
Softlink 104717
419
7 Extension Development
lost. After registration, the extension is initially marked as Members only, which means: after uploading, this extension cannot be seen by others unless they are registered as members. It is a good idea to choose a descriptive name for the extension key, one which is as short as possible. It should be descriptive, so that you (and others) can recognize from the name of the extension directory what type of extension is involved, and short, because the program code uses this key as a namespace. A long key name would mean long designators in the PHP, HTML, and CSS code. Underscores may be used, but are removed by Kickstarter from certain designators, which can cause confusion. So the simplest way is to avoid using underscores in key names. Once you have defined an extension key, it is entered in Kickstarter in the entry field at the bottom left.
7.2.2 Kickstarter Components An extension is shown opposite containing all the components that can be generated with Kickstarter. You can also see which files were created in doing so.
420
7.2 Extension Wizard: Kickstarter
Figure 7.9: Example extension using all possible components that Kickstarter can create
Individual components can be added with the + icons, and removed with the trashcan icon. If an extension contains several components of the same sort, the directories are numbered accordingly: mod1/, mod2/. The individual components are: General info Basically each extension must contain the General info component. This defines general information on the extension, which will be displayed in the TER and in the Extension Manager (EM).
421
7 Extension Development
New Database Tables New database tables are created with this. With the help of a wizard, fields can be created and field types (string/entry field, integer/checkbox etc.) be defined. Extend existing Tables Existing database tables can be extended with this component, and the same wizard functions are available for field definitions. Frontend Plugins This adds a front-end plugin to the extension. Plugins can extend the front end in different ways. Examples of this are new content elements, menu functions or FE applications. Kickstarter provides a selection of the most common plugins. Backend Modules This option adds a back-end module to the extension. This can be inserted into various main modules such as Web, File, or Tools. Integrate in existing Modules Some modules can be extended by submodule functions. Kickstarter supports this for a series of Web modules as well as for the User | Tasks module. Clickmenu items Entries can be generated in the context menu with this. Services Creates a service component. Static TypoScript code TypoScript can be added to the extension with this component. After the extension has been installed, the TS code is active systemwide. TSConfig PAGE and USER TSConfig can be added to the extension with
this. Setup languages Both plugins and modules contain support for multiple languages. In Kickstarter, texts (field identifiers, titles, etc.) can be defined in many different languages if the languages are added with this component. 422
7.2 Extension Wizard: Kickstarter
7.2.3 Extension Structure As already described, extensions consist of a number of files and possibly, directories. These have specific functions determined by their filename, or they are included by the Extension API.
Softlink 099886
Since an extension is normally created with Kickstarter, and will therefore already contain all the files and directories in the correct form, we shall only give an overview below of their contents and functions. Where necessary, details are explained in the examples. In addition we would like to point out the soft link to the documentation. ext_emconf.php All general information and metadata on the extension is saved here, generally data from the General info Kickstarter component. ext_localconf.php For each request, this file is included both in the front end and in the back end, and can contain all configurations ($TYPO3_CONF_VARS), as well as typo3conf/localconf.php. In addition, TypoScript can be included through the Extension API. ext_tables.php Database tables for use in the back end are configured here, and plugins and modules are included through the Extension API. The relevant code is generated by Kickstarter and only rarely needs to be modified. ext_tables.sql This file contains SQL data for the table definition. The definition is recognized and evaluated by the EM and the Installation Tool. In this way the EM and the Installation Tool can recognize if a table needs to be created or updated. ext_tables_static+adt.sql Contains SQL table definitions, including data; this is intended for static data, as can be found in the Static Info Tables extension, for example. This contains data on countries, languages, and currencies. The abbreviation "adt" stands for "add drop table" and refers to the -add-drop-table option, which is used when the table is dumped with the mysqldump tool so that corresponding SQL statements can be placed in front of the dump. DROP TABLE IF EXISTS static_countries;
423
7 Extension Development
The table definition itself must also exist in ext_tables.sql for it to be correctly recognized. ext_typoscript_*.txt Contains TypoScript code that is globally integrated, so that it is not just available through template records (see static/). ext_conf_template.txt This file holds definitions of extension configuration options if needed. Based on these definitions, these options are displayed for the user in the EM. *icon*.gif Icon files for the extension, database tables, plugins, modules, etc. locallang*.php These files contain texts in different languages for localising plugins, modules, and TCA definitions. class.*.php Contains PHP classes, for plugins or submodule functions. class.ext_update.php Makes functions available for an update of the extension in the EM; an example can be found in the newloginbox extension. conf.php With this file a module is configured and inserted into the back end. index.php The file index.php is generally the main script of a module. pi1/ The directory containing scripts and data for a plugin. cm1/ This directory contains context menu scripts and data. mod1/ This is a directory for a module. It includes conf.php and index.php.
424
7.2 Extension Wizard: Kickstarter
modfunc1/ Contains scripts and data for submodule functions. static/ This directory contains TypoScript template files that are inserted through the Extension API, and then they are available in template records, in a similar way to static templates. sv1/ Directory containing services. res/ Directory for any kind of data ("resources") doc/ Directory for the documentation; also contains the file wizard_form.dat, in which the entire Kickstarter definition is located. With this information a new extension can be created by Kickstarter, using this extension as a basis.
7.2.4 Basic Rules of Extension Development Components As already described, an extension may contain several components. But not all combinations make sense, for example an extension should only contain the components of one application. An example of an extension with several components could be a hotel-booking extension, with database tables, a plugin to display data in the front end and to allow bookings, as well as a back-end module for the display and administration of reservations. It makes little sense to add a plugin to this extension showing the current news from your local tourist office. This is a separate functionality, and should also be a separate extension. The following rule of thumb applies: unless it really makes sense to have all components installed together in one extension, then they should be split up over several extensions.
Documentation Even though it is certainly not always possible to include complete documentation with an extension, it should at least contain a manual 425
7 Extension Development
(doc/manual.sxw) with the section "Introduction". This section should consist of a description of the function, and if possible a screenshot. There should also be a short description of the type of extension and how it is called or integrated. For a module, this would be a note about where the module can be found after its installation. For a plugin, it should be made clear if this is a new content element, for example, or if it must be integrated into a page using Insert Plugin. In general this description does not need to be particularly long and should only provide an overview. Since the "Introduction" section is displayed in the Details View for the extension in the TER on TYPO3.org, you can already get an idea of the extension from there. Using this information, you may decide that the extension is suitable for the purpose you have in mind. For someone who is interested in a particular extension, this may save a great deal of time spent trying things out. Please note that a manual that is uploaded to the Repository for the first time, as described in section 7.3.5, Publishing Documentation, first has to be initialized. Otherwise the "Introduction" section will not be recognized.
Categories It should be pointed out that extensions have to be sorted into the correct categories. These are the basic categories on the one hand (back end, back-end modules, front end, etc.), which are used for sorting in the EM, and on the other the application-related ones in the TER, which have to be assigned to the extension on TYPO3.org (see section 7.3.4, TER Extension Management). While the basic categories help more to keep a clear picture in the EM, categories in the TER help to find suitable extensions for a specific purpose.
Publishing At this point it should be mentioned once again that all code used in the TYPO3 framework (which is what an extension you have written yourself is) is automatically subject to the GPL license. This does not mean that you have to publish your extension. But bear in mind that several years of work have been invested in this project, and that every contribution that helps TYPO3's progress is in your own interests as well.
426
7.3 Extension Management for Developers
7.3 Extension Management for Developers 7.3.1 Functions of the Extension Manager The Extension Manager provides a number of interesting functions that are very useful in the administration of your own extensions. These functions are available in the Details View of an extension. You can reach the Details View by clicking on the title of an extension in the List View of the EM. A menu is available there containing various functions.
Figure 7.10: Functions in the extended Details View of the EM
Information Detailed information on the extension is listed here. Apart from general details such as title, description, and version number, information is also listed on the files and database tables contained. Where appropriate, any errors within this extension are also shown. These could be violations to the extension namespace, for example, or missing XCLASS definitions (see section 7.10, Modifying and Extending XCLASS Classes). Relevant comments are marked in red. Edit files Here you can edit files of the extension online; this can sometimes be useful to correct small errors on the web server. Backup/Delete A number of functions are gathered together under this menu item, as shown in the following figure. The following sections belong to this item.
427
7 Extension Development
Figure 7.11: Functions of Backup/Delete in the EM
Backup | Extension files: It is certainly very useful to be able to download the extension as a T3X file. This package contains the entire extension, and can be installed again with the EM. In this way, extensions can be sent simply via e-mail, without having to pack all the necessary files by hand into a zip archive. Especially on Windows servers, the PHP extension for (de-)compressing data is frequently not available. For this reason, some extension packages may remain unpacked. You can distinguish the packages from the -z at the end of the filename (*-z.t3x), which identifies a compressed package. Backup Data tables With this function you can download the database table of the extension, if it exists. Delete This function deletes the complete extension from the server, but only if it is not currently activated. Update EM_CONF With this you can update the ext_emconf.php file of an extension. Bookkeeping, so to speak, is carried out in this file on the versions of the files in the extension. This helps to check if files have been changed, thus making it necessary to update the version in the TER. This is shown accordingly in the overview under Information. Before you transfer an extension to the TER you should call this function. 428
7.3 Extension Management for Developers
Make new extension This function allows you to use the extension as a template, and to start a new extension in Kickstarter. There the extension key can be changed and a new extension be assembled as required. But this does not mean that the functionality of this extension is taken over, because Kickstarter creates a new framework where there is no manually written code for the extension currently selected. This function is useful, for example, for creating a new extension with an identical or similar database table to an existing one. Dump DB You can use this to update the database definition in ext_tables.sql. This is useful if you have made changes in the table definition with phpMyAdmin, for example, and want to include these in the extension. Bear in mind that the TCA definitions of the table may need to be adjusted. Upload With this function the extension can be uploaded to the TER. This is described in the following sections.
7.3.2 TER Account Before you can upload extensions to the TER on TYPO3.org, you need to set up an account on TYPO3.org (see soft link). Enter your user name and password in the EM now under Settings. By the way, the EM, with only this access data, can display extensions for which you are a member (Members only).
Softlink 900162
Figure 7.12: Setting access data for the Repository in the EM
To upload extensions, a password is required, which may be different for each extension. If you frequently use the same password, you can enter a standard password in default upload password. The password is defined in the extension key registration, but can be changed again later on. 429
7 Extension Development
7.3.3 Transferring an Extension to the TER To transfer an extension to the TER, you must click on the title of the required extension, in a List View in the Extension Manager, to reach the Details View. Then select the Upload menu and you will see the display as shown in the following figure.
Figure 7.13: Preparing an extension for upload to the online Repository
Normally you only have to select what procedure is to be used with the version number of the extension. This can be incremented automatically by the upload. But increasing the last number of the version number does not lead to it being displayed as a new version in the TER or the EM. This can be useful if only slight modifications need to be made in the documentation, for example, and a new download would not be worthwhile for most users. If an error has been corrected, however, you should select the middle number to increase the version number. If you have chosen a special upload password for the selected extension, you must enter this now. Otherwise the default upload password from Settings will be used. If an extension is transferred for the first time to the TER, it is marked as Members only, and is thus only accessible for registered members. The Private option offers a way of providing the current version of your exten-
sion with a password. This is very practical if you want to have a new version of an already accessible extension tested by selected people, without making it publicly available. 430
7.3 Extension Management for Developers
Clicking on Upload extension transfers the extension. When the procedure is complete, a corresponding message appears. Since the version number in the Repository may have increased, this should also be done in the local version, of course. The update must still be confirmed after the version number has been changed. The transfer to the TER is then finished.
7.3.4 TER Extension Management On TYPO3.org you can manage your extensions in the TER. To do this, you must first log in. If you now select the Extensions main menu item, you can access your own extensions via the additional menu item, My extension keys.
Softlink 156502
An overview will appear, as shown in the following figure. This can be sorted according to various criteria, and contains some statistical data. If you click on an entry in the list, a form appears with some details on the extension and some options for settings.
Figure 7.14: Overview of your own extensions on TYPO3.org
Here you can change the name and description of the extension. The extension can also be sorted into a number of additional categories, which can then be found in the Categories view of the TER. The versions uploaded until now are listed. You can delete old versions; this should be done regularly, to free memory space in the Repository. If the extension contains locallang language files, then there is an overview of translations into other languages. After this the contents directory of the documentation can be configured. More information on this is given in the next section.
431
7 Extension Development
Figure 7.15: Detailed information and settings for an Extension
Members Only An important function consists of restricting access to extensions only to members. This is very useful during the development phase, to allow selected testers to obtain beta versions. As mentioned above, every extension is initially marked as Members only. To add members to an extension, enter their names, or alternatively the TYPO3.org user names, in the entry field under Lookup users. If you send off the form, all the relevant users are listed, from whom you can then choose. To make an extension generally available, that is, to publish it in the TER, the Members only option must be deactivated. This cannot be undone, however. Once an extension is published, it remains so. Individual versions of an already published extension can be hidden if they are uploaded with the Private option, which makes them accessible only to those with the 432
7.3 Extension Management for Developers
appropriate password.
Figure 7.16: Entering members of an Extension
7.3.5 Publishing Documentation Documentation should be available for every extension in the specified format. But this does not mean that extensions without documentation should not be published at all. Where there is doubt, it is more in the spirit of the project to publish an undocumented but substantial work, rather than to let too much time pass by trying to reach the required standard. The documentation can be found in the extension in the file manual.sxw of the doc/ subdirectory. This file contains the manual in the OpenOffice format and is uploaded with the extension to the TER. This system of documentation is used not only for extensions with modules and plugins, but also for general documentation. Pure documentation extensions only contain the files ext_emconf.php and ext_icon.gif, apart from the file doc/manual.sxw. If you do not yet have OpenOffice, you should install it now (download from http://www.openoffice.org). it is a very powerful Office package and is freely available for the Unix/Linux, OS X, and Windows platforms. The advantage of the OpenOffice format lies in its openness. The format is documented and is available as XML. This makes it easy for other software to read and convert it. It is also the reason that documentation is displayed within the website on TYPO3.org automatically after the extension has been uploaded. In order for this to function smoothly, several requirements must be fulfilled. First the manual template is downloaded from TYPO3.org (see soft link) and saved in the doc/ directory as manual.sxw. The template already contains sections with explanations.
Softlink 167050
If you think it will be useful, you can add new sections to the documentation. Since not every section makes sense for every extension, a manual does not have to take over every section of the template. At the end of the template there is another section containing general hints on creating documentation with OpenOffice, which should be deleted entirely. This is a short version of the "Writing documentation for TYPO3" guide (see soft link).
Softlink 600297
433
7 Extension Development
If your documentation is finished, you can also transfer it, by uploading the extension to the TER. It is advisable to at least include the "Introduction" section as an overview of the functionality of the extension. After the first upload of the documentation—or if you have added new sections, you should initialize or update the table of contents on TYPO3.org. This is done by calling the Details View for the extension in the Repository and selecting the Edit TOC metadata option in the doc/manual.sxw section. After you have sent off the form, the table of contents can be arranged. The sections from the template are recognized automatically. The language in which the documentation is written must be assigned accordingly. Even though the standard language for documentation in the TYPO3 project is English, documentation can also be written in other languages. For each section you can also define the target group to which this will be of interest: editors, administrators, or developers. This is done by selecting the icons with variously highlighted layers. You have probably noticed that this is the TYPO3 logo. These levels symbolize the three user roles; the first level (closest to the surface) represents the editor, the middle one, the administrator, and the lowest level (closest to the core), the developer.
Figure 7.17: Editing the content structure of an extension manual
7.4 The TYPO3 Framework With its architecture, TYPO3 represents a framework that can be expanded very efficiently via extensions through its own developments. The modularity of the framework allows the principles of the architecture to be maintained, despite the high level of functionality. This capacity for expansion, which can be used quickly with the help of the Extension 434
7.4 The TYPO3 Framework Kickstarter, has already found many supporters, as can be seen from the
large number of publicly available extensions. The synergy effect caused through the mutual use of functions that are made available by the core of the system and other extensions, helps new developments to achieve a significantly higher level of implementation compared to stand-alone solutions. We will provide an overview of the TYPO3 framework below. This includes concepts, data models, core functions, and general notes on programming in the framework. Special observations on the framework, from the perspective of front-end and back-end programming, are made in further sections. To give an overview does not mean to replace the existing documentation and reference—which wouldn't make sense anyway. You still need to look in the reference material to examine detailed functionality and options, but we believe that the overview will guide you to the right entry points into the system.
7.4.1 Framework Structure TYPO3 is not monolithic, but has a modular structure. So much so, that both the front end and back end can be replaced or removed. Even though more than 99 percent of TYPO3 installations are used as a CMS, the system is primarily a database management system, based on Web technologies. The core of TYPO3 is essentially defined by a database model and corresponding access functions in class.t3lib_tcemain.php (TCE). In this model, any database tables whatsoever can be organized in a type of directory structure—similar to a file system. The administration of users and user permissions is already part of the basic system.
435
7 Extension Development
Figure 7.18: The TYPO3 framework in a schematic structure
The CMS uses this data model for the administration of page structures with contents. This means that the front end and the accompanying database tables (tt_content, ...) and page types (Extended, Not in the menu, ... ) represent an application (extension) of the TYPO3 framework. It is quite possible not even to install the CMS front end, and to implement an Intranet bookkeeping software, for example, on the basis of the TYPO3 back end. Another scenario is a specialized high-performance front end, which is not structured on the TypoScript technique, but creates output (HTML, XML, ...) directly. But even the back end is replaceable, as has been proven in practice. If you have not been using TYPO3 for very long, you will probably not yet know the Classic Backend. This back end was quite an impressive JavaScript application, but was admittedly a little bit slow and difficult to maintain. As you already know, TYPO3 can be expanded simply with the help of extensions. Even the CMS itself is an extension. Seen from the framework extensions can basically be divided into five categories:
•
Based only on the core
•
Based on the standard back end (typo3/)
•
Based on the CMS front end (sysext/cms/)
•
Based on a different back end
•
Based on a different front end
The first three categories are also frequently mixed with each other, for 436
7.4 The TYPO3 Framework
example an extension with a database table (core) and a suitable plugin (CMS) for display. The last two categories are much more seldom, since TYPO3 is normally used as a CMS with standard front end and back end.
7.4.2 Coding Guidelines Before we take a closer look at the framework, the Coding Guidelines for the TYPO3 project should be briefly introduced. They will be particularly helpful to you if you are used to embedding PHP in HTML documents, because this concept is hardly ever used in TYPO3.
Softlink 485098
So code in the following form is not used in TYPO3: and the following line, which can be found in files such as ext_tables.php and ext_localconf.php: if (!defined ('TYPO3_MODE')) die ('Access denied.');
But all these elements are generated by Kickstarter, so that the examples can be reconstructed without problem. Furthermore all examples are available for download. The prefix user_, which is reserved for local extensions, is always used for the extension keys. The examples were developed on the basis of the CSS Styled Content extension, which renders content in such a way that it is marked exclusively with CSS classes. This concept is also used in the example extensions. It has the advantage that content and layout can be more easily separated. Most examples also function without being adjusted to the static template content (default); but it is possible that the results will differ somewhat in their appearance. But this is of no significance as far as the programming of a plugin is concerned.
498
7.6 Front-E End Programming: Examples
7.6.1 Content Borders This example is a small extension that inserts new borders for content elements.
Figure 7.31: Output of the linkexample plugin
In order to create new borders, you must of course know how the existing ones function. Since these are not encapsulated in a small extension where they can be quickly found, you have to do a little searching. As you know, content elements are stored in the tt_content database table, and in turn these are rendered via the TypoScript setup tt_content. So there are a number of places where you can start searching for the border. The file typo3/sysext/cms/tbl_tt_content.php contains the TCA definition of the fields in the table tt_content. Unfortunately this definition at first glance doesn't seem to contain much that would be of help to us. As described in section 7.4.7, Database, TCA, and TCEForms, the appearance of the back-end form for content elements is defined in this file. Therefore the entries from the selection field for borders should also appear here. These entries, however, have been moved to a separate file containing the various languages. A look at the file tbl_tt_content.php shows that the labels can be found in the file locallang_ttc.php. Array('LLL:EXT:cms/locallang_ttc.php:CType.I.0', 'header'), Array('LLL:EXT:cms/locallang_ttc.php:CType.I.1', 'text'),
The entries from the selection field are quickly found. The keys for the labels are now known. 'section_frame' => 'Rahmen:', 'Frame:' 'section_frame.I.1' => 'Invisible', 'section_frame.I.2' => 'Line in front', 'section_frame.I.3' => 'Ruler after', 'section_frame.I.4' => 'Indent', 'section_frame.I.5' => 'Indent, 33/66%',
Using the (section_frame) key in the TCA definition, you can now search for the field for the borders (this is also possible via Tools | Configuration | $TCA). The following section can be found in the file tbl_tt_content.php: 'section_frame' => Array ( 'exclude' => 1, 'label' => 'LLL:EXT:cms/locallang_ttc.php: section_frame', 'config' => Array ( 'type' => 'select', 'items' => Array ( Array('', '0'), Array('LLL:EXT:cms/locallang_ttc.php: section_frame.I.1','1'), Array('LLL:EXT:cms/locallang_ttc.php: section_frame.I.2', '5'),
Here the section_frame field in the tt_content table defines the border for content elements. Now search through the TypoScript setup for the place that renders the border; to do this, use the TypoScript Object Browser in the Web | Template module. You can look through the setup for section_frame in the search form. Now the position in the TypoScript setup where the new borders must be inserted is also known.
500
7.6 Front-E End Programming: Examples
Figure 7.32: Searching through the TypoScript setup
So for new borders, the new entry in the TypoScript object is necessary to render borders: tt_content.stdWrap.innerWrap.cObject
as well as entries in $TCA['tt_content']['columns']['section_frame'] ['config']['items']
so that these borders are available for the user in the back end. Unfortunately the Extension Kickstarter does not make provisions for creating such an extension. You could copy the required files from other extensions and adjust them, or you can create an extension with Kickstarter that contains roughly what you need, and then modify this, deleting unnecessary components. It is a good idea to create an Add as a Textbox type plugin with Kickstarter for this extension. Since a PHP plugin is not required here, the pi1/ directory can be deleted again, and the extension contains the following files: ext_emconf.php ext_icon.gif ext_localconf.php ext_tables.php locallang_db.php
Extending the TCA definition is done in ext_tables.php and looks 501
A wrap is necessary to create the border. Border 1 can serve here as a template: tt_content.stdWrap.innerWrap.cObject.20 = TEXT tt_content.stdWrap.innerWrap.cObject.20.value = |
The necessary TypoScript is inserted in ext_localconf.php. A for loop is again used here to generate the required TypoScript via t3lib_extMgm::addTypoScript(). // generate frames with key 75 - 77 for ($key = 75; $key /* /*]]>*/ ... ...
7.6.2 The Countdown TypoTag Although a CMS is supposed to separate layout and content, it is often necessary to mark the contents first. TYPO3 provides its own tags for marking. These tags are not to be confused with HTML tags, because socalled TypoTags are transformed during the rendering process into HTML (or something else). The following example introduces the tag. Its purpose is to count down the days until a certain day is reached. In a Text content element, the following contents: 504
7.6 Front-E End Programming: Examples
There are still 23 June 2004 days till the Linux Days 2004.
should lead to the following output: There are still 104 days till the Linux Days 2004.
The date enclosed in the tag should therefore be converted to the number of days until this date. A new tag can be easily created in Kickstarter with the corresponding option. The Kickstarter provides the following files: ext_emconf.php ext_icon.gif ext_localconf.php pi1/ class.user_tagcountdown_pi1.php
Figure 7.35: The tag is created as a plugin in Kickstarter
In the file ext_localconf.php, class.user_tagcountdown_pi1.php (the PHP script) and the plugin are integrated into the TypoScript template. t3lib_extMgm::addPItoST43($_EXTKEY, 'pi1/class.user_tagcountdown_pi1.php', '_pi1', '', 1); t3lib_extMgm::addTypoScript($_EXTKEY,'setup','
505
7 Extension Development lib.parseFunc_RTE.tags.countdown = < plugin.'. t3lib_extMgm::getCN($_EXTKEY). '_pi1',43);
You should note here that this does not function with the content (default) template, because parseFunc is in a different location there. So if the plugin is to function with this template, it must be inserted in a different way. Generally the TypoScript Object Browser in the Web | Template module can be of help to find such locations. t3lib_extMgm::addTypoScript($_EXTKEY,'setup',' tt_content.text.20.parseFunc.tags.countdown = < plugin.'. t3lib_extMgm::getCN($_EXTKEY). '_pi1',43);
But let's go back to the first variation. The resulting TypoScript integration, summarized, appears as follows: plugin.user_tagcountdown_pi1 = USER plugin.user_tagcountdown_pi1.userFunc = user_tagcountdown_pi1->main includeLibs.user_tagcountdown_pi1 = typo3conf/ext/user_tag_countdown/pi1/ class.user_tagcountdown_pi1.php lib.parseFunc_RTE.tags.countdown = cObj->getCurrentVal(); $timestamp = strtotime($date); $delta = $timestamp - time(); $days = intval($delta / (60 * 60 * 24)) + 1;
506
7.6 Front-E End Programming: Examples
return $days; } }
The $this->cObj->getCurrentVal() function returns the contents of the tag (the date), which is converted to days in the following lines. It should be pointed out that the PHP function strtotime() cannot handle some national date conventions, but this plays no role in this example. Parameters can be passed to the main() function in two different ways. In the first, the handover occurs directly in the Typo tag, just as with HTML tags. There are still 23 Jun 2004 hours till the Linux Days 2004.
All parameters in the tag are accessible to the plugin object via the $this->cObj->parameters array. In this case $this->cObj->parameters['unit'] will contain the value hour. This also functions with multiple parameters. In addition, $this->cObj->parameters['allParams'] contains all parameters as a string, in the form in which they were passed on. To have the hours displayed, the plugin must be modified as follows: function main($content,$conf) { // get parameter from tag $unit = $this->cObj->parameters['unit']; // get parameter from TypoScript $unit = $unit ? $unit : $this->cObj-> stdWrap($conf['unit'], $conf['unit.']); if ($unit=='min') { $divider = 60; } elseif ($unit=='hour') { $divider = 60 * 60; } else { // day - default $divider = 60 * 60 * 24; } $date = $this->cObj->getCurrentVal(); $timestamp = strtotime($date); $delta = $timestamp - time(); $days = intval($delta / $divider) + 1; return $days; }
507
7 Extension Development
Now the tag can handle minutes, hours and days. The second way of passing on parameters is, as with all plugins, through TypoScript. The code that fetches the unit parameter via TypoScript is already contained in the above variation. $unit = $unit ? $unit : $this->cObj-> stdWrap($conf['unit'], $conf['unit.']);
If unit has not already been passed as a parameter in the tag, stdWrap() is called to fetch this value from the TypoScript setup. The stdWrap() method is a component of the cObj content object. The cObj object is set externally while a plugin is initialized, and is available to the plugin. cObj is an instance of tslib/class.tslib_content.php, and renders all known TypoScript objects such as TEXT or IMAGE. plugin.user_tagcountdown_pi1.unit = min
This TypoScript setup defines the value min for unit; this means that the default value is no longer day. So now minutes are counted, as long as unit is not set in the tag. Because plugin.user_tagcountdown_pi1.unit is an object of the stdWrap type, it also has the same properties. This makes the following TypoScript setup possible: plugin.user_tagcountdown_pi1.unit = min plugin.user_tagcountdown_pi1.unit.override.data = register: user_tagcountdown_unit
Here unit is filled with the value min, but if user_tagcountdown_unit contains a value there, then this is overwritten with the TS register. TYPO3 reads TypoScript into a PHP array. you can make this array visible by inserting the debug($conf); function at the beginning. If you now reload the page in the front end you will obtain the output as shown in the following figure:
Figure 7.36: Output of the debug() function
This is the entire TypoScript for this plugin. The tables reproduce the embedding found in the arrays. In standard text form, this appears as follows: plugin.user_tagcountdown_pi1 = USER
508
7.6 Front-E End Programming: Examples plugin.user_tagcountdown_pi1 { userFunc = user_tagcountdown_pi1->main unit = min unit.override.data = register: user_tagcountdown_unit }
If stdWrap() is called up, the first parameter to be passed is the value of $conf['unit'], in this case, min. $this->cObj->stdWrap($conf['unit'], $conf['unit.']);
This first parameter of stdWrap() is the value or content that the method is intended to process. The second parameter $conf['unit.'] defines the behavior of stdWrap by means of a parameter array. You should take a look at the stdWrap() function in tslib/class.tslib_content.php and try to understand how it works. You will find this principle over and again in TYPO3. And if you have another look at the PHP code for this plugin, you will realize that even main() follows this principle.
7.6.3 Countdown Tag with JavaScript The countdown tag will now be extended so that the counter in the front end continues running via JavaScript. It is a good idea here to extend the plugin so that it is able to display seconds, because otherwise there will be nothing much to see in the front end. In addition the new animate parameter is introduced. There are still 23 Jun 2004 seconds to go until the Linux Days 2004.
JavaScript should only be inserted into the page if this is set. Even if this goes slightly beyond the limits of this book, we want to briefly mention JavaScript programming here. Because a number of extensions can insert JavaScript into HTML pages, the JavaScript code must also adhere to the namespace made available by the extension. The simplest way to obtain this is to encapsulate the entire script in an object, thus avoiding global variables. Objects work in JavaScript similarly to classes in PHP. One function serves here as a container. This container can be expanded via the prototype property. function myClass() { this.myInstanceVar = 0; } myClass.prototype.myFirstMethod = function (param1,
509
7 Extension Development param2) { this.myInstanceVar = (param1 + param2)/2; } myClass.prototype.mySecondMethod = function () { return this.myInstanceVar; }
In this way, only myClass() is present in the global namespace. All other functions and variables are encapsulated. It makes sense to use $this-> extKey or $this->prefixId as the namespace for JavaScript code. This results in the following structure for the JavaScript code for this extension: function user_tagcountdown_pi1(id,countdown,unit) { ... } user_tagcountdown_pi1.prototype.showcount = function () { ... }
The additionalHeaderData array in the global object TSFE is available so that you can insert something into the HTML header. The following example shows how you insert JavaScript into the header. // check if JavaScript is already set if (!$GLOBALS['TSFE']->additionalHeaderData[$this-> prefixId]) { $jsCode = ' alert("This is JavaScript");'; // wrap JavaScript in script tags and add to page // header $GLOBALS['TSFE']->additionalHeaderData[$this->prefixId] = t3lib_div::wrapJS($jsCode); }
First a check is made to see if the JavaScript code has already been inserted. This should only happen once of course, no matter how many times the plugin is called up. Through the function t3lib_div::wrapJS(), the JavaScript code is provided with <script> tags and then added to the HTML header.
510
7.6 Front-E End Programming: Examples
If you want to use the JavaScript onload() event handler in the body tag, you have to share this with other extensions. You do this by entering your JavaScript onload code into an array in the TSFE object. $GLOBALS['TSFE']->JSeventFuncCalls['onload'][$this-> prefixId] = 'alert("JS executed on load");';
In the modified code of the plugin, first the counter is introduced, so that the elements can later be given a unique ID. A global variable is used for this: function main($content,$conf) { // count items for JavaScript usage $GLOBALS['T3_VAR']['ext'][$this-> prefixId]['count']++;
With $GLOBALS['T3_VAR']['ext'][$this->prefixId], namespace of the plugin is used.
only
the
// get parameter from tag $unit = $this->cObj->parameters['unit']; // get parameter from TypoScript $unit = $unit ? $unit : $this->cObj-> stdWrap($conf['unit'], $conf['unit.']);
Seconds are then added to the calculation: if ($unit=='sec') { $divider = 1; } elseif ($unit=='min') { ... $days = intval($delta / $divider) + 1;
The new animate parameter is introduced. Note that the check is made with isset(), since animate does not have a value unless you write the following: . // check if "animate" parameter is set in tag $animate = isset($this->cObj->parameters['animate']); // get parameter from TypoScript $animate = $animate ? $animate : $this->cObj->stdWrap($conf['animate'], $conf['animate.']);
Finally, there is the code that integrates the animation. This only happens for seconds or minutes, because nobody would notice an animation that only changed hourly or daily. 511
7 Extension Development // do animation for seconds or minutes only if ($animate AND ($unit=='sec' OR $unit=='min')) {
An ID for the HTML element is created: // unique id for every element (HTML DOM doesn't accept '_') $domId = str_replace('_','-',$this->prefixId).'-'. $GLOBALS[$this-> prefixId]['count'];
The function to integrate the JavaScript code, which follows later, is called: // include JS code $this->addJsCounter($domId, $days, $unit);
Finally the text is provided with a <span> tag, including an ID. // add an id to the content $days = '<span id=".$domId.'">'.$days.''; } return $days; }
Now comes the function that integrates the JavaScript code. The locations containing Java-Script are marked in bold. Please note that it contains PHP variables such as $this->prefixId, which make the code portable. /** * Add JavaScript counter code to the page * * @param string dom id * @param integer start value for the counter * @param string unit: 'sec' or 'min' * @return void */ function addJsCounter($id, $countdown, $unit) { // include JS code once if (!$GLOBALS['TSFE']->additionalHeaderData[$this-> prefixId]) { $jsCode = prefixId}(id,countdown,unit) { this.id = id; this.countdown = countdown; setInterval( "{$this-> prefixId}ObjArr['"+id+"].showcount()", unit); }
512
7.6 Front-E End Programming: Examples
{$this->prefixId}.prototype.showcount = function () { this.countdown = this.countdown-1; element = document.getElementById(this.id); element.innerHTML = this.countdown; } EOD; // wrap JavaScript in script tags and add to page // header $GLOBALS['TSFE']->additionalHeaderData[$this-> prefixId] = t3lib_div::wrapJS($jsCode); } $unit = ($unit=="min") ? 60000 : 1000; // add JS onload handler $GLOBALS['TSFE']->JSeventFuncCalls['onload'][$id] = "{$this->prefixId}ObjArr['{$id}'] = new {$this->prefixId}('{$id}', {$countdown}, '{$unit}');"; }
Since the principle applied here has already been explained, we will not be going into any more detail regarding the example code. As you can see, it's not that difficult to integrate JavaScript so that several JavaScript plugins can be used on the same page, without coming into conflict with one another.
7.6.4 Integrating External PHP Scripts The simpler and more clearly structured external scripts are, the easier it is to use them in TYPO3. If scripts already exist as classes, writing a wrapper seems like the obvious thing to do. This will then insert the class and call it correspondingly. More work is involved if parameters are sent. As a rule, the URL, and possibly the parameters themselves, must be adjusted. If the script is less structured or if it is an old script, using now obsolete PHP variables, for example, adjustments will be necessary.
Softlink 680352
External PHP scripts can be integrated in the TYPO3 front end in many different ways, via the following TypoScript objects: USER, USER_INT These objects represent the standard method. All plugins created by the Kickstarter are integrated as USER or USER_INT. The difference between the two methods is that the output is cached when integrated with USER, while this is not the case with 513
7 Extension Development USER_INT. The latter method is used if the script is intended to react to parameters (GET, POST) in order to generate different outputs, and where it is not worthwhile to use the cHash functionality. Integrating scripts with USER objects is certainly preferable to doing this with PHP_SCRIPT. Integration with PHP_SCRIPT is only necessary if a script is not available as a class, and if porting is not an option.
PHP_SCRIPT Integrating a script looks something like this in TypoScript: page.90 = PHP_SCRIPT page.90.file = fileadmin/scripts/myscript.php
The script is then included in tslib_cObj. This means that you have access to all the methods of this object, via $this. The output of the script must be contained in the variable $content. PHP_SCRIPT_INT This method functions like PHP_SCRIPT. The output of the script is not cached, however. PHP_SCRIPT_EXT In this method, the output is also not cached. But integration functions here differently to the two methods above, since the script can produce its output with echo/print.
Converting PHP Script If you want to insert scripts into TYPO3 that have not been developed specially for it, this is usually possible with relatively little work. Using the example of the following small script, which fetches a few pieces of information on a web server, we will show you what possibilities are available.
