[TASK] Make IconRegistry::getAllRegisteredIconIdentifiers() public API
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / 8.3 / needs_github_docs / Feature-74365-LinkServiceForUnifiedReferencingSyntax.rst
1 ================================================================
2 Feature: #74365 - Add Linkservice for unified referencing syntax
3 ================================================================
4
5 Description
6 ===========
7
8 Resources within TYPO3 have been referenced using multiple, different forms of syntax
9 in the past.
10
11 TYPO3 now supports a modern and future-proof way of referencing resources using an
12 extensible and expressive syntax which is easy to understand.
13
14 In order to understand the syntax, we will guide you through using a simple page
15 link.
16
17 ``t3://page?uid=13&campaignCode=ABC123``
18
19 The syntax consists of three main parts, much like parts on an URL:
20
21 Syntax Namespace (t3://)
22    The namespace is set to ``t3://`` to ensure the ``LinkService`` should be called to
23    parse the URL.
24    This value is fixed and mandatory.
25
26 Resource handler key (page)
27    The resource handler key is a list of available handlers that TYPO3 can work
28    with. At the time of writing these handlers are:
29
30    * page
31    * file
32    * folder
33
34    More keys can be added via ``$TYPO3_CONF_VARS['SYS']['linkHandler']`` in an associative
35    array where the key is the handler key and the value is a class implementing
36    the LinkHandlerInterface.
37
38 Resource parameters(?uid=13&campaignCode=ABC123)
39    These are the specific identification parameters that are used by any handler.
40    Note that these may carry additional parameters in order to configure the
41    behavior of any handler.
42
43 Handler syntax
44 ==============
45
46 page
47 ----
48
49 The page identifier is a compound string based on several optional settings.
50
51 uid
52    **int**:
53    The **uid** of a page record.
54
55    ``t3://page?uid=13``
56 alias
57    **string**:
58    The **alias** of a page record (as an alternative to the UID).
59
60    ``t3://page?alias=myfunkyalias``
61 type
62    **int** *(optional)*:
63
64    ``t3://page?uid=13&type=3`` will reference page 13 in type 3.
65 parameters
66    **string** *(optional, prefixed with &)*:
67
68    ``t3://page?uid=1313&my=param&will=get&added=here``
69 fragment
70    **string** *(optional, prefixed with #)*:
71
72    ``t3://page?alias=myfunkyalias#c123``
73
74    ``t3://page?uid=13&type=3#c123``
75
76    ``t3://page?uid=13&type3?my=param&will=get&added=here#c123``
77
78 file
79 ----
80
81 uid
82    **int**: The UID of a file within the FAL database table ``sys_file``.
83    ``t3://file?uid=13``
84
85 identifier
86    **int**: The identifier of a file when not indexed in FAL.
87    ``t3://file?identifier=folder/myfile.jpg``
88
89 folder
90 ------
91
92 identifier
93    **string**: The identifier of a given folder.
94    ``t3://folder?identifier=fileadmin``
95
96 storage
97    **string**: The FAL storage to the given folder (optional).
98    ``t3://folder?storage=1&identifier=myfolder``
99
100
101 Examples:
102 =========
103
104 Linking to a page in RTE
105 ------------------------
106
107 The old way of linking to a page in the RTE resulted in the following code in the
108 database:
109 ``<link 13?campaignCode=ABC123 _blank class="linkMe" #c1234>Text</link>``
110
111 The new way would be the following code in the database:
112 ``<a href="t3://page?uid=13&campaignCode=ABC123#c1234" target="_blank" class="linkMe">Text</a>``
113
114 As you can see, the syntax is more in line with known markup, thus removing the
115 demand of data processing from or to the RTE component.
116
117 Referencing an image in RTE
118 ---------------------------
119
120 ``<img src="t3://file?uid=134&renderAs=png" width="200" height="200">``
121
122 In this example we illustrate a **fictional** usecase of identifier configuration (mind the "renderAs" part).
123
124 Impact
125 ======
126
127 Currently the impact is rather low, since a fallback mechanism will still be able to
128 work with the old syntax.