Modern Template Building, Part 2+3¶

Skill levels¶

Part 1 of this tutorial contained:

The Basics - a newbee introduction to building websites with TYPO3, template records, TypoScript and Content Objects (cObjects). Any person who wants to develop with TYPO3 should be familiar with the concept described here.

Part 1: Integration of an HTML template - this part aims specifically at intermediate HTML-webdesigners with a limited amount of technical knowledge.

Notice: The Basics and Part 1 are found in another document, in the extension "doc_tut_templselect"

This part (2+3) contains:

Part 2: Creating a Template Selector - this part aims at intermediate web developer with good knowledge of PHP, SQL and programming concepts in general.

Part 3: Extending the Built-In Access Scheme - for advanced TYPO3 /PHP-developers.

The challenge¶

However we will now take the basic example from the previous section in this tutorial and expand it heavily so that instead of one template file we can select from any number of template files per page and per section. Further we want the content area to be more flexible having different sub-templates for columns, news sections etc. And all this should be made so flexible that new templates can be added by Mr. Raphael (the designer) simply by creating the file in the right location! At the same time the non-technical authors/editors should be able to select from these templates on a per-page basis in a visually intuitive way.

The technical outlines¶

The illustration below outlines what we need in order to achieve our goal:

As you can see the main structure (light blue section) is the same as in the previous section. However the template file delivered to the "plugin.tx_automaketemplate_pi1" USER cObject must be selected based on which template file is selected for the current page/template.

Further the insertion of page content elements must be done based on the currently selected content area template which will be combined with content from one or more columns by a TEMPLATE cObject (the light yellow section).

In the backend we need to add selector boxes for the templates in the page records. The content of these selectors must be dynamically loaded by some logic that looks up template files from a designated location in the file system. Thus Mr. Raphael can add new templates by the act of just creating a new template file there!

The selectors should be equipped with icons representing the template options visually, something like this:

Skill level¶

Intermediate to advanced web developer. Requires skills with PHP. Developer experience with TYPO3 and extension development is highly recommended.

To complete this section of the tutorial you should be a developer minded type of person. It requires you to know PHP and furthermore I'll be less explicit than in the previous section. So you will have to enable your brain during this section and figure out what's between the lines once in a while.

The main templates¶

The main templates Mr. Raphael made are stored in the folder "fileadmin/template/main/". There are currently two main templates there:

template_1.html:

This is the same template as in Part 1 of this tutorial.

template_2.html:

This is an alternative main template. It includes a "path-menu" (Root page > First page > ....), a horizontal menu of current-page sub items and a content area which spreads over the full width of the page.

For each of these templates Raphael also made a little icon. He gave the icons the same name as the template file, but with the "gif" extension instead:

template_1.gif:

template_2.gif:

As you can see these icons are designed to reflect the overall structure of the main templates.

Now, lets just look inside of the template_2.html file for a second:

Notice the title of the document - we will use this for the main template selector box!

This template uses an additional stylesheet!

The template has a "path-menu" in a table cell with the id "path"

The main menu is contained in a table row with id "menu_2" (#5) and each element is wrapped in a <td> element.

"menu_2" is the id of the table row (see #4)

The class "oddcell" is used for every second menu item - this will produce alternating background colors

The class "menu2-level1-act" is used to define the style for active elements in the menu.

The id "content" is used - as with template_1.html - for the table cell defining the content area of the main template.

Content area templates¶

In the folder "fileadmin/templates/sub/" we find four templates for different layouts of the content area of either of the main templates. Thus we have two main templates times four content area templates - a total of 8 possible combinations!

<div id="colNormal">
        <h1>Buy PaperShredder(tm) Gizmo with 30-days money-back guarantee!</h1>
        <img src="../main/images/paperwork.jpg" width . . . ="0" alt="" align="right"/>
        <p class="bodytext">Adam Seth Enos Cainan Malelehel . . . </p>
        <p class="bodytext">Filii Ham Chus et M. . . </p>

        <br />
</div>

<table border="0" width="100%">
<tr>
        <td id="colNormal" width="390" valign="top">
                <h1>Buy PaperShredder(tm) Gizmo with 30-days money-back guarantee!</h1>
                <img src="../main/images/paperwork.jpg" wid...0" alt="" align="right"/>
                <p class="bodytext">Adam Seth Enos Cainan Maleleh.../p>
                <p class="bodytext">Filii Ham Chus et M...</p>

                <br />
        </td>
        <td width="20"></td>
        <td id="colRight" width="190" valign="top">
                <h1>Buy PaperShredder(tm) Gizmo with 30-days money-back guarantee!</h1>
                <img src="../main/images/paperwork.jpg" wid...der="0" alt="" align="right"/>
                <p class="bodytext">Adam Seth Enos Cainan Malelehel Iar...</p>
                <p class="bodytext">Filii Ham Chus et Mesraim Ph...</p>

                <br />
        </td>
</tr>
</table>

. . .
/* Additional attributes for content in RIGHT column */
#colRight H1 {
        font-size: 12px;
        background-color: #eefffe;
        text-align: center;
        font-color: maroon;
}
#colRight P.bodytext {
        font-size: 10px;
}
. . .

