The PageTitle API of TYPO3 CMS: how to use it?

With the release of TYPO3 CMS v9LTS, a new API has been introduced by the TYPO3 SEO Iniative. The content of the title tag that is rendered in frontend, is now managed by the PageTitle API. In this blog post I will tell you how to use the PageTitle API of TYPO3 and how to extend it if the already built-in solutions won’t suit your needs.

What was the problem with the old solution?

Well, it was easily possible to adjust the title tag of your page in previous versions of TYPO3. The only problem was, that you could do it in several ways. This caused a problem with in particular extensions that want to set the content of the title tag, So, when you have a detail page of a news item for example. In most setups it is physically one page that shows content of a specific record. The extension has to set the title tag of the specific news item. When the extension didn’t use the same method as you do in your project, you could end up with two title tags. The problem was, there was not a preferred way of setting the title tag.

How can the PageTitle API of TYPO3 CMS help you?

From now on, there is a preferred way of setting the tag. You can use the PageTitle API that is included in the system extension core. 

To get the information of the title tag, the PageTitle API uses so called PageTitleProviders. Each provider gets a priority and based on that priority, the core will decide which provider will deliver the content for the page title.

PageTitleProviders shipped by core

The core with his PageTitle API ships several PageTitleProviders. Let’s start with the provider with the lowest priority. This is the RecordPageTitleProvider which will return the value of title field of the current page record. By default, this provider is the last one that is checked and is the overall fallback. 

Another PageTitleProvider shipped by core, is the AltPageTitleProvider. This provider is introduced for legacy reasons. If an extension is using $GLOBALS['TSFE']->altPageTitle, this provider will make sure the value set on this property is returned as the page title. This provider is checked just before the RecordPageTitleProvider. So if a value is set to this property, it will not check the title field of the page record.

PageTitleProviders by the SEO core extension

If you have installed the system-extension SEO, you also have a SeoTitlePageTitleProvider. With that extension installed, you have a separate SEO title field in the page properties which can differ from the normal title. This provider makes sure that if you set this SEO title in the backend, it will be checked before the AltPageTitleProvider and the RecordPageTitleProvider.

By default, core is using the following priorities:

  • If EXT:seo is installed, first check if the SEO title is filled in the backend. If so, use that value as the data for the title tag.
  • If no other provider has provided a title earlier, the AltPageTitleProvider will check if $GLOBALS['TSFE']->altPageTitle is set. If so, it will return that value.
  • When no provider did set a page title, it will fall back to the title field of the page record.

How to use the PageTitle API of TYPO3 in a project?

If you have a project with only normal pages, you don’t have to do anything. Based on the default priorities, the most common setup is set. Do you want to change the priorities? That is possible of course!

Change the priorities of the PageTitleProviders

You can set the priority of the PageTitle API by TypoScript. The config.pageTitleProviders is the part you can setup those priorities. By default, the keys record, altPageTitle and, if you have installed the EXT:seo, seo. Every key has a property provider which contains the classname that will handle the request. More important in this case are the properties before and after. With those properties you can set if this provider is handled before or after the specified providers.

A little example. If you want to have the RecordPageTitleProvider checked before the AltPageTitleProvider, you can use the following TypoScript:

		config.pageTitleProviders {
    altPageTitle {
        before >
    }
    record {
        before = altPageTitle
    }
}

	

As you can see on line 3, we unset the current value of the before attribute of the altPageTitleProvider. This value is set by default, so we have to unset it. On line 6 you see the before property of the RecordPageTitleProvider getting the value altPageTitle.

This example makes sure that the RecordPageTitleProvider is checked before the AltPageTitleProvider.

Do I need any further configuration?

By default, the core ships all PageTitleProviders you need for core features. If you use extensions that may change the content based on parameters like with 1 physical detail page showing content of a given record, you might need a new PageTitleProvider. I encourage extension builders to add those PageTitleProviders within their extension, so an integrator just have to set the right priorities.

What to do when you need an own PageTitleProvider?

As said, I encourage all extension developers that have a plugin that have to define the title of the page, to add a separate PageTitleProvider. I will tell you how to do this. This example can be used by extension developers, but also within your project if the extension doesn’t provide a PageTitleProvider itself.

Create your own class

First of all, you need to create a new class in your extension. In my example, I create a class with the name MyOwnPageTitleProvider.php in the folder Classes/PageTitle. Your class have to implement the PageTitleProviderInterace. The easiest way is to extend your class from the AbstractPageTitleProvider. So let’s start with that. We have a file like this:

		<?php
declare(strict_types = 1);

namespace Company\Extension\PageTitle;

use TYPO3\CMS\Core\PageTitle\AbstractPageTitleProvider;

class MyOwnPageTitleProvider extends AbstractPageTitleProvider
{
    public function __construct()
    {
        $this->title = ‘Example page title’;
    }
}
	

Register your provider

The next thing to do is to register this PageTitleProvider. This needs to be done with TypoScript just like we change the order of the PageTitleProviders. In your ext_localconf.php you can add the following code to add the TypoScript config.

		\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTypoScriptSetup(trim('
    config.pageTitleProviders {
        own {
            provider = Company\Extension\PageTitle\MyOwnPageTitleProvider
            before = record
            after = altPageTitle
        }
    }
'));

	

With this snippet, you will add your own PageTitleProvider and you tell the core to handle this provider after the altPageTitle is checked. With the before attribute, it makes sure the provider is checked before the record of the page.

Now just visit a page in your installation with no altPageTitle set. You will see that the title of your page contains the string ‘Example page title’. Depending on your configuration you can also see a prefix and a suffix.

Now the TitleProvider is working, we want to make it possible a Controller can set the page title. So we remove the constructor method and add a new setTitle method. Our class now looks like:

		<?php
declare(strict_types = 1);

namespace Company\Extension\PageTitle;

use TYPO3\CMS\Core\PageTitle\AbstractPageTitleProvider;

class MyOwnPageTitleProvider extends AbstractPageTitleProvider
{
    /**
     * @param string $title
     */
    public function setTitle(string $title)
    {
        $this->title = $title;
    }
}
	

In your Controller action, you can now add the following code:

		$titleProvider = GeneralUtility::makeInstance(MyOwnPageTitleProvider::class);
$titleProvider->setTitle(‘Title from controller action’);

	

Now, check a page which contains a plugin with the controller action you just altered and check the page title. You will see, it now includes the ‘Title from controller action’. 

It is now up to you what you want to do with it. As long as the title property of the provider contains the right title and you set the right priority, you can add your own logic to set the correct title. 

Why not one PageTitleProvider that can be used by all extensions?

One of the main problems why people didn’t use the page title function from core in version 8 or earlier was because you couldn’t control the priorities of extensions. So let’s say you had two extension on 1 page that both want to alter the page title, you had to guess which one was taking control.

To handle this problem, we introduced the priority configuration in version 9. As you have seen, you can set the priorities of each PageTitleProvider. If all extensions are using the same PageTitleProvider, that benefit is gone directly. So please extension developers, create your own PageTitleProvider and make it easier for integrators to set the priorities they need!

Need any help with the PageTitle API of TYPO3?

If you have any problems or questions regarding this new PageTitle API of TYPO3, please ask your question in the #cig-seo channel on Slack. Together with lots of other people, I will try to help you there.

Get in touch!

Do you have a question? Do you want to work together? Just send me a message and I will get in touch as soon as possible.

Send a message