Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

Extension Development, using HTML-Templates

From TYPO3Wiki
Jump to: navigation, search

<< 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 an HTML template for the use in extension development. Use with caution.

Preparation

  • Set up ext_typoscript_setup.txt:
plugin.tx_myextension_pi1.templateFile = EXT:my_extension_key/template.html
  • Create the HTML template:
<html>
	<h3>TEMPLATE</h3>
	<p>This is a simple HTML template.</p>
	<!-- ###TEMPLATE### begin -->
	<h1>###MARKER1###</h1>
	<h1>###MARKER2###</h1>
	<!-- ###TEMPLATE### end -->
</html>
  • In class.tx_myext_pi1.php:
// Get the template
$this->templateHtml = $this->cObj->fileResource($conf['templateFile']);
 
// Extract subparts from the template
$subpart = $this->cObj->getSubpart($this->templateHtml, '###TEMPLATE###');
  
// Fill marker array
$markerArray['###MARKER1###'] = 'content for marker 1';
$markerArray['###MARKER2###'] = 'content for marker 2';
 
// Create the content by replacing the content markers in the template
$content = $this->cObj->substituteMarkerArrayCached($subpart, $markerArray);

Notice: Use substituteMarkerArrayCached() with care. If the substitution is simple, use substituteMarkerArray() instead of substituteMarkerArrayCached(), as it is faster and doesn't clog the TYPO3 cache.

Subparts

Are useful for (among other uses) filling table rows.

  • The subparts template (the markers between the markers will be replaced with the content from the database):
<html>
	<h3>TEMPLATE</h3>
	<p>This is a more complex HTML template</p>
	<!-- ###TEMPLATE### begin -->
		<table>
		<!-- ###CONTENT### -->
			<!-- ###ITEM### -->
				<tr>
					<td>###MARKER1###</td>
					<td>###MARKER2###</td>
				</tr>
			<!-- ###ITEM### -->
		<!-- ###CONTENT### -->
		</table>
	<!-- ###TEMPLATE### end -->
</html>

  • In class.tx_myext_pi1.php:
// Read the template
$this->templateHtml = $this->cObj->fileResource($this->conf['templateFile']);
 
// Extract subparts from the template
$subparts['template'] = $this->cObj->getSubpart($this->templateHtml, '###TEMPLATE###');
$subparts['item'] = $this->cObj->getSubpart($subparts['template'], '###ITEM###');

// Your SQL query comes here:
... 
...
...

// Loop through query result
$contentItem = ;
while ($row = $GLOBALS['TYPO3_DB']->sql_fetch_assoc($res)) {
	// Fill marker array
 	$markerArray['###MARKER1###'] = $row['username'];             
 	$markerArray['###MARKER2###'] = $row['price']; 
   
   // Substitute markers and append to result string
   $contentItem .= $this->cObj->substituteMarkerArrayCached($subparts['item'], $markerArray);
}   

// Fill subpart marker
$subpartArray['###CONTENT###'] = $contentItem; 

// Complete the template expansion by replacing the "content" marker in the template  
$content = $this->cObj->substituteSubpartArrayCached($subparts['template'], null, $subpartArray);

Wrapped subparts

Are useful (among other uses) for links.

  • The wrapped subparts template:
<html>
	<h3>TEMPLATE</h3>
	<p>This is an example template for wrapped subparts</p>
	<!-- ###TEMPLATE### begin -->
		<table border="1" cellpadding="2">
			<tr>
				<td><!--###LINK###-->Click me!<!--###LINK###--></td>
			</tr>
		</table>
	<!-- ###TEMPLATE### end -->
</html>
  • In class.tx_myext_pi1.php:
// configure typolink functionality for this class
$this->localCObj = t3lib_div::makeInstance('tslib_cObj');
$this->localCObj->setCurrentVal($GLOBALS['TSFE']->id);
$this->typolinkConf = $this->conf['typolink.'];
$this->typolinkConf['parameter.']['current'] = 1;