<table border="0" width="100%" id="ct3">
<tr>
        <td id="colLeft" width="30%" valign="top">
                . . .
        </td>
        <td id="colNormal" width="30%" valign="top">
                . . .
        </td>
        <td id="colRight" width="30%" valign="top">
                . . .
        </td>
</tr>
</table>

. . .
/* Overriding attributes for columns in case of content template #3 */

#ct3 #colRight P.bodytext,
#ct3 #colLeft P.bodytext,
#ct3 #colNormal P.bodytext
{
        font-size: 10px;
}
#ct3 #colRight H1,
#ct3 #colLeft H1,
#ct3 #colNormal H1
{
        font-size: 12px;
        text-align: center;
        font-color: maroon;
}

#ct3 #colLeft H1 {      background-color: #E3DEBC; }
#ct3 #colNormal H1 { background-color: #F4EAAB; }
#ct3 #colRight H1 {     background-color: #FFF2A0; }

#ct3 TD#colRight {padding-left: 5px;}
#ct3 TD#colLeft {padding-right: 5px;}
#ct3 TD#colNormal {padding-right: 5px;padding-left: 5px;}
. . .

<table border="0" align="right" id="news-table" width="200">
<tr>
        <td class="news-header"><h1>News:</h1></td>
</tr>
<tr>
        <td id="news-pi">
                <DIV class="tx-mininews-pi1">
                  <DIV class="tx-mininews-pi1-fp_listrow" style="margin-top: 5px;">
                          <P class="tx-mininews-pi1-fp_listrowField-datetime">07-02-03 16:00</P>
                          <P class="tx-mininews-pi1-fp_listrowField-title"><A HREF="#">Adam.. </a></P>
                          <P class="tx-mininews-pi1-fp_listrowField-teaser">Ham et. . .</P>

                          <P class="tx-mininews-pi1-fp_listrowField-datetime">29-01-03 10:30</P>
                          <P class="tx-mininews-pi1-fp_listrowField-title"><A HREF="#">Saba ...</a></P>
                          <P class="tx-mininews-pi1-fp_listrowField-teaser"> . . </P>

                          <P class="tx-mininews-pi1-fp_listrowField-datetime">06-01-03 16:24</P>
                          <P class="tx-mininews-pi1-fp_listrowField-title"><A HREF="#">Sabat. .</a></P>
                          <P class="tx-mininews-pi1-fp_listrowField-teaser">Chus et Mesr. . </P>
                  </DIV>
          </DIV>
        </td>
</tr>
</table>
<!-- ###colNormal### -->
        <h1>Buy PaperShredder(tm) Gizmo with 30-days money-back guarantee!</h1>
        <p class="bodytext">Adam Seth Enos Cainan Malelehel. . .m.</p>
        <p class="bodytext">Filii Ham Chus et Mesraim Phut et ... </p>

        <br />
<!-- ###colNormal### -->

/* NEWS splash in template #4 */
TABLE#news-table {
  margin-left: 10px;
  border: solid 1px black;
}
TD.news-header {
        background-color: navy;
}
TD.news-header H1 {
  color: white;
  margin: 0px 0px 0px 0px;
  text-align: center;
}
DIV.tx-mininews-pi1-fp_listrow P {
        font-size: 11px;
        font-color: navy;
        font-family: verdana;
        margin: 0px 0px 0px 0px;
}
DIV.tx-mininews-pi1-fp_listrow P.tx-mininews-pi1-fp_listrowField-datetime { font-size: 10p. . .x;}
DIV.tx-mininews-pi1-fp_listrow P.tx-mininews-pi1-fp_listrowField-title { font-weight: bold; }
 . . .
DIV.tx-mininews-pi1-fp_listrow P.tx-mininews-pi1-fp_listrowField-teaser A:hover { tex . . derline;}

Summary¶

After this analysis of the source templates from Mr. Raphael we can define this overview of id/class values for which Mr. Benoit - the developer on the team - needs to produce subparts and dynamic content:

Main templates:

Get an extension key¶

First you should register an extension key on typo3.org. The extension key I'm using here, tmplselect, is mine (I registered it!) and you cannot/should not use it (except for internal playing around on your own server).

Go to the kickstart wizard¶

The Kickstarter Wizard allows you to quickly launch a framework for a new extension. The Kickstarter Wizard is not an extension editor and it will probably never be one. When your extension framework is written to disc you are basically on your own... (for re-modelling a framework you can load the original K-Wizard configuration by selecting "Backup/Delete" in the menu and click "Start new" when looking at the details of an extension in the Extension Manager.)

Now, enter general information:

Extend the "pages" table by two new, completely alike selector boxes with a single, blank item and PHP-preprocessing added:

Add a "Frontend Plugin", select the "Just include library" type:

Finally, press the "View result" button and write the extension to the local extension space of your installation:

You should see this message confirming the success of the operation:

Now, install the extension you just created:

Confirm the creation of the two new database fields and clear cache.

The new extension is now installed.

Check the installed extension¶

First, lets verify that the extension is available as we would expect.

For the frontend plugin which should include a simple library we would expect to find this in the Object Browser from the Template module:

And for the two new fields in the "pages" table we should find this when we edit a page header:

