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 return
or
$lconf
.
Attention
If typolink is used from parse
the $c
array is
loaded with the lowercase link parameters!
Properties
extTarget
extTarget
-
- Type
- string / stdWrap
- Default
- "" (no target set)
Target used for external links
fileTarget
fileTarget
-
- Type
- string / stdWrap
Target used for file links
language
language
-
- Type
- integer
Language uid for link target
Omitting the parameter
language
will use the current language.Examplepage.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
Copied!
target
target
-
- Type
- string / stdWrap
Target used for internal links
no_cache
no_cache
additionalParams
additionalParams
-
This is parameters that are added to the end of the URL. This must be code ready to insert after the last parameter.
Examplepage.10.typolink.additionalParams = '&print=1' page.20.typolink.additionalParams = '&sword_list[]=word1&sword_list[]=word2'
Copied!ApplicationsThis 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:
page.20.typolink.additionalParams.data = register:SWORD_PARAMS
Copied!Note
additionalParams are only considered for internal links.
addQueryString
addQueryString
-
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.
untrusted
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
Copied!
addQueryString.exclude
addQueryString.exclude
-
- Type
- string
List of query arguments to exclude from the link. Typical examples are
L
orc
.Hash 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
Copied!
wrap
wrap
ATagBeforeWrap
ATagBeforeWrap
-
- Type
- boolean
- Default
- 0
If set, the link is first wrapped with
wrap
and then the <A>-tag.
parameter
parameter
-
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):
page.10.typolink.parameter = t3://page?uid=51
Copied! -
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":
page.10.typolink.parameter = t3://page?uid=current _blank specialLink "Very important information"
Copied!which is converted to a link like this:
<a href="?id=51" target="_blank" class="specialLink" title="Very important information">
Copied! -
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:
page.10.typolink.parameter = https://example.com/ - specialLink
Copied! -
A mailto link with a title attribute (but no target and no class):
page.10.typolink.parameter = mailto:info@example.org - - "Send a mail to main TYPO3 contact"
Copied!
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 addedrel="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
: regular external links(s):// mailto:
: regular mailto linksinfo@example. org
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".
ExamplesOpen page 51 in a popup window measuring 400 by 300 pixels:
typolink.parameter = 51 400x300
Copied!Open page 51 in a popup window measuring 400 by 300 pixels. Do not make the window resizable and show the location bar:
typolink.parameter = 51 400x300:resizable=0,location=1
Copied! -
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 theATag
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.Params Attention
When used from
parse
, the value should not be defined explicitly, but imported like this:Func typolink.parameter.data = parameters : allParams
Copied!
-
forceAbsoluteUrl
forceAbsoluteUrl
-
- 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.scheme is overridden.
forceAbsoluteUrl.scheme
forceAbsoluteUrl.scheme
-
- Type
- string
- Values
-
http
/https
- Default
-
http
Defines the URL scheme to be used (https or http). http is the default value. Example:
typolink { parameter = 13 forceAbsoluteUrl = 1 forceAbsoluteUrl.scheme = https }
Copied!
title
title
JSwindow_params
JSwindow_params
-
- Type
- string
Preset values for opening the window. This example lists almost all possible attributes:
page.10.typolink.JSwindow_params = status=1,menubar=1,scrollbars=1,resizable=1,location=1,directories=1,toolbar=1
Copied!
returnLast
returnLast
-
- Type
- string
If set to "url", then it will return the URL of the link (
$this->last
).Typo Link Url 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!
If set to
result
, it will return the json_encoded output of the internalLinkResult
object.{ "href": "/my-page", "target": null, "class": null, "title": null, "linkText": "My page", "additionalAttributes": [] }
Copied!
section
section
ATagParams
ATagParams
-
- Type
- <A>-params / stdWrap
Additional parameters
Examplepage.10.typolink.ATagParams = class="board"
Copied!
linkAccessRestrictedPages
linkAccessRestrictedPages
-
- 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
-
- Type
- function name
All of the
typolink
TypoScript configuration will be parsed and evaluated by the TYPO3 Core'sLink
method, and then passed on to the definedFactory->create () user
for further manipulation. TheFunc user
needs to return an object implementing theFunc Link
. The currently calculated typolink is passed as an argument to theResult Interface user
as an object of the same type. This allows to return either an enriched link, or a completely new one.Func The detailed execution steps are:
First, the
typolink
will be created as configured by the specified TypoScript. This will result in an object of TypeLink
. This immutable object receives all of the TypoScriptResult Interface typolink
configuration as properties, and makes them available via corresponding getters. Then your customuser
is executed and receives the following arguments (delivered viaFunc $content
):Object Renderer->call User Function () $content
-
This contains the object implementing
Link
. Inside yourResult Interface user
you can call for example:Func () $content->get
to get the URL of a link,Url () $content->get
to get the text of your link (everything with theLink Text () <a>...</
tag),a> $content->get
for the array with all typolink configuration options,Link Configuration () $content->get
returns current anchor link attributes (likeAttributes () typolink.
),additional Arguments $content->get
returns the kind of link that is operated on, likeType () Link
(specific pages in your TYPO3 setup) orService:: TYPE_ PAGE Link
for links to external pages.Service:: TYPE_ URL
See the PHP definition of
Link
for the full list of getters.Result Interface Since
Link
is an immutable object, you must use the methodsResult Interface with
and/orLink Text () with
to create a new object variant, which at the end of yourAttributes () user
must be returned (see below for examples). In case you do not make any changes to the object, the function must return the original object.Func $conf
- Contains an array of the TypoScript configuration of your
user
parameters.Func $request
- Contains the PSR-7 request object that allows you to operate on your current frontend
environment and retrieve things like Site Settings, current Language, current URL,
related
Content
(Object Renderer $c
) and other aspects, see TYPO3 request object.Obj
See Examples for typolink.userFunc for more details.
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://
The syntax consists of three main parts, much like parts on an URL:
- Syntax Namespace (
t3://
) - The namespace is set to
t3://
to ensure theLink
should be called to parse the URL. This value is fixed and mandatory.Service - 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
- record (see
\TYPO3\
)CMS\ Core\ Link Handling\ Record Link Handler - phone (see
\TYPO3\
)CMS\ Core\ Link Handling\ Telephone Link Handler
More keys can be added via
$GLOBALS
in an associative array where the key is the handler key and the value is a class implementing the LinkHandlerInterface.['TYPO3_ CONF_ VARS'] ['SYS'] ['link Handler'] - Resource parameters (
?uid=13&campaign
)Code=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
-
- Type
- string of parameters
- Implementation
- EXT:core/Classes/LinkHandling/PageLinkHandler.php (GitHub)
- Example
t3://
page?uid=42&type=3
The page identifier is a compound string based on several optional settings.
page.uid
page.uid
page.alias
page.alias
page.type
page.type
-
- Type
- integer
- Default
- 0
- Example
t3://
page?uid=13&type=3
The type (Properties property of the PAGE top level object).
t3://
will reference page 13 in type 3.page?uid=13&type=3
page.parameters
page.parameters
-
- 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
page.fragment
-
- Type
- string
- Example
t3://
page?uid=13&type=3#123
The anchor or section to jump to. Must be prefixed with
#
.
file
file
-
- Type
- string of parameters
- Implementation
- EXT:core/Classes/LinkHandling/FileLinkHandler.php (GitHub)
- Example
t3://
file?uid=13
Links to a file to download.
file.uid
file.uid
-
- Type
- integer
- Example
t3://
file?uid=13
The UID of a file within the file abstraction layer (FAL) database table
sys_
.file
file.identifier
file.identifier
-
- Type
- integer
- 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 UID0
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 File > Filelist.
folder
folder
-
- Type
- string of parameters
- Implementation
- EXT:core/Classes/LinkHandling/FolderLinkHandler.php (GitHub)
- Example
t3://
folder?storage=1&identifier=myfolder
Links to a folder.
folder.identifier
folder.identifier
-
- Type
- string
- Example
t3://
folder?identifier=fileadmin
The identifier of a given folder.
folder.storage
folder.storage
-
- Type
- string
- Example
t3://
folder?storage=1&identifier=myfolder - Default
- 0
The file abstraction layer (FAL) storage UID to the given folder.
-
- Type
- string of parameters
- Implementation
- EXT:core/Classes/LinkHandling/EmailLinkHandler.php (GitHub)
- Example
t3://
email?email=mailto: user@example. org
Mail address to be used, prefixed with
mailto:
url
url
-
- Type
- string of parameters
- Implementation
- EXT:core/Classes/LinkHandling/EmailLinkHandler.php (GitHub)
- Example
t3://
url?url=example. org
URL to be used, if no scheme is used
$GLOBALS
is prefixed automatically. The schemes['TYPO3_ CONF_ VARS'] ['SYS'] ['default Scheme'] javascript:
anddata:
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
-
- Type
- string of parameters
- Implementation
- EXT:core/Classes/LinkHandling/RecordLinkHandler.php (GitHub)
- 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
record.identifier
-
- 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: Properties of 'config' and the TSconfig backend link handler configuration
record.uid
record.uid
-
- Type
- integer
The UID of the referenced record to be linked.
phone
phone
-
- Type
- string of parameters
- Implementation
- EXT:core/Classes/LinkHandling/TelephoneLinkHandler.php (GitHub)
- 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:
page.20 = TEXT
page.20.value = anchor text
page.20.typolink.parameter = 2
Output:
<a href="/somepage">anchor text</a>
Just display the URL:
page.30 = TEXT
page.30.typolink.parameter = 2
page.30.typolink.returnLast = url
Output:
/somepage