Jul 11, 2008

Using templates in TYPO3 Frontend

Firsts, I wanted to write a warning article about the substituteMarkerArrayCached function. But then I understood that article is going to be about template functions in general and warning should be in the different article.

Let's have an overview of TYPO3 templates and functions to handle them.

TYPO3 template basics

Templates in TYPO3 are normal HTML files. These files contain special markers that TYPO3 can replace with data. Markers typically are words in CAPS surrounded by three hash marks. For example: ###LINK###.

There are two types of markers: single markers and subpart markers. Single markers is a single piece of data, it is replaced as is. Subpart markers surround parts of the HTML code. Here is an example:

<!-- ###LIST### begin -->
Repeating elements:
<ul>
  <!-- ###REPEATING### begin -->
  <li>Iteration ###NUMBER###</li>
  <!-- ###REPEATING### end -->
  </ul>
<!-- ###LIST### end -->

Here ###LIST### and ###REPEATING### are subpart markers. Extension can get a subpart and replace it as whole. Often it is used for repeating elements of for subparts that should be removed under certain conditions. “begin” and “end” are not necessary but conventional.

###NUMBER### is a single marker.

Template functions in TYPO3 Frontend

TYPO3 has functions to work with templates. Extension authors may use these function to process markers.

The functions are located in class tslib_cObj and available in Frontend plugins through $this->cObj. Here is the list:

  • getSubpart
    Obtains a subpart from template
  • substituteMarker
    This function substitutes a single marker. Just that.
  • substituteMarkerArray
    This function does the same as above but for many markers in the array
  • substituteSubpart
    Substitutes a single subpart
  • substituteMarkerArrayCached
    This is a bad function that you should not use. Read why.

As you see, there is no function to substitute subpart array. You have to do it in a loop for each subpart.

Using TYPO3 template functions

But let's see code example. Example assumes that HTML template is located in $this->templateCode.

function generateRepeatingContent() {
  // Get template
  $template = $this->cObj->getSubpart($this->templateCode, '###LIST###');
  // Get subpart template
  $subTemplate = $this-cObj->getSubpart($template, '###REPEATING###');
  // Loop to create repeating content
  $subPartContent = '';
  for ($i = 1; $i <= 10; $i++) {
    $subPartContent .= $this->cObj->substituteMarker($subTemplate,
'###NUMBER###', $i);
  }
  // Substitute subpart
  return $this->cObj->substituteSubpart($template, '###REPEATING###',
$subPartContent);
}

This example uses the same template as shown above.

Conclusion

This is how easy to use templates in TYPO3. So when you develop extension next time, you can make it better by providing templatable output for your extension.

No comments:

Post a Comment