As you can see there is both a dummy-icon and an item supposedly added by a PHP function.

Next stop is to fill these selector boxes with a list of template files from "fileadmin/template/main/" and "fileadmin/template/sub/" including their icons!

ext_tables.php¶

<?php
if (!defined ("TYPO3_MODE"))    die ("Access denied.");

if (TYPO3_MODE=="BE")   {
  include_once(t3lib_extMgm::extPath("tmplselect").
                                  "class.tx_tmplselect_addfilestosel.php");
}

$tempColumns = Array (
  "tx_tmplselect_main_tmpl" => Array (
          "exclude" => 1,
          "label" => "LLL:EXT:tmplselect/locallang_db.php:pages.tx_tmplselect_main_tmpl",
          "config" => Array (
                  "type" => "select",
                  "items" => Array (
                          Array(
                                  "LLL:EXT:tmplselect/locallang_db.php:pages.tx_tmplselect_main_tmpl.I.0",
                                  "0",
                                  t3lib_extMgm::extRelPath("tmplselect")."selicon_pages_tx_tmplselect_main_tmpl_0.gif"
                          ),
                  ),
                  "itemsProcFunc" => "tx_tmplselect_addfilestosel->main",
          )
  ),
  "tx_tmplselect_ca_tmpl" => Array (
          "exclude" => 1,
          "label" => "LLL:EXT:tmplselect/locallang_db.php:pages.tx_tmplselect_ca_tmpl",
          "config" => Array (
                  "type" => "select",
                  "items" => Array (
                          Array(
                                  "LLL:EXT:tmplselect/locallang_db.php:pages.tx_tmplselect_ca_tmpl.I.0",
                                  "0",
                                  t3lib_extMgm::extRelPath("tmplselect")."selicon_pages_tx_tmplselect_ca_tmpl_0.gif"
                          ),
                  ),
                  "itemsProcFunc" => "tx_tmplselect_addfilestosel_ca->main",
          )
  ),
);


t3lib_div::loadTCA("pages");
t3lib_extMgm::addTCAcolumns("pages",$tempColumns,1);
t3lib_extMgm::addToAllTCAtypes("pages","tx_tmplselect_main_tmpl;;;;1-1-1, tx_tmplselect_ca_tmpl");
?>

class.tx_tmplselect_addfilestosel.php¶

class tx_tmplselect_addfilestosel {
        var $dir = "main";

        function main(&$params,&$pObj)  {
                        // Adding an item!
                $params["items"][]=Array($pObj->sL("Mode: ".$this->dir), 999);
        }
}
class tx_tmplselect_addfilestosel_ca extends tx_tmplselect_addfilestosel {
        var $dir = "sub";
}

Now the whole game is about programming the main function in the class tx_tmplselect_addfilestosel. The input array $params is passed as a reference and we only need to add entries in this array with label / filename / icon-reference pairs.

I'll just flatly list the PHP code that needs to go into class.tx_tmplselect_addfilestosel.php to achieve this and since the code is well commented you can read the comments to understand the details:

// Include the parse-html class: require\_once( PATH\_t3lib . 'class.t3lib\_parsehtml.php' );class tx\_tmplselect\_addfilestosel {var $dir = "main" ; /\*\* \* Manipulating the input array, $params, adding new selectorbox items. \*/ function main (& $params ,& $pObj ){ // configuration of paths for template files: $confArray =array( "main" => "fileadmin/template/main/" , "sub" => "fileadmin/template/sub/" ); // Finding value for the path containing the template files. $readPath = t3lib\_div :: getFileAbsFileName ( $confArray [ $this -> dir ]); // If that directory is valid, is a directory then select files in it: if(@ is\_dir ( $readPath )){ // Getting all HTML files in the directory: $template\_files = t3lib\_div :: getFilesInDir ( $readPath , 'html,htm' , 1 , 1 ); // Start up the HTML parser: $parseHTML = t3lib\_div :: makeInstance ( 't3lib\_parseHTML' ); // Traverse that array: foreach( $template\_files as $htmlFilePath ){ // Reset vars: $selectorBoxItem\_title = '' ; $selectorBoxItem\_icon = '' ; // Reading the content of the template document... $content = t3lib\_div :: getUrl ( $htmlFilePath ); // ... and extracting the content of the title-tags: $parts = $parseHTML -> splitIntoBlock ( 'title' , $content ); $titleTagContent = $parseHTML -> removeFirstAndLastTag ( $parts [ 1 ]); // Setting the item label: $selectorBoxItem\_title = trim ( $titleTagContent . ' (' . basename ( $htmlFilePath ). ')' ); // Trying to look up an image icon for the template $fI = t3lib\_div :: split\_fileref ( $htmlFilePath ); $testImageFilename = $readPath . $fI [ 'filebody' ]. '.gif' ;if(@ is\_file ( $testImageFilename )){ // If an icon was found, set the icon reference value: $selectorBoxItem\_icon = '../' . substr ( $testImageFilename , strlen ( PATH\_site ));} // Finally add the new item: $params [ "items" ][]=Array( $selectorBoxItem\_title , basename ( $htmlFilePath ), $selectorBoxItem\_icon );}} // No return - the $params and $pObj variables are passed by reference, so just change content in them and it is passed back automatically... }}class tx\_tmplselect\_addfilestosel\_ca extends tx\_tmplselect\_addfilestosel {var $dir = "sub" ;}

