MetaTag API¶
In order to have the possibility to set metatags in a flexible (but regulated way), a new MetaTag API is introduced.
Note
Usually, it is sufficient to set meta tags using the API of the PageRenderer
which uses the MetaTag API
internally. For all other cases, use the MetaTag API directly.
The API uses MetaTagManagers
to manage the tags for a "family" of meta tags. The Core e.g. ships an
OpenGraph MetaTagManager that is responsible for all OpenGraph tags.
In addition to the MetaTagManagers included in the Core, you can also register your own
MetaTagManager
in the \TYPO3\CMS\Core\MetaTag\MetaTagManagerRegistry
.
Using the MetaTag API¶
To use the API, first get the right MetaTagManager
for your tag from the MetaTagManagerRegistry
.
You can use that manager to add your meta tag; see the example below for the og:title
meta tag.
use TYPO3\CMS\Core\MetaTag\MetaTagManagerRegistry;
use TYPO3\CMS\Core\Utility\GeneralUtility;
$metaTagManager = GeneralUtility::makeInstance(MetaTagManagerRegistry::class)->getManagerForProperty('og:title');
$metaTagManager->addProperty('og:title', 'This is the OG title from a controller');
This code will result in a <meta property="og:title" content="This is the OG title from a controller" />
tag in frontend.
If you need to specify sub-properties, e.g. og:image:width
, you can use the following code:
use TYPO3\CMS\Core\MetaTag\MetaTagManagerRegistry;
use TYPO3\CMS\Core\Utility\GeneralUtility;
$metaTagManager = GeneralUtility::makeInstance(MetaTagManagerRegistry::class)->getManagerForProperty('og:image');
$metaTagManager->addProperty('og:image', '/path/to/image.jpg', ['width' => 400, 'height' => 400]);
You can also remove a specific property:
use TYPO3\CMS\Core\MetaTag\MetaTagManagerRegistry;
use TYPO3\CMS\Core\Utility\GeneralUtility;
$metaTagManager = GeneralUtility::makeInstance(MetaTagManagerRegistry::class)->getManagerForProperty('og:title');
$metaTagManager->removeProperty('og:title');
Or remove all previously set meta tags of a specific manager:
use TYPO3\CMS\Core\MetaTag\MetaTagManagerRegistry;
use TYPO3\CMS\Core\Utility\GeneralUtility;
$metaTagManager = GeneralUtility::makeInstance(MetaTagManagerRegistry::class)->getManagerForProperty('og:title');
$metaTagManager->removeAllProperties();
Creating Your Own MetaTagManager¶
If you need to specify the settings and rendering of a specific meta tag (for example when you want to make it possible
to have multiple occurrences of a specific tag), you can create your own MetaTagManager
.
This MetaTagManager
must implement \TYPO3\CMS\Core\MetaTag\MetaTagManagerInterface
.
To use the manager, you must register it in ext_localconf.php
:
<?php
declare(strict_types=1);
use Some\CustomExtension\MetaTag\CustomMetaTagManager;
use TYPO3\CMS\Core\MetaTag\MetaTagManagerRegistry;
use TYPO3\CMS\Core\Utility\GeneralUtility;
defined('TYPO3') or die();
$metaTagManagerRegistry = GeneralUtility::makeInstance(MetaTagManagerRegistry::class);
$metaTagManagerRegistry->registerManager(
'custom',
CustomMetaTagManager::class
);
Registering a MetaTagManager
works with the DependencyOrderingService
. So you can also specify the
priority of the manager by setting the third (before) and fourth (after) parameter of the method. If you for example
want to implement your own OpenGraphMetaTagManager
, you can use the following code:
<?php
declare(strict_types=1);
use Some\CustomExtension\MetaTag\MyOpenGraphMetaTagManager;
use TYPO3\CMS\Core\MetaTag\MetaTagManagerRegistry;
use TYPO3\CMS\Core\Utility\GeneralUtility;
defined('TYPO3') or die();
$metaTagManagerRegistry = GeneralUtility::makeInstance(MetaTagManagerRegistry::class);
$metaTagManagerRegistry->registerManager(
'myOwnOpenGraphManager',
MyOpenGraphMetaTagManager::class,
['opengraph']
);
This will result in MyOpenGraphMetaTagManager
having a higher priority and it will first check if your own
manager can handle the tag before it checks the default manager provided by the Core.
TypoScript and PHP¶
You can set your meta tags by TypoScript and PHP (for example from plugins). First the meta tags from content (plugins) will be handled. After that the meta tags defined in TypoScript will be handled.
It is possible to override earlier set meta tags by TypoScript if you explicitly say this should happen. Therefore the
meta.*.replace
option was introduced. It is a boolean flag with these values:
1
: The meta tag set by TypoScript will replace earlier set meta tags0
: (default) If the meta tag is not set before, the meta tag will be created. If it is already set, it will ignore the meta tag set by TypoScript.
page.meta {
og:site_name = TYPO3
og:site_name.attribute = property
og:site_name.replace = 1
}
When you set the property replace to 1
at the specific tag, the tag will replace tags that are set from plugins.
By using the new API it is not possible to have duplicate metatags, unless this is explicitly allowed. If you use custom
meta tags and want to have multiple occurrences of the same meta tag, you have to create your own MetaTagManager
.
See also
config.meta in the TypoScript reference