[FEATURE] Add PageTitle API
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / master / Feature-85678-AddAPIForTitleTags.rst
1 .. include:: ../../Includes.txt
3 ===================================
4 Feature: #85678 - Add PageTitle API
5 ===================================
7 See :issue:`85678`
9 Description
10 ===========
12 In order to keep setting the titles in control, a new API to set the page title has been introduced.
14 The API uses :php:`PageTitleProviders` to define the page title based on page record and the content on the page.
16 Based on the priority of the providers, the :php:`PageTitleProviderManager` will check the providers if a title
17 is given by the provider. It will start with the highest priority PageTitleProviders and will end with the lowest
18 in priority.
20 By default, the core ships three providers. The provider with the (by default) highest priority will be the
21 :php:`AltPageTitleProvider`. This provider handles the (since v9 deprecated) property
22 :php:`$GLOBALS['TSFE']->altPageTitle`. If an extension has set a value to this property, this provider will return
23 that value.
25 If you have installed the system extension SEO, the second provider will be the :php:`SeoTitlePageTitleProvider`.
26 When an editor has set a value for the SEO title in the page properties of the page, this provider will provide
27 that title to the :php:`PageTitleProviderManager`. If you have not installed the SEO system extension, this fields
28 and provider are not available.
30 The fallback provider with the lowest priority is the :php:`RecordPageTitleProvider`. When no other title is set
31 by a provider, this provider will return the title of the page.
33 Besides the providers shipped by core, you can add own providers. An integrator can define the priority of the
34 providers for his project.
36 Create your own PageTitleProvider
37 =================================
39 Extension developer may want to have an own provider for page titles. For example if you have an extension with
40 records and a detail view. The title of the page record, will not be the correct title. To make sure to display
41 the correct page title, you have to create your own :php:`PageTitleProvider`. It is quite easy to create one.
43 First of all create a PHP class in your extension that implements the :php:`PageTitleProviderInterface`. This will
44 force you to have at least the :php:`getTitle()` method in your class. Within this method you can create your
45 own logic to define the correct title.
47 Define priority of PageTitleProviders
48 =====================================
50 The priority of the providers are set by the TypoScript property :typoscript:`config.pageTitleProviders`. This
51 way an integrator is able to set the priorities for his project and can even have conditions in place.
53 By default, the core has the following setup:
55 .. code-block:: typoscript
57 config.pageTitleProviders {
58 altPageTitle {
59 provider = TYPO3\CMS\Core\PageTitle\AltPageTitleProvider
60 before = record
61 }
62 record {
63 provider = TYPO3\CMS\Core\PageTitle\RecordPageTitleProvider
64 }
65 }
67 The ordering of the providers is based on the `before` and `after` parameters. If you want a provider to be handled
68 before a specific other provider, just set that provider in the `before`, do the same with `after`.
70 If you have installed the system extension SEO, you will also get a third provider. The configuration will be:
72 .. code-block:: typoscript
74 config.pageTitleProviders {
75 altPageTitle {
76 provider = TYPO3\CMS\Core\PageTitle\AltPageTitleProvider
77 before = record
78 }
79 record {
80 provider = TYPO3\CMS\Core\PageTitle\RecordPageTitleProvider
81 }
82 seo {
83 provider = TYPO3\CMS\Seo\PageTitle\SeoTitlePageTitleProvider
84 before = record
85 after = altPageTitle
86 }
87 }
89 First the :php:`AltPageTitleProvider` will be checked, then the :php:`SeoTitlePageTitleProvider` (because it will be
90 handled before record and after altPageTitle) and if both providers didn't provide a title, the
91 :php:`RecordPageTitleProvider` will be checked.
93 You can override these settings within your own installation. You can add as many providers as you want. Be aware
94 that if a provider returns a non-empty value, all provider with a lower priority won't be checked.
96 .. index:: Frontend, ext:core, ext:seo