There are two things to comment now:

First of all the class does a little trick by reading out the content of the <title> tag in the template files (this is why Mr. Raphael should name them carefully!). This title is used in the selector box. The class t3lib_parseHTML is used for that and the API is fully documented elsewhere.

Secondly the path from which the HTML-template files are read is stored in the hardcoded array $confArray. We might consider making this array configurable somehow. But we will just bypass that for now. Notice how it was the internal variable $this->dir that pointed out the position of the template records for both the main templates and content area templates. If we wanted a third or forth selector box for other kinds of templates it would be easily implemented by just another extension class.

The result will be two nice selector boxes just like this:

And if you look inside of them....

IMPORTANT NOTE on working with ext_tables.php and ext_localconf.php¶

When you are making changes to the files ext_tables.php and ext_localconf.php you must beware of two things:

• Don't make parsing errors!
• Always clear out the cache file in typo3conf/ - otherwise your changes will not take effect!

The reason is simple: Unless TYPO3 is configured otherwise all ext_tables.php and ext_localconf.php files from the installed extensions will be read from disc and concatenated to one, big file named something like "typo3conf/temp_CACHED_xxxxxx_ext_[localconf/tables].php". Thus TYPO3 needs to include only one file - not hundreds.

So from now on, every time you change one of these scripts in an extension it is implicit that you click this link to remove the cached files!

The downside is that changes made to the individual ext_localconf.php / ext_tables.php files in the installed extensions will not be shown unless you remove these cache-files first (they will automatically be rewritten upon the next page hit). That is what clicking the link on the image above does!

But you might be very unfortunate to introduce a fatal error in one of these files and if you do the cached file will have this error as well ... and in return TYPO3 will not work! The solution to the problem is that a) you locate the error-line in the cached file, identify the problem and fix it in the original ext_tables/localconf.php file in the extension, then b) you manually remove the cached files through the servers file system (since TYPO3 is unable to do that for you due to the error!).

Statistically this problem has proved to be of very little significance in both production and development environments but it should be clear to everyone that the installation, removal and development of extensions should always be done only if you are ultimately able to remove these files by other means than TYPO3s built-in tools.

Dummy icons, labels and SQL¶

We are almost finished with the backend work of the extension. I'll just direct your attension to a few features.

First, look in the ext_tables.sql file:

#
# Table structure for table 'pages'
#
CREATE TABLE pages (
        tx_tmplselect_main_tmpl int(11) unsigned DEFAULT '0' NOT NULL,
        tx_tmplselect_ca_tmpl int(11) unsigned DEFAULT '0' NOT NULL
);

As you can see the two new fields for the pages table is defined in this "pseudo-query" - if you piped it into MySQL it would not work well - it is rather used by the Extension Manager to control the database requirements for this extension.

But another thing is that the fields are defined to be integer fields - this is useless if we want to store a reference to a filename! So you should change the entries to this instead:

#
# Table structure for table 'pages'
#
CREATE TABLE pages (
        tx_tmplselect_main_tmpl varchar(32) DEFAULT '' NOT NULL,
        tx_tmplselect_ca_tmpl varchar(32) DEFAULT '' NOT NULL
);

Now you have to go to the Extension Manager in order to update the database as well:

... and :

After this everything should be cool.

Then look in the locallang_db.php file:

<?php /\*\*\* Language labels for database tables/fields belonging to extension "tmplselect"\*\* This file is detected by the translation tool.\*/ $LOCAL\_LANG =Array( "default" =>Array( "pages.tx\_tmplselect\_main\_tmpl.I.0" => "Default" , "pages.tx\_tmplselect\_main\_tmpl" => "Select template:" , "pages.tx\_tmplselect\_ca\_tmpl.I.0" => "Default" , "pages.tx\_tmplselect\_ca\_tmpl" => "Select content area template:" ,),); ?>

Here labels for the selector box labels and dummy items are defined. If you look in ext_tables.php you can easily see the references although it may at first seem a little complex:

$tempColumns = Array (
        "tx_tmplselect_main_tmpl" => Array (
                "exclude" => 1,
                "label" => "LLL:EXT:tmplselect/locallang_db.php:pages.tx_tmplselect_main_tmpl",
                "config" => Array (
                        "type" => "select",
                        "items" => Array (
                                Array(
                                        "LLL:EXT:tmplselect/locallang_db.php:pages.tx_tmplselect_main_tmpl.I.0",
                                        "0",
                                        t3lib_extMgm::extRelPath("tmplselect")."selicon_pages_tx_tmplselect_main_tmpl_0.gif"
                                ),
                        ),
                        "itemsProcFunc" => "tx_tmplselect_addfilestosel->main",
                )
        ),
        "tx_tmplselect_ca_tmpl" => Array (
                "exclude" => 1,
                "label" => "LLL:EXT:tmplselect/locallang_db.php:pages.tx_tmplselect_ca_tmpl",
                "config" => Array (
                        "type" => "select",
                        "items" => Array (
                                Array(
                                        "LLL:EXT:tmplselect/locallang_db.php:pages.tx_tmplselect_ca_tmpl.I.0",
                                        "0",
                                        t3lib_extMgm::extRelPath("tmplselect")."selicon_pages_tx_tmplselect_ca_tmpl_0.gif"
                                ),
                        ),
                        "itemsProcFunc" => "tx_tmplselect_addfilestosel_ca->main",
                )
        ),
);

