Extension Development, using HTML-Templates

From TYPO3Wiki

<< Back to Extension Development << Back to Developer manuals page

[edit] Introduction

This document is a guide mainly for extension developers, explaining the basic steps to create a html template for the use in extension development. Use with caution.

[edit] Preparation

setting up ext_typoscript_setup.txt:

<TS> :

 
 plugin.tx_myextension_pi1.templateFile = EXT:my_extension_key/template.html

creating a html-template:

<XML> :

 
 <h3>TEMPLATE</h3>
 <em>This is a simple HTML-Template</em> 
 <!-- ###TEMPLATE### begin -->
  <h1>###MARKER1###</h1><h1>###MARKER2###</h1>
 <!-- ###TEMPLATE### end -->

in class.tx_myext_pi1.php:

<PHP> :

 
   // Get the template
 $this->templateCode = $this->cObj->fileResource($conf['templateFile']);
 
   // Get the parts out of the template
 $template['total'] = $this->cObj->getSubpart($this->templateCode,'###TEMPLATE###');
 
   // Fill marker
 $markerArray['###MARKER1###'] = 'content for marker 1';
 $markerArray['###MARKER2###'] = 'content for marker 2';
 
   // Finalize and create the content by replacing the "content" marker in the template
 $content = $this->cObj->substituteMarkerArrayCached($template['total'],$markerArray);

Notice : the function used to finalize and create the content by replacing the "content" marker in the template must be use with care. If the substitution is simple, use substituteMarkerArray() instead of substituteMarkerArrayCached(), it is faster. More informations here.

[edit] Subparts

Are useful for filling rows.

The subparts template (the markers between the  will be replaced with the content from the database):

<XML> :

 
 <h3>TEMPLATE</h3>
 <em>This is a more complex html template</em>
 <!-- ###TEMPLATE### begin -->
  <table>
   <!-- ###CONTENT### -->
    <!-- ###ITEM### -->
     <tr>
      <td>###MARKER1###</td><td>###MARKER2###</td>
     </tr>
    <!-- ###ITEM### -->
   <!-- ###CONTENT### -->
  </table>
 <!-- ###TEMPLATE### end -->

<PHP> :

 
  // Get the template
 $this->templateCode = $this->cObj->fileResource($this->conf['templateFile']);
 
   // Get the parts out of the template
 $template['total'] = $this->cObj->getSubpart($this->templateCode,'###TEMPLATE###');
 $template['item'] = $this->cObj->getSubpart($template['total'],'###ITEM###');
 
   // Your SQL query comes here:
 ... 
 ...
 ...
 
   // Loop through query result
 while ($row = $GLOBALS['TYPO3_DB']->sql_fetch_assoc($res)) {
 
   // Fill marker
  $markerArray['###MARKER1###'] = $row['username'];             
  $markerArray['###MARKER2###'] = $row['price']; 
 
    // Add subpart into a string
  $content_item .= $this->cObj->substituteMarkerArrayCached($template['item'], $markerArray);
 }   
 
   // Fill subpart marker
 $subpartArray['###CONTENT###'] = $content_item; 
 
   // Finalize and create the content by replacing the "content" marker in the template  
 $content = $this->cObj->substituteMarkerArrayCached($template['total'], array(), $subpartArray);

[edit] Wrapped Subparts

Are useful for links.

The wrapped subparts template:

<XML> :

 
 <h3>TEMPLATE</h3>
 <em>This is an example template for wrapped subparts</em>
 <!-- ###TEMPLATE### begin -->
  <table border="1" cellpadding="2">
   <tr><td><!--###LINK###-->Click me!<!--###LINK###--></td></tr>
  </table>
 <!-- ###TEMPLATE### end -->

