Submitting your vote...
Recently I often see that TYPO3 plugins do not create links properly. It seems that authors simply do not know how to make links properly in TYPO3. As a result links are not RealURL-compatible or cache issues happen.
This article shows how to use typoLink in Frontend plugin.
To create a link from plugin you can either use one of pi_* functions available from tslib_pibase class or use tslib_cObj::typoLink function. The first is good if you need to keep and/or replace plugin variables. The second one is the most universal and I want to focus on it in this article.
The first thing you should have under hand before you start using typoLink is... TSRef. Yes, TypoScript reference. It contains full description of typoLink configuration.
When using typoLink, there are several important properties, to which you need pay special attention:
- useCacheHash
If URL contains any parameters that affect page content and that content iscached (=not produced by USER_INT plugin), then URL must include cHash. cHash ensures that page cache takes URL parameters into account. If you forget cHash for cached content, you will get the same content every time with different parameters. - additionalParams
Firsts, it must start with & character. If not, it will be ignored. Secodnly, it is sdWrap, which gives you great flexibility for adding parameters. - no_cache
Generally this must not be set because it makes performance of the web server zero.
typoLink is usually called in the following way:
$link = $this->cObj->typoLink('linkedText', $conf);
This will create a complete link: text linked to whatever specified in configuration. It is possible to get only link by using typoLink_URL instead. There is also configuration option that forces typoLink to return URL.
Full code example for typoLink with explanation:
$conf = array(
// Link to current page
'parameter' => $GLOBALS['TSFE']->id,
// Set additional parameters
'additionaParams' => '&tx_ttnews[tt_news]=' . $ttNewsItemUid,
// We must add cHash because we use parameters
'useCashHash' => true,
// We want link only
'returnLast' => 'url',
);
$url = $this->cObj->typoLink('', $conf);
As you see, it is very easy to use typoLink. As additional bonus you get simulateStatic/RealURL/CoolURI automatically.
But, it says nothing about good practices for customizing links.
f.e. if I need to insert class="link-to-single" to every link that points to single item (news, gallery, faq ...).
I have some solutions for this problem
1) Use TS configuration for plugin. I use code like this
plugin.tx_myplugin {
linkToSingle {
parameter = single
ATagParams = class="link-to-single"
}
}
And than in my PHP code:
singleTypolinkConf = $this->conf['linkToSingle.'];
singleTypolinkConf['additionalParams'] .= '&singleUid='.$singleUid;
$link = explode('|',$this->cObj->typoLink('|', $singleTypolinkConf)); //Use this as wrap subpart
But I do not think this method is good enough.
I can't predict what will happend if someone will use returnLast=url in TS setup (for customization).
Can you me how to handle with problems of customization of links.
Thanks.
great article that sums up nicely the essentials of link building in TYPO3.
Just to make sure, people won't fail in generating links when using the above code:
There is a misspelling in the PHP typolink code. The parameters name is "useCacheHash", not "useCashHash"... or do you also take credit cards? ;))
Big ups from Germany,
Jochen
additionaParams -> should be -> additionalParams
Thanks for your blog!
Stefan.