typolink¶

Wraps the incoming value in a link with an HTML 'a' tag.

If you do not want to have the HTML 'a' tag around the link, then you must set the property by returnLast = url or $lconf['returnLast'] = 'url'.

Attention

If typolink is used from parseFunc the $cObj->parameters array is loaded with the lowercase link parameters!

Properties ¶

extTarget ¶

extTarget¶

Data type: target / stdWrap
Default: _top

Target used for external links

fileTarget ¶

fileTarget¶

Data type: target / stdWrap

Target used for file links

language ¶

language¶

Data type: integer

Language uid for link target

Omitting the parameter language will use the current language.

Example

page.10 = TEXT
page.10.value = Link to the page with the ID 23 in the current language
page.10.typolink.parameter = 23

page.20 = TEXT
page.20.value = Link to the page with the ID 23 in the language 3
page.20.typolink.parameter = 23
page.20.typolink.language = 3

target ¶

target¶

Data type: target / stdWrap

Target used for internal links

no_cache ¶

no_cache¶

Data type: boolean / stdWrap

Adds &no_cache=1 to the link

additionalParams ¶

additionalParams¶

Data type: string / stdWrap

This is parameters that are added to the end of the URL. This must be code ready to insert after the last parameter.

Example

EXT:site_package/Configuration/TypoScript/setup.typoscript¶

page.10.typolink.additionalParams = '&print=1'
page.20.typolink.additionalParams = '&sword_list[]=word1&sword_list[]=word2'

Applications

This is very useful – for example – when linking to pages from a search result. The search words are stored in the register-key SWORD_PARAMS and can be insert directly like this:

EXT:site_package/Configuration/TypoScript/setup.typoscript¶

   page.20.typolink.additionalParams.data = register:SWORD_PARAMS

Note

additionalParams are only considered for internal links.

addQueryString ¶

addQueryString¶

Data type: boolean / string

Add the current query string to the start of the link.

Note

This option does not check for any duplicate parameters. This is not a problem: Only the last parameter of the same name will be applied.

Possible values:

0: No query parameters are added.
1: Only query parameters resolved by route enhancers are added, any other query arguments are rejected. This way, additional query arguments are never added by default. This is the recommended behaviour.

Changed in version 12.0: Before TYPO3 v12 this setting added all query parameters. To ensure the previous behaviour use untrusted.
untrusted: New in version 12.0.

Any given query parameters of the current request are added.

Example

# Pass resolved query parameters to the link
typolink.addQueryString = 1

# Pass all query parameters to the link
typolink.addQueryString = untrusted

addQueryString.exclude ¶

addQueryString.exclude¶

Data type: string

List of query arguments to exclude from the link. Typical examples are L or cHash.

Attention

This property should not be used for cached contents without a valid cHash. Otherwise the page is cached for the first set of parameters and subsequently taken from the cache no matter what parameters are given. Additionally the security risk of cache poisoning has to be considered.

Example

# Remove parameter "gclid" from query string
typolink.addQueryString.exclude = gclid

wrap ¶

wrap¶

Data type: wrap / stdWrap

Wraps the links.

ATagBeforeWrap ¶

ATagBeforeWrap¶

Data type: boolean
Default: 0

If set, the link is first wrapped with wrap and then the <A>-tag.

parameter ¶

parameter¶

Data type: string / stdWrap

This is the main data that is used for creating the link. It can be the id of a page, the URL of some external page, an email address or a reference to a file on the server. On top of this there can be additional information for specifying a target, a class and a title. Below are a few examples followed by full explanations.

Examples

