Delivering Extbase output with a typeNum page type
A typeNum page type delivers another representation of a page: the same page,
in the same site and language, with the same access checks and the same page
cache, rendered by a dedicated TypoScript
PAGE
object instead of
the page template. It is the most widespread way to get JSON, XML or an HTML
fragment out of an Extbase plugin, and a good tool to have at hand.
What the plugin sees in a page type depends on what the
PAGE
object renders. When it renders the plugin's content element, the plugin
works with the settings and the storage folder an editor chose, exactly as on
the regular page. When it renders the plugin on its own, the plugin works with
its TypoScript configuration.
This page builds an RSS feed for conference lists that editors filter themselves, and then shows the variants for output that does not belong to a content element on the page.
On this page
What a typeNum page type is in TYPO3
Every TYPO3 frontend page is rendered by a TypoScript
PAGE object. The
one that renders the regular HTML page has
typeNum
0. Further
PAGE
objects with other numbers can be defined next
to it. The type query parameter selects one of them: ?type=1762214400
renders the same page, in the same site and language, with the other
PAGE
object.
The core uses this itself. The
XML sitemap of
EXT: is a
PAGE
object with
type.
Note
A typeNum page type is unrelated to the
page types an
editor selects for a page record, such as "Standard", "Folder" or
"Shortcut". Those are stored in the doktype field of the page. Both are
called "page type" in many places, which makes searching for either one
harder than it should be.
Rendering an Extbase plugin in a typeNum page type
The example site has several conference lists: all conferences, conferences
in Europe, conferences this year. Each one is a page with a conference list
plugin, and an editor chose the storage folder and the filter in the plugin's
content element. Every list page also offers its selection as an
RSS feed at a URL ending in
feed..
The feed is a second representation of the list page, so a typeNum page type
fits. It renders the conference list content element of the current page and
ignores everything else an editor placed there. Four pieces work together: the
plugins, a
PAGE
object, a template in the XML format, and a
route that maps the URL suffix to the page type.
The list plugin is configured and
registered as a content element
as usual. The feed plugin is only configured: editors never place it, the
PAGE
object renders it, so it needs no
register call:
<?php
use MyVendor\MyExtension\Controller\ConferenceController;
use MyVendor\MyExtension\Controller\ConferenceFeedController;
use TYPO3\CMS\Extbase\Utility\ExtensionUtility;
defined('TYPO3') or die();
ExtensionUtility::configurePlugin(
'MyExtension',
'ConferenceList',
[ConferenceController::class => 'list'],
);
ExtensionUtility::configurePlugin(
'MyExtension',
'ConferenceFeed',
[ConferenceFeedController::class => 'feed'],
);
The
PAGE
object selects the list content element with a
CONTENT object and
renders the feed plugin for it with
EXTBASEPLUGIN:
conferenceFeed = PAGE
conferenceFeed {
typeNum = 1762214400
config {
disableAllHeaderCode = 1
admPanel = 0
}
10 = CONTENT
10 {
table = tt_content
select {
where = {#CType} = 'myextension_conferencelist'
orderBy = sorting
max = 1
}
renderObj = EXTBASEPLUGIN
renderObj {
extensionName = MyExtension
pluginName = ConferenceFeed
}
}
}
plugin.tx_myextension_conferencefeed {
settings {
title = Conferences
description = Conferences of the community
}
}
CONTENTsearches the current page, in the current language, as the page template does. Thewhereclause restricts it to content elements of the list plugin, so text, images and other plugins on the page do not end up in the feed. An RSS document has one channel, somax = 1takes only the first list.- The
renderruns once for the selected content element, with the content element as its record. The feed plugin therefore reads the storage folder and the FlexForm settings of the list, see What the PAGE object renders decides the configuration.Obj - The
renderisObj EXTBASEPLUGINand nottt_. The content element rendering wraps the plugin output in the HTML of the content element layout, which has no place in an XML document.content. myextension_ conferencelist - disableAllHeaderCode
removes everything TYPO3 adds around the content: the HTML document
structure, the
<head>and the<body>. Only the plugin output is left. - admPanel keeps the Admin Panel out of the feed for logged-in backend users.
- The TypoScript settings of the feed plugin provide the defaults for the channel. The FlexForm settings of the list element are merged on top of them.
The controller applies the same filter the list uses. It sets the request
format to xml before the view is created, and returns the rendered view with
the content type of an RSS feed:
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Controller;
use MyVendor\MyExtension\Domain\Repository\ConferenceRepository;
use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;
class ConferenceFeedController extends ActionController
{
public function __construct(
protected readonly ConferenceRepository $conferenceRepository,
) {}
protected function initializeFeedAction(): void
{
$this->request = $this->request->withFormat('xml');
}
public function feedAction(): ResponseInterface
{
$conferences = $this->conferenceRepository->findFiltered(
(string)($this->settings['region'] ?? ''),
(bool)($this->settings['currentYearOnly'] ?? false),
);
$this->view->assign('conferences', $conferences);
return $this->responseFactory->createResponse()
->withHeader('Content-Type', 'application/rss+xml; charset=utf-8')
->withBody($this->streamFactory->createStream($this->view->render()));
}
}
find stands for the repository method the list action calls
with the same settings, see
Queries in Extbase. The storage folder
needs no code: Extbase takes it from the list element and restricts every
query to it.
The format decides which template file Extbase looks for. With format xml,
the action
feed renders
Templates/ instead of
Feed., see
Fluid template file resolution. Setting the
format in
initialize ties it to this one action. The
TypoScript option format
would change the default for every action of the plugin.
The template is plain XML with Fluid syntax. Fluid escapes every variable it
outputs, so titles and descriptions containing & or < stay valid XML:
<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0">
<channel>
<title>{settings.title}</title>
<link><f:uri.page absolute="true" /></link>
<description>{settings.description}</description>
<f:for each="{conferences}" as="conference">
<item>
<title>{conference.title}</title>
<description>{conference.description}</description>
<guid isPermaLink="false">conference-{conference.uid}</guid>
</item>
</f:for>
</channel>
</rss>
The
Content- header of the action's response becomes the
content type of the whole page. TYPO3 stores it with the page in the page
cache, so cached deliveries keep it. A
PAGE
object that renders
an Extbase plugin therefore does not need
config.additionalHeaders
to set the content type. The sitemap of EXT: needs it, because its
renderer is not an Extbase plugin.
Finally, the
PageType decorator
maps the page type to a URL suffix, so the feed of the page
https:// is available at
https:// instead of
https://:
If the site already defines a PageType decorator, add the entry to its
map
rather than defining a second one.
The list template links to the feed of its own page by passing the page type to a page link:
<f:link.page pageType="1762214400">Subscribe to this list as a feed</f:link.page>
A new list page needs nothing but the list content element. The feed follows
the editor's filter without any further configuration, and on a page without
a conference list the
CONTENT
object finds nothing to render.
What the PAGE object renders decides the configuration
A plugin takes part of its configuration from the record its content object
is rendered for: the
FlexForm settings an editor filled in,
and the Record Storage Page that sets the
storagePid. The page type itself does
not change this. Only the
PAGE
object's content does:
- On the regular page, the page template renders the content elements, and
every plugin is rendered for its own content element. The same is true in
a page type that renders content elements with
CONTENTorRECORDS. EXTBASEPLUGINplaced directly in thePAGEobject is rendered for the page record, which carries no FlexForm and no storage page. The plugin then works with its TypoScript settings, and its queries use the storagePid from TypoScript, or page0if none is set.
Which one fits depends on where the configuration lives. The following sections show the two variants that do not take it from a content element on the current page.
Rendering the plugin without a content element
A page type that renders
EXTBASEPLUGIN
directly suits output
of one plugin that is configured in TypoScript, for example the next page of
a paginated list that a script loads without reloading the page:
conferenceListUpdate = PAGE
conferenceListUpdate {
typeNum = 1762214401
config {
disableAllHeaderCode = 1
admPanel = 0
}
10 = EXTBASEPLUGIN
10 {
extensionName = MyExtension
pluginName = ConferenceList
}
}
plugin.tx_myextension_conferencelist {
persistence.storagePid = 42
settings.itemsPerPage = 10
}
The links of the pagination carry the page type and the plugin arguments, so
the plugin receives the requested page number as it does on the regular page,
and each page of the list is cached on its own. When editors configure the
list in its content element instead, select that element with
CONTENT
as in the feed example.
Rendering one known content element on every page
A RECORDS object renders a content element by its uid, wherever it is stored. That suits a fragment that is the same on every page, for example a short list of upcoming conferences in the sidebar, which a small script in the page layout loads from the page type:
conferenceShortList = PAGE
conferenceShortList {
typeNum = 1762214402
config {
disableAllHeaderCode = 1
admPanel = 0
}
10 = RECORDS
10 {
tables = tt_content
source = 123
conf.tt_content = EXTBASEPLUGIN
conf.tt_content {
extensionName = MyExtension
pluginName = ConferenceList
}
}
}
An editor configures the short list in content element 123, and the plugin
is rendered for exactly that element on whatever page requests the page type.
The uid is fixed in TypoScript, so it fits a content element that is known
and stays in place, not one that editors create and delete.
Configuring the plugin in the page record as a last resort
Extbase does not check which table the record comes from. It reads the fields
pages
,
recursive
and
pi_ by name. When the page
record has fields with these names, a plugin rendered directly by
EXTBASEPLUGIN
uses them as it would use the fields of a content
element. Adding the three fields to the
pages
table in
TCA, showing them for a dedicated
page type,
and restricting the typeNum page type to that page type with a condition lets
editors configure the output in the page properties.
The field names are dictated by Extbase and end up as generic names in a core table that every extension extends, where another extension can add a field with the same name. Use it only when the output needs editor input and there is no content element to take it from.
Caching an Extbase plugin in a typeNum page type
A typeNum page type is cached like any other page. The page type is part of the page cache identifier, so the feed and the HTML page are cached separately, and the feed is rendered once and then delivered from the cache until the cache is cleared. Extbase plugin arguments in the URL create one cache entry per argument combination, protected by the cHash.
An action listed as non-cacheable turns the plugin into a
USER_INT object automatically,
exactly as it does in a content element. Wrapping the plugin in a
COA_, as some tutorials do, is not necessary.
To refresh the feed when a conference changes, use cache tags as for any other cached plugin output.
What to keep in mind with a typeNum page type
A page type is a full frontend page, with everything that brings. A few consequences are worth knowing before adding one.
- The frontend rendering runs for every uncached request
- TYPO3 resolves the site and the page, checks access, evaluates the site's
TypoScript and renders the
PAGEobject. From the page cache that is fast. Output that cannot be cached, such as anything depending on the logged-in frontend user, goes through all of it on every request. - The page type inherits the site's configuration
- The
PAGEobject starts from the globalconfigof the site, which is why page type examples switch off options such asdisableandAll Header Code adm. A site-wide option added later reaches the page type as well.Panel - The page type exists on every page
- A
PAGEobject applies wherever its TypoScript applies, usually to the whole site. Selecting the content withCONTENT, as in the feed example, keeps the output empty where it does not belong. TypoScript conditions can restrict a page type to some pages. - The typeNum is a number nothing reserves
- Every
PAGEobject needs a number that is unique in the site's TypoScript, and two extensions choosing the same number overwrite each other's page type without an error. A number derived from a timestamp, such as1533906435inEXT:, makes a collision unlikely.seo - The configuration spans several places
- The plugin configuration in
ext_localconf.php, thePAGEobject in TypoScript, and the PageType decorator in the site's routing work together. A site set ships the TypoScript and the routing in one place.
When a typeNum page type is the right tool
A typeNum page type fits when the output belongs to a page or benefits from what a page brings: a site, a language, access checks, and the page cache.
- Feeds and exports such as RSS or Atom feeds, calendar files in the iCalendar format, or a CSV export of a list on the page.
- Sitemaps and other machine-readable views of the page tree, as in
EXT:.seo - Alternative views of a page, such as a print version.
- Parts of a page that a script loads, such as the next page of a list or a fragment shown on every page.
It is also the natural approach outside Extbase. A page type does not need a plugin at all: TypoScript content objects such as CONTENT or PAGEVIEW can produce JSON or XML on their own, and the page type delivers their output under its own URL.
For small data that needs neither a page nor TypoScript, such as a live status or search suggestions, an endpoint that answers before the page rendering starts can be the lighter choice.
Alternatives to a typeNum page type
TYPO3 offers several other ways to deliver output that is not an HTML page, from requesting the regular page to answering in a middleware before any page is rendered. Ways to deliver non-HTML output from TYPO3 compares them, including what each one has available and what each one is suited for.