Ajado

What is this about?

A while ago I figured out that a lot of extension developers like to make up their own TypoScript parameter names, even when it would not be necessary. That bothered me for a long time now, in this article I will explain why.

The problem:

TypoScript is very powerful, but it gets painful when every developer uses his/her own name for the same things:

headerImageWidth = 55
header.image-widht = 566
header.width-max = 34

tt_news is a perfect example for a suboptimal configuration structure, and everyday before I go to bed I pray that there will a complete rewrite of the tt_news rendering engine. You can find parameters like
prevLinkTitle_stdWrap, prevLinkLabel_stdWrap or imgAltTextField. Can you tell me what that is all about? Yes? Most likely that's because you read the manual a few hours ago - well done.
On the same topic: A few months ago I was asked why extension developers should not introduce their own configuration like this:

$imageConf['file'] = $row['image'];
$imageConf['file.']['maxH'] = $this->conf['largeMaxH'];
$imageConf['file.']['maxW'] = $this->conf['largeMaxW'];

Why you should not make up your own configuration parameter names

Here is a small example, with an explanation why you shouldn't:

Imagine you just have installed two extensions with configurable image sizes. You look into the TypoScript object browser because you want the image size changed. You see following settings:

A.)

plugin.tx_myfirstextension.largeMaxH = 60
plugin.tx_myfirstextension.largeMaxW = 20

B.)

plugin.tx_secondextension.thumbnail = IMAGE
plugin.tx_secondextension.thumbnail.file.width = 60

So the question now is: which extension has a better implementation? I would say the second one because:

1) If you know the TSREF, you can start configuring the extension without even taking one look into the extension manual. You will know what the parameter thumbnail.file.width does but you will NOT know which effect the setting largeMaxW has.

2) You will be able to do wicked things, which the developer of the extension maybe event didn't think about, e.g. linking the image, without touching a single line of PHP:

plugin.tx_secondextension.thumbnail.imageLinkWrap = 1
plugin.tx_secondextension.thumbnail.imageLinkWrap.enable = 1
plugin.tx_secondextension.thumbnail.imageLinkWrap.typolink.parameter = www.somepage.com

3) Because the extension developer added the following line of code ...

plugin.tx_secondextension.thumbnail = IMAGE

... you will have full code completion support in the t3editor. Even a TSREF newbie will find it's way through.

How do I write great, configurable PHP code?

For example, to render a single image use following code:

$image = $this->getImageRowFromDb($imageUid);
$cObj = t3lib_div::makeInstance('tslib_cObj');
$cObj->start($image);
$content .= $cObj->cObjGetSingle($this->conf['singleView.']['thumbnail'], $this->conf['singleView.']['thumbnail.']);

Remember to set the correct configuration in the TypoScript setup:

plugin.tx_myextension_pi1.singleView.thumbnail = IMAGE
plugin.tx_myextension_pi1.singleView.thumbnail{
  file.import = uploads/tx_gorillary/
  file.import.field = image
  file.width = 400
}