T3dallas typoscript
Download as KEY, PDF4 likes1,813 views
The document is a comprehensive guide to Typoscript, a configuration language used in TYPO3 for rendering pages and managing site behavior. It covers syntax, best practices, and key concepts such as content objects, configuration setup, and the interaction of Typoscript with PHP. Best practices for organizing and managing Typoscript, including the importance of storing it in the filesystem and avoiding redundancy, are also emphasized.
![In code,
extension
authors access
Typoscript as
an array.
<?php
$wrap = $conf[‘1.’][‘wrap’];
?>](https://image.slidesharecdn.com/t3dallas-typoscript-100523101157-phpapp02/85/T3dallas-typoscript-11-320.jpg)
![[globalVar = TSFE:id = 1]
key.value = true
[else]
key.value = false
[end]
Typoscript conditions are
awesome. In most cases, use
them instead of extension
templates.](https://image.slidesharecdn.com/t3dallas-typoscript-100523101157-phpapp02/85/T3dallas-typoscript-25-320.jpg)
![Use page.config to manage JS
and CSS files for specific pages.
[globalVar = TSFE:id = {$pid.timeline}]
page.includeJS {
5 = fileadmin/templates/js/contrib/jQuery/fancybox/jquery.fancybox-1.2.6.pack.js
6 = fileadmin/templates/js/usr/timeline.js
6.allWrap =
}
page.includeCSS {
7 = fileadmin/templates/js/contrib/jQuery/fancybox/jquery.fancybox-1.2.6.css
}
[end]
[globalVar = TSFE:id = {$pid.photoGallery}]
page.includeJS {
8 = fileadmin/templates/js/contrib/jQuery/fancybox/jquery.fancybox-1.2.6.pack.js
9 = fileadmin/templates/js/usr/photoGallery.js
}
page.includeCSS {
10 = fileadmin/templates/js/contrib/jQuery/fancybox/jquery.fancybox-1.2.6.css
}
[end]](https://image.slidesharecdn.com/t3dallas-typoscript-100523101157-phpapp02/85/T3dallas-typoscript-54-320.jpg)
T3dallas typoscript
- 1. TYPOSCRIPT CRASH COURSE Your driver today will be Zach Davis from Cast Iron Coding Inc.
- 2. Overview • What is Typoscript, really, and how does it generally work? • Overview of Typoscript Syntax • Overview of how pages are rendered through Typoscript • Typoscript and PHP • Navigating Typoscript documentation • Overriding core content rendering • Typoscript best practices
- 3. Where is Typoscript Used? • Typoscript is used to tell TYPO3 how to render pages. Every TYPO3 site requires a root-level Typoscript template. • Typoscript is (over) used in extension templates to control the behavior of individual pages or branches of a site. • Typoscript is used in static templates, which are part of TYPO3 extensions, to provide default configuration that can be overridden on individual sites.
- 4. Typoscript is Idiosyncratic, which can be confusing. For better or for worse, extension authors are free to implement Typoscript however they please.
- 5. Take tt_news, for example • Like most extensions, tt_news contains Typoscript properties that are only used in tt_news. • To undestand tt_news’ Typoscript, you would need to look at the tt_news documentation. • Look for TS in EXT/pi1/ static or EXT/static.
- 7. Typoscript is a configuration language • In this sense, it’s similar to YAML or XML. • Typoscript is not a programming language—it doesn’t really do anything programmatic, although it sometimes seems like it does. • Typoscript is interpreted by PHP scripts, which use it to determine what to render on the front-end.
- 8. Typoscript is a multi- dimensional associative array Arrays are pairs of keys and values, kind of like these mailboxes.
- 9. Typoscript is a multi- dimensional associative array If one or more of these mailboxes contained another wall of mailboxes inside of them, you’d have a multi- dimensional array.
- 10. Typoscript is a multi- dimensional associative array If we debug Typoscript, it looks like a series of nested tables.
- 11. In code, extension authors access Typoscript as an array. <?php $wrap = $conf[‘1.’][‘wrap’]; ?>
- 12. It’s all just strings and arrays. entryLevel = 0 wrap = <ul id=”primaryNav... 1 = TMENU 2 { expAll = 1 noBlue = 1 NO { WrapItemAndSub = <li>|... } ACT = 1 ACT { wrapItemAndSub = <li>|... ATagParams = class=... } }
- 13. Typoscript Syntax is Easy. really!
- 14. Key = Value Value is a string (or an integer).
- 15. Key { Value } The confinements tell us that value is an array.
- 16. Key < Value Value is another Typoscript path, which is copied and pasted to key.
- 17. For Example: myObj.wrap = before|after myOtherObj.wrap < myObj.wrap In this case, myOtherObj.wrap equals before|after.
- 18. Key < Value When assigning values in this way, you can assign an entire chunk of Typoscript or a single value of a given property.
- 19. Key > The greater than sign unsets the value of a Typoscript property.
- 20. Key = 1,2,3 Key := addToList(4,5) Key := removeFromList(1) The := operator is used to modify an existing Typoscript value.
- 21. Key = 1,2,3 Key := addToList(4,5) Key := removeFromList(1) In this case, the final value for Key would be “2,3,4,5”
- 22. Key = 1,2,3 Key := addToList(4,5) Key := removeFromList(1) Other := options include prependString, appendString, removeString, and replaceString.
- 23. Comments // A comment / Another comment # Yet one more comment /* No end to the comments */
- 24. Key ( Value... Even more value ) Parentheses allow for multi-line values.
- 25. [globalVar = TSFE:id = 1] key.value = true [else] key.value = false [end] Typoscript conditions are awesome. In most cases, use them instead of extension templates.
- 26. A TYPO3 page is a set of TS cObjs mapped to an HTML template.
- 27. In TYPO3, all things come from Typoscript. Pages Navigation Plugins and content elements and page titles and dynamic content
- 28. PAGE.10 lib.auxNav lib.logo lib.search lib.header lib.primaryNav lib.breadcrumb lib.share lib.tagline lib.secondaryNav lib.heroImage plugin.tx_ccnygrants_pi1 styles.content.getRight styles.content.get
- 29. How a page is rendered from Typoscript • TYPO3 looks for a PAGE typoscript object, which is similar to a COA (content object array). • According to convention, we put the majority of the output for a page into PAGE.10. • PAGE.10 is typically a USER object (eg, templavoila) or a TEMPLATE object.
- 30. Anatomy of a TemplaVoila Page TS Obj USER SCRIPT: Page. Page. tx_templavoila_pi1->main_page 10 20 PAGE HTML Template TypeNum=0 TS Obj Content Area TS Obj Output TS Obj to Browser
- 31. Anatomy of a TEMPLATE Page TS Obj TS TEMPLATE OBJECT TS Obj Page. Page. 10 20 Content Area TS Obj TS Obj PAGE TypeNum=0 HTML TMPL WITH MARKERS Output AUTOMAKETEMPLATE to HTML TEMPLATE Browser
- 32. Behind the Scenes Let’s look at how PHP code interacts with Typoscript.
- 33. class.tslib_content.php This is where individual TS content objects are rendered. tslib_content contains the class definition for the tslib_cObj object, which is used to render HTML from Typoscript.
- 34. It’s really not that complicated. Many of the tslib_cObj methods are pretty straight forward. The code for rendering a TEXT object, for example, is one line. Most of the functionality is located in stdWrap or in other Typoscript “functions.”
- 36. But who needs code when you have the TSREF? You can find just about everything you need to know about Typoscript in the TSREF.
- 37. Data Types You just have to Functions know how to read it... The TSREF is divided into a few key parts: Setup •Data Types •Functions •Setup •Content Objects cObjects
- 38. Typoscript Content Objects • Typoscript Content Objects are chunks of content that are rendered from Typoscript. Eg. a menu, or a plugin, or a logo in a header. • The main ones are: HTML, TEXT, COA, IMAGE, IMG_RESOURCE, HMENU, CASE, FORM, TEMPLATE, IMGTEXT, RECORDS, CONTENT.
- 39. PAGE COA TEXT HTML COA HMENU HMENU HTML HTML HMENU PLUGIN PLUGIN CONTENT CONTENT
- 40. Typoscript Content Objects • CSS Styled Content is used to render content from individual tt_content records. • It is essentially a library of Typoscript objects (and some associated PHP scripts) that transform tt_content records into HTML. tt_content:10 <!-- COMMENT... --> <h1>My Record</h1> Field Value header My Record tt_content.text <p class=”bodytext”> Test </p> bodytext Test
- 41. CSS Styled Content: Text
- 43. Typoscript Data Types •Every Typoscript property has a data type. Most are strings or integers. •Some properties are of a certain data type, which often means that there are additional properties available.
- 45. Remember the common types. Look up the rest. •<tag> •int •wrap •align •string •linkWrap •valign •boolean •case •VHalign •rotation •space •resource •x,y,w,h •date-conf •imgResource •HTML-color •strftime-conf •HTML-code •GraphicColor •UNIX-time •target •page_id •path •imageExtension •pixels •getText •degree •list •dir •posint •margins •function-name
- 46. Typoscript Functions • We might think of Typoscript functions as small content objects. • For example, the typolink function turns a chunk of TS into text wrapped with an A tag or, in some cases, a URL. • You will see references to these functions throughout the TSREF. They are generally prefaced with -> (eg. - >stdWrap). If the value in the data type column begins with ->, it’s a function. Otherwise, it’s a data type.
- 47. As with datatypes, remember the common functions, look up the rest. •stdWrap •typolink •parseFunc •imgResource •textStyle •makeLinks •imageLinkWrap •encapsLines •tags •numRows •tableStyles •HTMLparser •select •references •HTMLparser_tags •split •addParams •if •filelink
- 48. stdWrap • Use stdWrap to manipulate strings: trim, parseFunc, strftime, case, stripHtml, cropHtml, crop, wrap, innerWrap, etc. • Use stdWrap to insert data into output: data, field • Use stdWrap to wrap other content objects around a value: preCObject, postCObject. • Use stdWrap to pass values through PHP functions: preUserFunc, postUserFunc, postUserFuncInt. • Use stdWrap to implement simple conditional logic: if, fieldRequired, required, ifEmpty, ifBlank, override.
- 49. typolink • It is essential that you use typolink to render links from typoscript. Doing so will make your site more portable and less prone to broken links. • use the .parameter property to designate the href of the link. • use the .returnLast property to return a URL instead of a full A tag. • you have access to stdWrap on parameter, which means you can do things like this: parameter.field = uid parameter.additionalParams = &L=1
- 50. ParseFunc is a session in and of itself. For now, we’ll just focus on what it does (not how it does it). You should at least know that any field that is rendered on the front-end that could contain HTML should probably be passed through parseFunc. ParseFunc is also responsible for transforming RTE content on the frontend, and for parsing TYPO3-specific tags.
- 51. Typoscript Setup: Config • So far we’ve been looking at Typoscript in the context of content objects. Eg, using Typoscript to render an HMENU content object. • To make matters more confusing, Typoscript is also used for front-end configuration (much like how TSConfig is used for backend configuration). • Mostly, you don’t need to worry about the contents of the setup section of the TSREF, except for...
- 52. Typoscript Setup: Config • ...except for the “config” section. • “config” contains properties that are generally applicable to every page that is governed by a given Typoscript template. • TYPO3 site builders should familiarize themselves with the config section, as there are lots of important properties contained within.
- 53. Typical Config on a CIC site config { # Miscellaneous noPageTitle = 1 typolinkCheckRootline = 1 typolinkEnableLinksAcrossDomains = 1 spamProtectEmailAddresses = -7 disablePrefixComment = 1 # Enable indexing index_enable = 1 admPanel = 1 # Set doc type doctype = xhtml_trans # Setup realURL simulateStaticDocuments = 0 baseURL = http://{$const.baseUrl}/ tx_realurl_enable = 1 }
- 54. Use page.config to manage JS and CSS files for specific pages. [globalVar = TSFE:id = {$pid.timeline}] page.includeJS { 5 = fileadmin/templates/js/contrib/jQuery/fancybox/jquery.fancybox-1.2.6.pack.js 6 = fileadmin/templates/js/usr/timeline.js 6.allWrap = } page.includeCSS { 7 = fileadmin/templates/js/contrib/jQuery/fancybox/jquery.fancybox-1.2.6.css } [end] [globalVar = TSFE:id = {$pid.photoGallery}] page.includeJS { 8 = fileadmin/templates/js/contrib/jQuery/fancybox/jquery.fancybox-1.2.6.pack.js 9 = fileadmin/templates/js/usr/photoGallery.js } page.includeCSS { 10 = fileadmin/templates/js/contrib/jQuery/fancybox/jquery.fancybox-1.2.6.css } [end]
- 55. Typoscript Best Practices (Well, perhaps not best, but these tips work for us.)
- 56. Typoscript Best Practices • Store your Typoscript in the filesystem, not in the database. If it’s in the database, it can’t be versioned with SVN, Git, etc. • Avoid using extension templates. Instead, make a new page template (reusable) or use a Typoscript condition. • Comment Typoscript carefully. Use object names (eg. lib.X) as a sort of Typoscript namespace. • Keep extension configuration and page template configuration separate.
- 57. Typoscript Best Practices • Organize your Typoscript in such a way that you’re able to avoid redundancy. Don’t declare properties twice if you an avoid it! • Use constants constantly. Always abstract the baseUrl to a constant, as well as any page ID values. • Never directly modify the Typoscript in an extension directory. If you do, you will regret it later. • Avoid using too many extension templates. Try to keep things in one place.
- 58. Typoscript Best Practices • Typolinks! Typolinks! Typolinks! Use wraps and COAs so that you don’t have to hard code URLs in your Typoscript (or, even worse, in your templates). • Keep Typoscript lightweight and modular. Instead of making a giant COA with 4 complex entries, make 4 TS objects and copy them into the COA. • Remember that order matters in Typoscript. You can’t reference another object unless that object has been included above the spot where you reference it.
- 59. How we organize our Typoscript •Extension TS goes in conf_ext, global site TS goes in conf_general and tsconfig goes in, well, tsconfig. •We store environment- specific constants in global_constants_context. txt.
- 60. How we organize our Typoscript •Put an .htaccess file in fileadmin/templates/conf so that you prevent spiders and users from viewing the contents of your Typoscript. That said, if it’s secret, try not to store it in Typoscript.
- 61. PID and URL abstraction simplifies distributed development Development Staging Production carnegie.lucas.cic.com staging.carnegie.org carnegie.org carnegie.zach.cic.com carnegie.gabe.local
- 62. PIDs and Domain Names change in each environment. Development Staging Production carnegie.lucas.cic.com staging.carnegie.org carnegie.org carnegie.zach.cic.com carnegie.gabe.local
- 63. global_constants_context does not get checked into Git—it’s context specific. Development Staging Production carnegie.lucas.cic.com staging.carnegie.org carnegie.org carnegie.zach.cic.com carnegie.gabe.local
- 64. All other Typoscript DOES get checked into Git. Development Staging Production carnegie.lucas.cic.com staging.carnegie.org carnegie.org carnegie.zach.cic.com carnegie.gabe.local
- 65. Wake up; it’s over! Thanks for listening and good luck with your future adventures in Typoscript.