================================================================
Feature: #74365 - Add Linkservice for unified referencing syntax
================================================================

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 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

   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.