Feature: #74365 - Add Linkservice for unified referencing syntax¶
See forge#74365
Description¶
Resources within TYPO3 have been referenced using multiple, different forms of syntax in the past.
TYPO3 now supports a modern and future-proof way of referencing resources using an extensible and expressive syntax which is easy to understand.
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 theLinkService
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
More keys can be added via
$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¶
The page identifier is a compound string based on several optional settings.
- uid
-
int: The uid of a page record.
t3://page?uid=13
- alias
-
string: The alias of a page record (as an alternative to the UID).
t3://page?alias=myfunkyalias
- type
-
int (optional):
t3://page?uid=13&type=3
will reference page 13 in type 3. - parameters
-
string (optional, prefixed with &):
t3://page?uid=1313&my=param&will=get&added=here
- fragment
-
string (optional, prefixed with #):
t3://page?alias=myfunkyalias#c123
t3://page?uid=13&type=3#c123
t3://page?uid=13&type3?my=param&will=get&added=here#c123
file¶
- uid
- int: The UID of a file within the FAL database table
sys_file
.t3://file?uid=13
- identifier
- int: The identifier of a file when not indexed in FAL.
t3://file?identifier=folder/myfile.jpg
folder¶
- identifier
- string: The identifier of a given folder.
t3://folder?identifier=fileadmin
- storage
- string: The FAL storage to the given folder (optional).
t3://folder?storage=1&identifier=myfolder
Examples:¶
Linking to a page in RTE¶
The old way of linking to a page in the RTE resulted in the following code in the
database:
<link 13?campaignCode=ABC123 _blank class="linkMe" #c1234>Text</link>
The new way would be the following code in the database:
<a href="t3://page?uid=13&campaignCode=ABC123#c1234" target="_blank" class="linkMe">Text</a>
As you can see, the syntax is more in line with known markup, thus removing the demand of data processing from or to the RTE component.
Referencing an image in RTE¶
<img src="t3://file?uid=134&renderAs=png" width="200" height="200">
In this example we illustrate a fictional usecase of identifier configuration (mind the "renderAs" part).
Impact¶
Currently the impact is rather low, since a fallback mechanism will still be able to work with the old syntax.