Soft references¶
“Soft References” are references to database elements, files, email addresses, URLs etc. which are found inside text fields.
For example, tt_content.bodytext
can contain soft references to pages,
to content elements, to files etc. The page reference can look
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
).
Which soft reference parsers will be used can be defined in the TCA field softref which is available for TCA column types text and input.
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.
typolink¶
softref key
typolink
Description
References to page id, record, 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
As typolink, 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/DefaultConfiguration.php
:
'SC_OPTIONS' => [
'GLOBAL' => [
'softRefParser' => [
'substitute' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
'notify' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
'typolink' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
'typolink_tag' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
'ext_fileref' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
'email' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
'url' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
],
],
// ...
],
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="http://example.org/some-cool-feature">this cool feature</a></p>
<p>Contact: email@example.org</p>
The parsers will return an array containing information about the references contained in the string:
[
'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>
',
'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="http://example.org/some-cool-feature">',
'subst' => [
'type' => 'string',
'tokenID' => '78910',
'tokenValue' => 'http://example.org/some-cool-feature',
]
],
[
'matchString' => 'email@example.org',
'subst' => [
'type' => 'string',
'tokenID' => '123456',
'tokenValue' => 'test@example.com',
]
]
],
],
The result array¶
In most cases the result array contains two keys: content
and elements
.
Key content
¶
This part contains the input content. Links to be substituted have been replaced by soft reference tokens.
For example: :html:’ <p>Contact: {softref:123456}</p>’
Tokens are strings like {softref:123456} which are placeholders for a values extracted by a soft reference parser.
For each token there in an entry in the elements
key which has a
subst
key defining the tokenID
and the tokenValue
. See below.
Key elements
¶
This part is an array of arrays, each with these keys:
matchString
: The value of the match. This is only for informationalpurposes 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 an md5 hash of a string defining uniquely the position of the element.
tokenValue
: The value that the token substitutes in the text.- Basically, 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 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.
Using the soft reference parser¶
To use the soft reference parser in your own extensions, use
\TYPO3\CMS\Backend\Utility\BackendUtility::softRefParserObj
to get
the parser for a specific soft reference type. For an example, take a look at
\TYPO3\CMS\Linkvalidator\LinkAnalyzer::analyzeRecord
.