Most simple. Will create a link to page 51 (if this is not default language, the correct target language will be resolved from the parameter):
EXT:site_package/Configuration/TypoScript/setup.typoscript¶
```
page.10.typolink.parameter = t3://page?uid=51
```
A full example. A link to the current page that will open in a new window. The link will have a class attribute with value "specialLink" and a title attribute reading "Very important information":
EXT:site_package/Configuration/TypoScript/setup.typoscript¶
```
page.10.typolink.parameter = t3://page?uid=current _blank specialLink "Very important information"
```
which is converted to a link like this:
Example output¶
```
<a href="?id=51" target="_blank" class="specialLink" title="Very important information">
```
An external link with a class attribute. Note the dash (-) that replaces the second value (the target). This makes it possible to define a class (third value) without having to define a target:
EXT:site_package/Configuration/TypoScript/setup.typoscript¶
```
page.10.typolink.parameter = https://example.com/ - specialLink
```
A mailto link with a title attribute (but no target and no class):
EXT:site_package/Configuration/TypoScript/setup.typoscript¶
```
page.10.typolink.parameter = mailto:info@example.org - - "Send a mail to main TYPO3 contact"
```

As you can see from the examples, each significant part of the parameter string is separated by a space. Values that can themselves contain spaces must be enclosed in double quotes. Each of these values are described in more detail below.

Link targets that are external or contain _blank will be added rel="noopener noreferrer" automatically.

Resource reference

The link

The first value is the destination of the link. It may start with:
- t3://: internal TYPO3 resource references. See Resource references for an in depth explanation on the syntax of these references.
- http(s)://: regular external links
- mailto:info@example.org: regular mailto links
It's also possible to direct the typolink to use a custom function (a "link handler") to build the link. This is described in more detail below.
Target or popup settings

Targets are normally as described above (extTarget, fileTarget, target). But it is possible to override them by explicitly defining a target in the parameter property. It's possible to use a dash (-) to skip this value when one wants to define a third or fourth value, but no target.

Instead of a target, this second value can be used to define the parameters of a JavaScript popup window into which the link will be opened (using window.open). The height and width of the window can be defined, as well as additional parameters to be passed to the JavaScript function. Also see property "Jswindow".

Examples

Open page 51 in a popup window measuring 400 by 300 pixels:
EXT:site_package/Configuration/TypoScript/setup.typoscript¶
```
typolink.parameter = 51 400x300
```
Open page 51 in a popup window measuring 400 by 300 pixels. Do not make the window resizable and show the location bar:
EXT:site_package/Configuration/TypoScript/setup.typoscript¶
```
typolink.parameter = 51 400x300:resizable=0,location=1
```
Class

The third value can be used to define a class name for the link tag. This class is inserted in the tag before any other value from the "ATagParams" property. Beware of conflicting class attributes. It's possible to use a dash (-) to skip this value when one wants to define a fourth value, but no class (see examples above).
Title