The references are reproduced in bold above, the reference to the particular locallang-file is in teal color and the reference to the label inside the locallang file is in red .

This was just for your understanding of these references to labels from locallang files. Actually you can enter a label value directly instead of a "LLL: ...:" string but then you will bypass the internal translation framework of TYPO3 so you are really encouraged to use and extend the locallang_db.php file with more labels as you need them! It keeps your work "translatable".

Finally, lets substitute the two dummy icons with some better equalents from the "misc/" folder of the tutorial extension:

Copy "dummy_main.gif" and "dummy_ca.gif" to the extension folder of "tmplselect"

• Remove the old files, "selicon_pages_tx_tmplselect_ca_tmpl_0.gif" and "selicon_pages_tx_tmplselect_main_tmpl_0.gif"
• In ext_tables.php, find the references to the old filenames and insert the new.

The result will be this nice set of selectors:

Getting template right...¶

We will immediately begin writing the real plugin code needed for selecting the right template file. This code listing should totally substitute the existing class:

<?php require\_once( PATH\_tslib . "class.tslib\_pibase.php" );class tx\_tmplselect\_pi1 extends tslib\_pibase {var $prefixId = "tx\_tmplselect\_pi1" ; // Same as class name var $scriptRelPath = "pi1/class.tx\_tmplselect\_pi1.php" ; // Path to this script relative to the extension dir. var $extKey = "tmplselect" ; // The extension key./\*\* \* Reads the template-html file which is pointed to by the selector box on the page \* and type parameter send through TypoScript. \* cObject (Content Object) \* \* @paramstringEmpty content string passed. Not used. \* @paramarrayTypoScript properties that belongs to this Content Object. \* @returnstringThe content of the required file. \*/ function main ( $content , $conf ){ // configuration of paths for template files: $confArray =array( "main" => "fileadmin/template/main/" , "sub" => "fileadmin/template/sub/" ); // Getting the "type" from the input TypoScript configuration: switch((string) $conf [ 'templateType' ]){case 'sub' : $templateFile = $GLOBALS [ 'TSFE' ]-> page [ 'tx\_tmplselect\_ca\_tmpl' ]; $relPath = $confArray [ 'sub' ];break;case 'main' :default: $templateFile = $GLOBALS [ 'TSFE' ]-> page [ 'tx\_tmplselect\_main\_tmpl' ]; $relPath = $confArray [ 'main' ];break;} // Setting templateFile reference to the currently selected value - or the default if not set: $templateFile = $templateFile ? $templateFile : $conf [ 'defaultTemplateFileName' ];if( $relPath ){ // If a value was found, we dare to continue:// Get Absolute Filepath: $absFilePath = t3lib\_div :: getFileAbsFileName ( $relPath . $templateFile );if( $absFilePath &&@ is\_file ( $absFilePath )){ $content = t3lib\_div :: getUrl ( $absFilePath );return $content ;}}}} ?>

There are lots of comments in the script which will make you wise if you take time to read them. But for now I'll just lead your attention to these details:

• The $confArray known from the class for manipulation of the items array is also found here with the same information!
• Two "TypoScript properties" are expected: "templateType" and "defaultTemplateFileName". Notice that the only mandatory TypoScript property of a USER cObject is "userFunc" - all others are free for you to define the meaning and purpose of! And they are conveniently available in the $conf-array as you can see!
• The current page has its page record stored in the global object TSFE; $GLOBALS["TSFE"]->page (used in the script to get the value from the two custom fields we have added!)
• The API function, t3lib\_div :: getFileAbsFileName(), was used to fetch the absolute path and further verify the path validity of the template filepath before we read it. Does not check if the file or directory exists though.

Further we will create a new file in the root of our extension: "ext_typoscript_setup.txt". This file will contain default TypoScript code for the setup fields:

plugin.tx_tmplselect_pi1 {

          # Template type. Default is "main". Allowed values: "main", "sub"
        templateType = main

          # Refers to the default template file name to use
          # if no value is set for the current page
        defaultTemplateFileName =
}

This adds two TypoScript properties to the default representation of the plugin in the Object Tree:

(You will have to flush the cache-files to update this.)

Finally we will set the property ".defaultTemplateFile" for the plugin as used by the Template Auto-parser:

plugin.tx_automaketemplate_pi1.content.defaultTemplateFileName = template_1.html

This makes the Object Browser show this:

Now, hit the frontend of the page "License C":

Then change the main template of the page "License C":

... and hit the frontend again. You should see this now:

This confirms that our plugin correctly reads the file "fileadmin/template/main/template_2.html" if selected, otherwise it defaults to "fileadmin/template/main/template_1.html".

tmplselect¶

545: plugin.tx_tmplselect_pi1 {
546:
548:   templateType = main
549:
552:   defaultTemplateFileName =
553: }

ext: Auto-parser plugin¶

556: plugin.tx_automaketemplate_pi1 {
558:   content < plugin.tx_tmplselect_pi1
559:   content.defaultTemplateFileName = template_1.html
560:
563:   elements {
564:     BODY.all = 1
565:     BODY.all.subpartMarker = DOCUMENT_BODY
566:
567:     HEAD.all = 1
568:     HEAD.all.subpartMarker = DOCUMENT_HEADER
569:     HEAD.rmTagSections = title
570:
571:     TD.all = 1
572:     TR.all = 1
573:   }
574:
576:   relPathPrefix = fileadmin/template/main/
577: }

ext: Menu 1¶

580: # ------------------------
581: # Menu 1 cObject - vertical 2-level menu
582: # ------------------------
583:
584: temp.menu_1 = HMENU
585:
586:   # First level menu-object, textual
587: temp.menu_1.1 = TMENU
588: temp.menu_1.1 {
589:     # Normal state properties
590:   NO.allWrap = <div class="menu1-level1-no"> | </div>
591:
592:     # Enable active state and set properties:
593:   ACT = 1
594:   ACT.allWrap = <div class="menu1-level1-act"> | </div>
595: }
596:
597:   # Second level menu-object, textual
598: temp.menu_1.2 = TMENU
599: temp.menu_1.2 {
600:     # Normal state properties
601:   NO.allWrap = <div class="menu1-level2-no"> | </div>
602:
603:     # Enable active state and set properties:
604:   ACT = 1
605:   ACT.allWrap = <div class="menu1-level2-act"> | </div>
606: }
607:
608:
609:
610: # ------------------------
611: # Menu 2 cObject - horizontal, one-level menu
612: # ------------------------
613:
614: temp.menu_2 = HMENU
615:   # Setting the entryLevel to be subpages to CURRENT page:
616: temp.menu_2.entryLevel = -1
617:
618:   # First level menu-object, textual
619: temp.menu_2.1 = TMENU
620: temp.menu_2.1 {
621:     # Normal state wrapping with alternating wrap-values (see "optionSplit")
622:   NO.allWrap =  |*|   <td>|</td>  ||  <td class="oddcell">|</td>   |*|
623:
624:     # Enable active state and set properties:
625:   ACT = 1
626:   ACT.allWrap = <td class="menu2-level1-act"> | </td>
627: }
628:
629:
630:
631:
632: # ------------------------
633: # Path menu cObject
634: # ------------------------
635:
636: temp.path = HMENU
637:   # Setting the special property to "rootline" - this will produce a "Path-menu"
638: temp.path.special = rootline
639:
640:   # First level menu-object, textual
641: temp.path.1 = TMENU
642:   # Wrapping value for the whole menu:
643: temp.path.1.wrap = Path: &nbsp; |
644: temp.path.1 {
645:     # Normal state properties appending " > " to all elements but the last one.
646:     # (See "optionSplit")
647:   NO.allWrap =   |&nbsp;&gt;&nbsp; |*||*|   |
648: }

ext: Main TEMPLATE cObject¶

654: # Main TEMPLATE cObject for the BODY
655: temp.mainTemplate = TEMPLATE
656: temp.mainTemplate {
657:     # Feeding the content from the Auto-parser to the TEMPLATE cObject:
658:   template =< plugin.tx_automaketemplate_pi1
659:     # Select only the content between the <body>-tags
660:   workOnSubpart = DOCUMENT_BODY
661:
662:     # Substitute the ###menu_1### subpart with dynamic menu:
663:   subparts.menu_1 < temp.menu_1
664:
665:     # Substitute the ###menu_2### subpart with dynamic menu:
666:   subparts.menu_2 < temp.menu_2
667:
668:     # Substitute the ###path### subpart with dynamic path menu:
669:   subparts.path < temp.path
670:
671:     # Substitute the ###content### subpart with some example content:
672:   subparts.content < styles.content.get
673: }

NEW SITE¶

678: # Main TEMPLATE cObject for the HEAD
679: temp.headTemplate = TEMPLATE
680: temp.headTemplate {
681:     # Feeding the content from the Auto-parser to the TEMPLATE cObject:
682:   template =< plugin.tx_automaketemplate_pi1
683:     # Select only the content between the <head>-tags
684:   workOnSubpart = DOCUMENT_HEADER
685: }
686:
687:
688:
689:
690: # Default PAGE object:
691: page = PAGE
692: page.typeNum = 0
693:
694: # Copying the content from TEMPLATE for <body>-section:
695: page.10 < temp.mainTemplate
696:
697: # Copying the content from TEMPLATE for <head>-section:
698: page.headerData.10  < temp.headTemplate

Setting a different default template for a section¶

The current set up allows Mr. Picouto to select an alternative template for each page he creates. The default template is "template_1.html" and "template_2.html" must be selected explicitly in the page header if he wants that.

However for the whole section "Terms & Conditions" Mr. Picouto wants "template_2.html" to be used by default!

This is very easy in TYPO3. Mr. Benoit simply has to create a single template record on the page "Terms & Conditions" and then override the definition of the default template file:

From the Template Analyzer it looks like this:

Notice how the extension template on the "Terms & Conditions" page is the last one included and thus any Setup code will be able to override previous values!

Now Benoit simply uses the Object Browser to locate the property, click the link (remember to have "Enable object links" turned on), edit the value and - voilá:

In the frontend this now means that all pages from "Terms & Conditions" by default will use template_2.html unless another selection is made in the page header for individual pages!

The "mininews" plugin¶

Now you should connect to TER (TYPO3 Extension Repository) from the Extension Manager. Import the "mininews" extension and install it:

Then create a few news items on the page "License C":

Finally just modify the inclusion template "ext: CA TEMPLATE cObject" like this:

. . .
  subparts {
    colNormal < styles.content.get
    colLeft < styles.content.getLeft
    colRight < styles.content.getRight
    news-pi < plugin.tx_mininews_pi1
    news-pi.CMD = FP
  }
}

