Soft references¶
Soft References are references to database elements, files, email addresses, URLs etc. which are found inside of text fields.
For example, tt_content.bodytext
can contain soft references to pages,
content elements and files. The page reference looks like this:
<a href="t3://page?uid=1">link to page 1</a>
In contrast to this, the field pages.shortcut
contains the page id of a
shortcut. This is a reference, but not a soft reference.
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. For example, when you try to delete a page, TYPO3 will warn you if there are incoming page links to this page.
All references, soft and ordinary ones, are written to the reference index
(table sys_refindex
).
You can define which soft reference parsers to use in the TCA field softref which is available for TCA column types text and input.
Default soft reference parsers¶
The TYPO3\CMS\Core\DataHandling\SoftReference
namespace contains generic
parsers for the most well-known types, which are the default for most TYPO3
installations. This is the list of the pre-registered 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.
typolink¶
softref key
typolink
Description
References to page id, record or file in typolink format. The typolink
soft reference parser can take an additional argument, which can be
linklist
(typolink['linklist']
). In this case the links will be
separated by commas.
typolink_tag¶
softref key
typolink_tag
Description
Same as typolink, but with an <a>
tag encapsulating it.
ext_fileref¶
softref key
ext_fileref
Description
Relative file reference, prefixed EXT:[extkey]/
- for finding
extension dependencies.
email¶
softref key
Description
Email highlight.
url¶
softref key
url
Description
URL highlights (with a scheme).
The default set up is found in
typo3/sysext/core/Configuration/Services.yaml
:
# Soft Reference Parsers
TYPO3\CMS\Core\DataHandling\SoftReference\SubstituteSoftReferenceParser:
tags:
- name: softreference.parser
parserKey: substitute
TYPO3\CMS\Core\DataHandling\SoftReference\NotifySoftReferenceParser:
tags:
- name: softreference.parser
parserKey: notify
TYPO3\CMS\Core\DataHandling\SoftReference\TypolinkSoftReferenceParser:
tags:
- name: softreference.parser
parserKey: typolink
TYPO3\CMS\Core\DataHandling\SoftReference\TypolinkTagSoftReferenceParser:
tags:
- name: softreference.parser
parserKey: typolink_tag
TYPO3\CMS\Core\DataHandling\SoftReference\ExtensionPathSoftReferenceParser:
tags:
- name: softreference.parser
parserKey: ext_fileref
TYPO3\CMS\Core\DataHandling\SoftReference\EmailSoftReferenceParser:
tags:
- name: softreference.parser
parserKey: email
TYPO3\CMS\Core\DataHandling\SoftReference\UrlSoftReferenceParser:
tags:
- name: softreference.parser
parserKey: url
Examples¶
For the tt_content.bodytext
field of type text from the example
above, the configuration looks like this:
$GLOBALS['TCA']['tt_content']['columns']['bodytext'] =>
// ...
'config' => [
'type' => 'text',
'softref' => 'typolink_tag,email[subst],url',
// ...
],
// ...
];
This means, the parsers for the softref types typolink_tag
, email
and
url
will all be applied. The email soft reference parser gets the additional
parameter subst
.
The content could look like this:
<p><a href="t3://page?uid=96">Congratulations</a></p>
<p>To read more about <a href="https://example.org/some-cool-feature">this cool feature</a></p>
<p>Contact: email@example.org</p>
The parsers will return an instance of
TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserResult
containing information about the references contained in the string.
This object has two properties: $content
and $elements
.
Property $content
¶
<p><a href="{softref:424242}">Congratulations</a></p>
<p>To read more about <a href="{softref:78910}">this cool feature</a></p>
<p>Contact: {softref:123456}</p>
This property contains the input content. Links to be substituted have been replaced by soft reference tokens.
For example: <p>Contact: {softref:123456}</p>
Tokens are strings like {softref:123456}
which are placeholders for values
extracted by a soft reference parser.
For each token there is an entry in $elements
which has a
subst
key defining the tokenID
and the tokenValue
. See
below.
Property $elements
¶
[
[
'matchString' => '<a href="t3://page?uid=96">',
'error' => 'There is a glitch in the universe, page 42 not found.',
'subst' => [
'type' => 'db',
'tokenID' => '424242',
'tokenValue' => 't3://page?uid=96',
'recordRef' => 'pages:96',
]
],
[
'matchString' => '<a href="https://example.org/some-cool-feature">',
'subst' => [
'type' => 'string',
'tokenID' => '78910',
'tokenValue' => 'https://example.org/some-cool-feature',
]
],
[
'matchString' => 'email@example.org',
'subst' => [
'type' => 'string',
'tokenID' => '123456',
'tokenValue' => 'test@example.com',
]
]
]
This property is an array of arrays, each with these keys:
matchString
: The value of the match. This is only for informational purposes to show, what was found.error
: An error message can be set here, like "file not found" etc.subst
: exists on a successful match and defines the token fromcontent
tokenID
: The tokenID string corresponding to the token in output content,{softref:[tokenID]}
. This is typically a md5 hash of a string uniquely defining the position of the element.tokenValue
: The value that the token substitutes in the text. If this value is inserted instead of the token, the content should match what was inputted originally.type
: the type of substitution.file
is a relative file reference,db
is a database record reference,string
is a manually modified string content (email, external url, phone number)relFileName
: (forfile
type): Relative filename.recordRef
: (fordb
type): Reference to DB record on the form<table>:<uid>
.
User-defined soft reference parsers¶
Soft Reference Parsers can also be user-defined. It is easy to set them up by registering them in your Services.(yaml|php) file. This will load them via dependency injection:
MyVendor\Extension\SoftReference\YourSoftReferenceParser:
tags:
- name: softreference.parser
parserKey: your_key
Don't forget to clear the hard caches in the admin tool after modifying DI configuration.
The soft reference parser class registered there must implement
TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserInterface
.
This interface describes the parse
method, which takes 5 parameters in
total as arguments: $table
, $field
, $uid
, $content
and an optional argument $structurePath
. The return type must be an
instance of
TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserResult
.
This model possesses the properties $content
and $elements
and has
appropriate getter methods for them. The structure of these properties has been
already described above. This result object should be created by its own factory
method SoftReferenceParserResult::create
, which expects both
above-mentioned arguments to be provided. If the result is empty,
SoftReferenceParserResult::createWithoutMatches
should be used instead.
If $elements
is an empty array, this method will also be used internally.
Using the soft reference parser¶
To get an instance of a soft reference parser, it is recommended to use the
TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserFactory
class. This factory class already holds all registered instances of the parsers.
They can be retrieved with the getSoftReferenceParser
method. You
have to provide the desired key as the first and only argument.
$softReferenceParserFactory = GeneralUtility::makeInstance(SoftReferenceParserFactory::class);
$softReferenceParser = $softReferenceParserFactory->getSoftReferenceParser('your_key');