The standard way of defining the title attribute of the link would be to use the title property or even the ATagParams property. However it can also be set in this fourth value, in which case it will override the other settings. Note that the title should be wrapped in double quotes (") if it contains blanks.
Attention

When used from parseFunc, the value should not be defined explicitly, but imported like this:
EXT:site_package/Configuration/TypoScript/setup.typoscript¶
typolink.parameter.data = parameters : allParams

forceAbsoluteUrl ¶

forceAbsoluteUrl¶

Data type: boolean
Default: false

Forces links to internal pages to be absolute, thus having a proper URL scheme and domain prepended.

Additional sub-property: forceAbsoluteUrl.scheme

Note

If the option config.forceAbsoluteUrls is enabled, forceAbsoluteUrl is overridden.

forceAbsoluteUrl.scheme ¶

forceAbsoluteUrl.scheme¶

Data type: string
Values: http / https
Default: http

Defines the URL scheme to be used (https or http). http is the default value. Example:

EXT:site_package/Configuration/TypoScript/setup.typoscript¶

typolink {
   parameter = 13
   forceAbsoluteUrl = 1
   forceAbsoluteUrl.scheme = https
}

title ¶

title¶

Data type: string / stdWrap

Sets the title parameter of the A-tag.

JSwindow_params ¶

JSwindow_params¶

Data type: string

Preset values for opening the window. This example lists almost all possible attributes:

EXT:site_package/Configuration/TypoScript/setup.typoscript¶

page.10.typolink.JSwindow_params = status=1,menubar=1,scrollbars=1,resizable=1,location=1,directories=1,toolbar=1

returnLast ¶

returnLast¶

Data type: string

If set to "url", then it will return the URL of the link ($this->lastTypoLinkUrl).

If set to target, it will return the target of the link.

So, in these two cases you will not get the value wrapped but the URL or target value returned!

New in version 11.4.

If set to result, it will return the json_encoded output of the internal LinkResult object.

{
    "href": "/my-page",
    "target": null,
    "class": null,
    "title": null,
    "linkText": "My page",
    "additionalAttributes": []
}

section ¶

section¶

Data type: string / stdWrap

If this value is present, it's prepended with a "#" and placed after any internal URL to another page in TYPO3.

This is used create a link, which jumps from one page directly the section on another page.

ATagParams ¶

ATagParams¶

Data type: <A>-params / stdWrap

Additional parameters

Example

EXT:site_package/Configuration/TypoScript/setup.typoscript¶

page.10.typolink.ATagParams = class="board"

linkAccessRestrictedPages ¶

linkAccessRestrictedPages¶

Data type: boolean

If set, typolinks pointing to access restricted pages will still link to the page even though the page cannot be accessed.

userFunc ¶

userFunc¶

Data type: function name

This passes the link-data compiled by the typolink function to a user- defined function for final manipulation.

The $content variable passed to the user-function (first parameter) is an array with the keys "TYPE", "TAG", "url", "targetParams" and "aTagParams".

TYPE is an indication of link-kind: mailto, url, file, page

TAG is the full <A>-tag as generated and ready from the typolink function.

The actual tag value is constructed like this:

$contents = '<a href="' . $finalTagParts['url'] . '"'
           . $finalTagParts['targetParams']
           . $finalTagParts['aTagParams'] . '>';

The userfunction must return an <A>-tag.

Resource references ¶

TYPO3 supports a modern and future-proof way of referencing resources using an extensible and expressive syntax.

In order to understand the syntax, we will guide you through using a simple page link.

t3://page?uid=13&campaignCode=ABC123

The syntax consists of three main parts, much like parts on an URL:

Syntax Namespace (t3://)

The namespace is set to t3:// to ensure the LinkService should be called to parse the URL. This value is fixed and mandatory.

Resource handler key (page)

The resource handler key is a list of available handlers that TYPO3 can work with. At the time of writing these handlers are:

page
file
folder
url
email
record (see \TYPO3\CMS\Core\LinkHandling\RecordLinkHandler)
phone (see \TYPO3\CMS\Core\LinkHandling\TelephoneLinkHandler)

More keys can be added via $GLOBALS['TYPO3_CONF_VARS']['SYS']['linkHandler'] in an associative array where the key is the handler key and the value is a class implementing the LinkHandlerInterface.

Resource parameters (?uid=13&campaignCode=ABC123)

These are the specific identification parameters that are used by any handler. Note that these may carry additional parameters in order to configure the behavior of any handler.

Handler syntax ¶

page ¶

page¶

Data Type: string of parameters
Implementation: EXT:core/Classes/LinkHandling/PageLinkHandler.php
Example: t3://page?uid=42&type=3

The page identifier is a compound string based on several optional settings.

page.uid¶

Data Type: int / string
Example: t3://page?uid=13

The UID (field uid) of a page record, or "current" to reference the current page.

t3://page?uid=13
t3://page?uid=current

page.alias¶

Data Type: string
Example: t3://page?alias=myfunkyalias

The alias (field alias) of a page record (as an alternative to page.uid).

page.type¶

Data Type: int
Default: 0
Example: t3://page?uid=13&type=3

The type (typeNum property of the PAGE top level object). t3://page?uid=13&type=3 will reference page 13 in type 3.

page.parameters¶

Data Type: string of parameters
Example: t3://page?uid=1313&my=param&will=get&added=here

String of parameters, prefixed with &, to be added to the URL.

page.fragment¶

Data Type: string
Example: t3://page?uid=13&type=3#123

The anchor or section to jump to. Must be prefixed with #.

file ¶

file¶

Data Type: string of parameters
Implementation: EXT:core/Classes/LinkHandling/FileLinkHandler.php
Example: t3://file?uid=13

Links to a file to download.

file.uid¶

Data Type: int
Example: t3://file?uid=13

The UID of a file within the file abstraction layer (FAL) database table sys_file.

file.identifier¶

Data Type: int
Example: t3://file?identifier=fileadmin/path/myfile.jpg

The identifier of a file using combined <storage>:<path> reference or a direct reference to a file in the default storage with UID 0 as a fallback.

Examples:

t3://file?identifier=1:/path/myfile.jpg
t3://file?identifier=fileadmin/path/myfile.jpg

Attention

file cannot resolve links to files in extensions. The files must lie in a storage and be accessible via the backend module Filelist.

folder ¶

folder¶

Data Type: string of parameters
Implementation: EXT:core/Classes/LinkHandling/FolderLinkHandler.php
Example: t3://folder?storage=1&identifier=myfolder

Links to a folder.

folder.identifier¶

Data Type: string
Example: t3://folder?identifier=fileadmin

The identifier of a given folder.

folder.storage¶

Data Type: string
Example: t3://folder?storage=1&identifier=myfolder
Default: 0

The file abstraction layer (FAL) storage UID to the given folder.

email ¶

email¶

Data Type: string of parameters
Implementation: EXT:core/Classes/LinkHandling/EmailLinkHandler.php
Example: t3://email?email=mailto:user@example.org

Mail address to be used, prefixed with mailto:

url ¶

url¶

Data Type: string of parameters
Implementation: EXT:core/Classes/LinkHandling/EmailLinkHandler.php
Example: t3://url?url=example.org

URL to be used, if no scheme is used $GLOBALS['TYPO3_CONF_VARS']['SYS']['defaultScheme'] is prefixed automatically. The schemes javascript: and data: are forbidden for security reasons and result in an empty url.

Query parameters have to be URL-encoded.

Examples:

t3://url?url=example.org
t3://url?url=https://example.org
t3://url?url=https://example.org%26parameter=value

record ¶

record¶

Data Type: string of parameters
Implementation: EXT:core/Classes/LinkHandling/RecordLinkHandler.php
Example: t3://record?identifier=my_content&uid=123

Can be used to link to a record of a certain table. See also the Record link tutorial in TYPO3 Explained.

Parameters record.identifier and record.uid are mandatory for this link handler.

record.identifier¶

Data Type: string

The (individual) identifier of the link building configuration to be used.

The same identifier is used as key in the TypoScript configuration of the frontend rendering: recordLinks and the TSconfig backend link handler configuration

record.uid¶

Data Type: int

The UID of the referenced record to be linked.

phone ¶

phone¶

Data Type: string of parameters
Implementation: EXT:core/Classes/LinkHandling/TelephoneLinkHandler.php
Example: t3://phone?phone=tel:+4912345678

This link handler sets links to phone numbers using the tel: protocol.

Examples ¶

Create a link to page with uid 2:

EXT:site_package/Configuration/TypoScript/setup.typoscript¶

page.20 = TEXT
page.20.value = anchor text
page.20.typolink.parameter = 2

Output:

Example output¶

<a href="/somepage">anchor text</a>

Just display the URL:

EXT:site_package/Configuration/TypoScript/setup.typoscript¶

page.30 = TEXT
page.30.typolink.parameter = 2
page.30.typolink.returnLast = url

Output:

Example output¶

/somepage

Using link handlers ¶

See Link handler documentation in "TYPO3 Explained".