<PHP> :

 
   // configure the typolink
 $this->local_cObj = t3lib_div::makeInstance('tslib_cObj');
 $this->local_cObj->setCurrentVal($GLOBALS['TSFE']->id);
 $this->typolink_conf = $this->conf['typolink.'];
 $this->typolink_conf['parameter.']['current'] = 1;
 
  // Get the template
 $this->templateCode = $this->cObj->fileResource($this->conf['templateFile']);
 
   // Get the parts out of the template
 $template['total'] = $this->cObj->getSubpart($this->templateCode,'###TEMPLATE###');
 
  // configure typolink
 $temp_conf = $this->typolink_conf;
 $temp_conf['additionalParams'].= '&tx_myextension_pi1[mode]=list&tx_myextension_pi1[cat]='.$row['uid'];
 $temp_conf['useCacheHash']=$this->allowCaching;                            
 $temp_conf['no_cache']=!$this->allowCaching;
 $temp_conf['parameter.']['wrap'] = "|,".$GLOBALS['TSFE']->type;
 
   // Fill wrapped subpart marker
 $wrappedSubpartContentArray['###LINK###'] = $this->local_cObj->typolinkWrap($temp_conf); 
 
  // Finalize and create the content by replacing the "content" marker in the template
 $content = $this->cObj->substituteMarkerArrayCached($template['total'],array(),array(), $wrappedSubpartContentArray);

Hints

If you have many markers to replace, you can do a loop:

<PHP> :

 
 $arrayAll = array('uid', 'brand', 'name', ...);
 foreach ($arrayAll as $marker) {
  $markerArray['###'.strtoupper($marker).'###'] = $this->pi_getLL($marker); 
 }

[edit] Example

The template:

<XML> :

 
 <h3>TEMPLATE</h3>
 <em>This is yet another example template</em>
 <!-- ###TEMPLATE### begin -->
   <h1>###MARKER1###</h1><h1>###MARKER2###</h1>
   <table>
   <!-- ###CONTENT### -->
    <!-- ###ITEM### -->
     <tr>
      <td>###MARKER3###</td><td>###MARKER4###</td>
     </tr>
    <!-- ###ITEM### -->
   <!-- ###CONTENT### -->
  </table>
  <table border="1" cellpadding="2">
   <tr><td><!--###LINK###-->Click me!<!--###LINK###--></td></tr>
  </table> 
 <!-- ###TEMPLATE### end -->

<PHP> :

 
   // Get the parts out of the template
 $template = array();
 $template['total'] = $this->cObj->getSubpart($this->templateCode,'###TEMPLATE###');
 $template['item'] = $this->cObj->getSubpart($template['total'],'###ITEM###');
 
 
 $markerArray['###MARKER1###'] = $this->pi_getLL('MARKER1');
 $markerArray['###MARKER2###'] = $this->pi_getLL('MARKER2');
 
   // Your SQL query comes here:
 ... 
 ...
 ...
 
  // Loop through query result
 while ($row = $GLOBALS['TYPO3_DB']->sql_fetch_assoc($res)) {
    // Fill marker
  $markerArray['###MARKER3###'] = $row['username'];             
  $markerArray['###MARKER4###'] = $row['price']; 
 
    // add subpart into a string
  $content_item .= $this->cObj->substituteMarkerArrayCached($template["item"], $markerArray);
 }   
 
   // Fill subpart marker
 $subpartArray['###CONTENT###'] = $content_item; 
 
   // config typolink
 $temp_conf = $this->typolink_conf;
 $temp_conf["additionalParams"].= '&tx_myextension_pi1[mode]=list&tx_myextension_pi1[cat]='.$row['uid'];
 $temp_conf['useCacheHash']=$this->allowCaching;                            
 $temp_conf['no_cache']=!$this->allowCaching;
 $temp_conf['parameter.']['wrap'] = "|,".$GLOBALS['TSFE']->type;
 
   // Fill wrapped subpart marker
 $wrappedSubpartContentArray['###LINK###'] = $this->local_cObj->typolinkWrap($temp_conf); 
 
   // Finalize and create the content by replacing the marker in the template
 $content = $this->cObj->substituteMarkerArrayCached($template['total'], $markerArray, $subpartArray,  $wrappedSubpartContentArray);

[edit] Colorized rows

For nice tables with colorized rows, you can use the subparts function of Typo3:

<XML> :

 
  <h3>TEMPLATE</h3>
 <em>This is the template for colorized rows</em>
 <!-- ###TEMPLATE### begin -->
  <table>
  <!-- ###SINGLEROW### begin -->
    <!-- ###ITEM### -->
     <tr bgcolor="#e0e0e0">
      <td>###MARKER1###</td><td>###MARKER2###</td>
     </tr>
    <!-- ###ITEM### -->
    <!-- ###ITEM_ALT### -->
     <tr>
      <td>###MARKER1###</td><td>###MARKER2###</td>
     </tr>
    <!-- ###ITEM_ALT### -->
  <!-- ###SINGLEROW### end --> 
  </table>
 <!-- ###TEMPLATE### end -->

<PHP> :

 
   // Get the template
 $this->templateCode = $this->cObj->fileResource($this->conf['templateFile']);
 
   // Get the parts out of the template
 $template['total'] = $this->cObj->getSubpart($this->templateCode,'###TEMPLATE###');
 $template['singlerow'] = $this->cObj->getSubpart($template['total'],'###SINGLEROW###');
 $template['row'] = $this->cObj->getSubpart($template['singlerow'],'###ITEM###');
 $template['row_alt'] = $this->cObj->getSubpart($template['singlerow'],'###ITEM_ALT###');	
 
 $switch_row = 0;
 
  // Your sql query comes here: 
 ...
 ...
 ...
 
  // Loop through the query result
 while ($row = $GLOBALS['TYPO3_DB']->sql_fetch_assoc($res)) {
 
    // Fill marker
  $markerArray['###MARKER1###'] = $row['username'];             
  $markerArray['###MARKER2###'] = $row['price'];
 
  $switch_row = $switch_row ^ 1;
  if($switch_row) {
  	$content_item .= $this->cObj->substituteMarkerArrayCached($template['row'], $markerArray);
  } else {
  	$content_item .= $this->cObj->substituteMarkerArrayCached($template['row_alt'], $markerArray);
  }
 }   
 
   // Fill the marker with the added string
 $subpartArray['###SINGLEROW###'] = $content_item; 
 
   // Finalize and create the content by replacing the marker in the template
 $content = $this->cObj->substituteMarkerArrayCached($template['total'], array(), $subpartArray);

Explanation:

this line: <PHP> :

 
  $switch_row = $switch_row ^ 1;

is a xor-operation. It can be useful for encryption, too. Imagine this function: <PHP> :

 
<?php
    function _xor($message, $key)
    {
        $keylen = strlen($key);
        $messagelen = strlen($message);
 
        for($i=0; $i<$messagelen; $i++)
            $message[$i] = ~($message[$i]^$key[$i%$keylen]);
 
        return $message;
    }
?>
 
To crypt :
<?php
    echo _xor('My string', 'key');
?>
 
To decrypt :
<?php
    echo _xor('?âíµ½¹¯£ý', 'key');
?>

You can do the same thing with a modulus-operation:

<PHP> :

 
  $alt_row = $switch_row % 2;
  if($alt_row) {
  	$content_item .= $this->cObj->substituteMarkerArrayCached($template['row'], $markerArray);
  } else {
  	$content_item .= $this->cObj->substituteMarkerArrayCached($template['row_alt'], $markerArray);
  }
  $switch_row++;

This way you have a row counter at the same time, and thus can limit the output or include a pagebrowser. Of course you can replace the line

<PHP> :

 
$alt_row = $switch_row % 2;

with any other number greater or equal then 2. This will result in coloring every 3th, 4th, 5th row.

[edit] Links

Extension mit HTML-Vorlage

--Chibox 15:37, 12 February 2008 (CET)

Extension Development, using HTML-Templates

From TYPO3Wiki

Contents

[edit] Introduction

[edit] Preparation

[edit] Subparts

[edit] Wrapped Subparts

[edit] Example

[edit] Colorized rows

[edit] Links

Views

Personal tools

Search

content

people

help 'N' beginners

Search

Toolbox