This will insert the mininews plugin cObject in the subpart "news-pi" (which was the id-attribute of the table cell where the dummy-content for the mininews plugin was found in Mr. Raphaels template!)

The result is convincing:

So now everything is running!

Creating a configuration template file¶

In the root of the "tmplselect" extension (the one we are working on...), create a file named "ext_conf_template.txt":

  # cat=basic//; type=string; label=Main Template folder: Enter the folder relative to the PATH_site where the main templates are placed.
main = fileadmin/template/main/

  # cat=basic//; type=string; label=Content Area Template folder: Enter the folder relative to the PATH_site where the content area templates are stored.
sub = fileadmin/template/sub/

Now, in the Extensions Manager you will find these two fields for the extension "tmplselect":

Press the Update button and the values in the form are written in a serialized string to a reserved key for the "tmplselect" extension in $TYPO3_CONF_VARS in typo3conf/localconf.php:

$TYPO3_CONF_VARS["EXT"]["extConf"]["tmplselect"] = 'a:2:{s:3:"sub";s:23:"fileadmin/template/sub/";s:4:"main";s:24:"fileadmin/template/main/";}';     //  Modified or inserted by Typo3 Extension Manager.

These values can then be extracted by the two classes using them:

class.tx_tmplselect_addfilestosel.php

