Soft References

“Soft References” are references to database elements, files, email addresses, URLs etc. which are found inside text fields. The <link[page_id]> tag found in bodytext fields is an example of this.

The Soft Reference parsers are used by the system to find these references and process them accordingly in import/export actions and copy operations. Also, the soft references are used by integrity checking functions.

Default soft reference parsers

The TYPO3\CMS\Core\Database\SoftReferenceIndex class contains generic parsers for the most well-known types which are default for most TYPO3 installations. This is the list of the possible keys:

substitute

softref key

substitute

Description

A full field value targeted for manual substitution (for import /export features)

notify

softref key

notify

Description

Just report if a value is found, nothing more.

images

softref key

images

Description

HTML <img> tags for RTE images / images from upload/.

ext_fileref

softref key

ext_fileref

Description

Relative file reference, prefixed EXT:[extkey]/ - for finding extension dependencies.

email

softref key

email

Description

Email highlight.

url

softref key

url

Description

URL highlights (with a scheme).

The default set up is found in typo3/sysext/core/Configuration/DefaultConfiguration.php:

'SC_OPTIONS' => array(
        'GLOBAL' => array(
                'softRefParser' => array(
                        'substitute' => 'TYPO3\\CMS\\Core\\Database\\SoftReferenceIndex',
                        'notify' => 'TYPO3\\CMS\\Core\\Database\\SoftReferenceIndex',
                        'images' => 'TYPO3\\CMS\\Core\\Database\\SoftReferenceIndex',
                        'typolink' => 'TYPO3\\CMS\\Core\\Database\\SoftReferenceIndex',
                        'typolink_tag' => 'TYPO3\\CMS\\Core\\Database\\SoftReferenceIndex',
                        'ext_fileref' => 'TYPO3\\CMS\\Core\\Database\\SoftReferenceIndex',
                        'email' => 'TYPO3\\CMS\\Core\\Database\\SoftReferenceIndex',
                        'url' => 'TYPO3\\CMS\\Core\\Database\\SoftReferenceIndex',
                ),
                ...
        ),
        ...
),

User-defined Soft Reference Parsers

Soft References can also be user-defined. It is easy to set them up by simply adding new keys in $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['GLOBAL']['softRefParser']. Use key names based on the extension you put it in, e.g. tx_myextensionkey.

The class containing the soft reference parser must have a function named findRef. Please refer to class TYPO3\CMS\Core\Database\SoftReferenceIndex for API usage and expected return values.