// Read the template
$this->templateHtml = $this->cObj->fileResource($this->conf['templateFile']);
 
// Extract the subparts from the template
$subparts['template'] = $this->cObj->getSubpart($this->templateHtml, '###TEMPLATE###');
  
// Configure typolink functionality for use
$typolinkConf = $this->typolinkConf;
$typolinkConf['additionalParams'] .= '&tx_myextension_pi1[mode]=list&tx_myextension_pi1[cat]='.$row['uid'];
$typolinkConf['useCacheHash'] = $this->allowCaching;                            
$typolinkConf['no_cache'] = !$this->allowCaching;
$typolinkConf['parameter.']['wrap'] = '|,'.$GLOBALS['TSFE']->type;

// Fill 'typolinkWrap'd subpart marker
$wrappedSubpartContentArray['###LINK###'] = $this->localCObj->typolinkWrap($typolinkConf); 
 
// Complete the template expansion by replacing the "content" marker in the template 
$content = $this->cObj->substituteMarkerArrayCached($subparts['template'], null, null, $wrappedSubpartContentArray); 


Localization

Use tslib_pibase->pi_getLL() to retrieve localized strings from your extension's translation files.

Example

...
$markerArray['###MARKER1###'] = $this->pi_getLL('MARKER1');
$markerArray['###MARKER2###'] = $this->pi_getLL('MARKER2');
...

BONUS EXAMPLE: Colorized rows

  • This example shows how to use the subparts functions to create a table with alternating row colors. To see the effect, you need to handle the different CSS classes (.even and .odd) classes in your CSS.
<html>
	<h3>TEMPLATE</h3>
	<p>This is the template for colorized rows</p>
	<!-- ###TEMPLATE### begin -->
		<table>
		<!-- ###SINGLEROW### begin -->
			<!-- ###ITEM### -->
				<tr class="even">
					<td>###MARKER1###</td>
					<td>###MARKER2###</td>
				</tr>
			<!-- ###ITEM### -->

			<!-- ###ITEM_ALT### -->
				<tr class="odd">
					<td>###MARKER1###</td>
					<td>###MARKER2###</td>
				</tr>
			<!-- ###ITEM_ALT### -->
		<!-- ###SINGLEROW### end -->
		</table>
	<!-- ###TEMPLATE### end -->
</html>
  • In class.tx_myext_pi1.php:
 // Read the template
 $this->templateCode = $this->cObj->fileResource($this->conf['templateFile']);
  
 // Extract the subparts from the template
 $subparts['template'] = $this->cObj->getSubpart($this->templateCode, '###TEMPLATE###');
 $subparts['singlerow'] = $this->cObj->getSubpart($subparts['template'], '###SINGLEROW###');
 $subparts['row'] = $this->cObj->getSubpart($subparts['singlerow'], '###ITEM###');
 $subparts['row_alt'] = $this->cObj->getSubpart($subparts['singlerow'], '###ITEM_ALT###');	
 		
 // Your SQL query comes here: 
 ...
 ...
 ...
 
 $contentItem = '';
 $rowIndex = 0;
 // Loop through the query result
 while ($row = $GLOBALS['TYPO3_DB']->sql_fetch_assoc($res)) {
	// Fill marker array
	$markerArray['###MARKER1###'] = $row['username'];             
	$markerArray['###MARKER2###'] = $row['price'];
	
	$isEvenRow = !($rowIndex % 2);
	$rowSubpart = $subparts[$isEvenRow ? 'row' : 'row_alt'];
	$contentItem .= $this->cObj->substituteMarkerArrayCached($rowSubpart, $markerArray);
	++$rowIndex;
 }   
 
 // Fill the row marker with the expanded rows
 $subpartArray['###SINGLEROW###'] = $contentItem; 
  
 // Complete the template expansion by replacing the "content" marker in the template 
 $content = $this->cObj->substituteMarkerArrayCached($subparts['template'], null, $subpartArray);