. . .
        function main(&$params,&$pObj)  {
                  // GETTING configuration for the extension:
          $confArray = unserialize($GLOBALS["TYPO3_CONF_VARS"]["EXT"]["extConf"]["tmplselect"]);

                        // Finding value for the path containing the template files.
                $readPath = t3lib_div::getFileAbsFileName($confArray[$this->dir]);
. . .

pi1/class.tmplselect_pi1.php

. . .
        function main($content,$conf)   {
                  // GETTING configuration for the extension:
          $confArray = unserialize($GLOBALS["TYPO3_CONF_VARS"]["EXT"]["extConf"]["tmplselect"]);

                        // Getting the "type" from the input TypoScript configuration:
                switch((string)$conf['templateType'])           {
. . .

The "template selector manual"¶

I would like to point out that our "reverse engineering" of Raphaels original templates should in the end - after the construction and implementation of the template selector - be reversed into a manual for the template designer.

Mr. Raphael has the power to add new templates in fileadmin/template/ without Mr. Benoit being involved. However Benoit created a technical framework which accepts only certain input from Mr. Raphael.

In the section "Investigating the source material" we ended up with two tables that told Benoit what selectors he needed to support in his template. This should be reversed now in order to become a manual for Raphael to design more templates!

Main templates:

Skill level¶

In order to complete this level you should be an advanced TYPO3 user and PHP expert. You should be a developer.

Filtering out "disabled records"¶

Whenever records from tables configured in $TCA are selected in the context of the frontend for display on webpages the function enableFields() is called (should be!) with the table name as argument. It might look like this:

. . .
                } else {
                        $query="FROM ".$table." WHERE pid IN (".$pidList.")".chr(10).
                                        $this->cObj->enableFields($table);
                }
. . .

$this->cObj is normally available in plugins and is the parent object which is an instance of the class "tslib_cObj" from the file "class.tslib_content.php".

So in tslib/class.tslib_content.php we will find the function enableFields() - but just to see it act as a simple wrapper for the function $GLOBALS["TSFE"]->sys_page->enableFields()

$TSFE is an instance of the class "tslib_fe" and looking inside of "tslib/class.tslib_fe.php" we will find that $GLOBALS["TSFE"]->sys_page is an instance of the class "t3lib_pageSelect".

The class "t3lib_pageSelect" is found in "t3lib/class.t3lib_page.php". Now we should be there:

function enableFields ( $table , $show\_hidden =- 1 , $ignore\_array =array()){if( $show\_hidden ==- 1 && is\_object ( $GLOBALS [ "TSFE" ])){ $show\_hidden = $table == "pages" ? $GLOBALS [ "TSFE" ]-> showHiddenPage : $GLOBALS [ "TSFE" ]-> showHiddenRecords ;}if( $show\_hidden ==- 1 ) $show\_hidden = 0 ; $ctrl = $GLOBALS [ "TCA" ][ $table ][ "ctrl" ]; $query = "" ;if( is\_array ( $ctrl )){if( $ctrl [ "delete" ]){ $query .= " AND NOT " . $table . "." . $ctrl [ "delete" ];}if( is\_array ( $ctrl [ "enablecolumns" ])){if( $ctrl [ "enablecolumns" ][ "disabled" ]&&! $show\_hidden &&! $ignore\_array [ "disabled" ]){ $field = $table . "." . $ctrl [ "enablecolumns" ][ "disabled" ]; $query .= " AND NOT " . $field ;}if( $ctrl [ "enablecolumns" ][ "starttime" ]&&! $ignore\_array [ "starttime" ]){ $field = $table . "." . $ctrl [ "enablecolumns" ][ "starttime" ]; $query .= " AND (" . $field . "<=" . $GLOBALS [ "SIM\_EXEC\_TIME" ]. ")" ;}if( $ctrl [ "enablecolumns" ][ "endtime" ]&&! $ignore\_array [ "endtime" ]){ $field = $table . "." . $ctrl [ "enablecolumns" ][ "endtime" ]; $query .= " AND (" . $field . "=0 OR " . $field . ">" . $GLOBALS [ "SIM\_EXEC\_TIME" ]. ")" ;}if( $ctrl [ "enablecolumns" ][ "fe\_group" ]&&! $ignore\_array [ "fe\_group" ]){ $field = $table . "." . $ctrl [ "enablecolumns" ][ "fe\_group" ]; $gr\_list = $GLOBALS [ "TSFE" ]-> gr\_list ;if(! strcmp ( $gr\_list , "" )) $gr\_list = 0 ; $query .= " AND " . $field . " IN (" . $gr\_list . ")" ;}}}else{die( "NO entry in the \$TCA-array for '" . $table . "'" );}return $query ;}

This function simply looks in the "ctrl" section of $TCA for the table and will put together the part of the WHERE clause that will filter out all records that should be hidden according to the settings for the enablefields, if any.

This is the general theory.

User defined extension¶

1: Create a directory in typo3conf/ext/ named "user_accessctrl"

2: Create a file named "ext_emconf.php" in "user_accessctrl/":

<?php

$EM_CONF[$_EXTKEY] = Array (
    'title' => 'New Access Control',
    'version' => '0.0.0'
);

?>

3: Create a file named "ext_localconf.php" in "user_accessctrl/":

<?php

$TYPO3_CONF_VARS["FE"]["XCLASS"]["t3lib/class.t3lib_page.php"] =
        t3lib_extMgm:extPath('user_accessctrl').'class.ux_t3lib_pageSelect.php';

?>

4: Create a file named "class.ux_t3lib_pageSelect.php" in "user_accessctrl/":

<?php

class ux_t3lib_pageSelect extends t3lib_pageSelect {

    /**
     * Extending function for enableFields()
     */
    function enableFields($table,$show_hidden=-1,$ignore_array=array())    {
            // Call parent function (the original!)
        $return_value = parent::enableFields($table,$show_hidden,$ignore_array);

            // Output the value so we can see what is produced:
        t3lib_div::debug(array($return_value));

            // Return the value:
        return $return_value;
    }
}

?>

Then go to the Extension Manager and install the extension:

... Oups:

Parse error: parse error in /www/htdocs/typo3/32/dummy_tut/typo3conf/temp_CACHED_pseed3_ext_localconf.php on line 121
Typo3 Fatal Error: Extension key "cms" was NOT loaded!

The solution to this problem is a) not to panic and then b) open the file "temp_CACHED_pseed3_ext_localconf.php" and find the problem:

Apparently a ":" (colon) was missing! So...

• a) we add the colon here so the file does not generate a parse error and
• b) we add the colon in the source file located in ... user_accessctrl/ext_localconf.php!

(The weird thing is that line 121 had nothing to do with this problem...)

Anyways, after this little intermezzo our extension should be installed and if we clear the cache and hit the frontend of page "License C" we should see something like this:

This debug information was outputted by the function t3lib_div::debug() which was found in our extension function of the enableFields() function.

The WHERE clause¶

As you can see from the screen dump the enableFields() function was called three times for the "tt_content" table - that is reasonable since we insert page content elements three times on this page!

The WHERE clause returned by parent::enableFields() is this:

AND NOT tt_content.deleted
AND NOT tt_content.hidden
AND (tt_content.starttime<=1047535575)
AND (tt_content.endtime=0 OR tt_content.endtime>1047535575)
AND tt_content.fe_group IN (0,-1)

The first line checks for the mandatory "deleted" field, the other four checks for the hidden, starttime, endtime and fe_groups.

Removing the check for "fe_group"¶

Now, add this file, "ext_tables.php", to the extension:

<?phpt3lib\_div :: loadTCA ( 'tt\_content' );unset( $TCA [ 'tt\_content' ][ 'ctrl' ][ 'enablecolumns' ][ 'fe\_group' ]); ?>

Clear all cache, clear cache files and reload the frontend. The WHERE clause for tt_content elements is now reduced to:

AND NOT tt_content.deleted
AND NOT tt_content.hidden
AND (tt_content.starttime<=1047536630)
AND (tt_content.endtime=0 OR tt_content.endtime>1047536630)

As you can see the check for the "tt_content.fe_group" field is not included anymore since we removed the definition of this column from the "enablecolumns" key of the "ctrl" section for the table "tt_content".