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.

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:seo is a PAGE object with typeNum = 1533906435 .

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.xml.

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 registerPlugin() call:

EXT:my_extension/ext_localconf.php
<?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'],
);
Copied!

The PAGE object selects the list content element with a CONTENT object and renders the feed plugin for it with EXTBASEPLUGIN:

EXT:my_extension/Configuration/Sets/MyExtension/setup.typoscript
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
  }
}
Copied!
  • CONTENT searches the current page, in the current language, as the page template does. The where clause 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, so max = 1 takes only the first list.
  • The renderObj runs 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.
  • The renderObj is EXTBASEPLUGIN and not tt_content.myextension_conferencelist . The content element rendering wraps the plugin output in the HTML of the content element layout, which has no place in an XML document.
  • 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:

EXT:my_extension/Classes/Controller/ConferenceFeedController.php
<?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()));
  }
}
Copied!

findFiltered() 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 feedAction() renders Templates/ConferenceFeed/Feed.fluid.xml instead of Feed.fluid.html, see Fluid template file resolution. Setting the format in initializeFeedAction() 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:

EXT:my_extension/Resources/Private/Templates/ConferenceFeed/Feed.fluid.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>
Copied!

The Content-Type 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:seo 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://example.org/conferences/europe is available at https://example.org/conferences/europe/feed.xml instead of https://example.org/conferences/europe?type=1762214400:

EXT:my_extension/Configuration/Sets/MyExtension/route-enhancers.yaml
routeEnhancers:
  PageTypeSuffix:
    type: PageType
    default: ''
    map:
      'feed.xml': 1762214400
Copied!

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:

EXT:my_extension/Resources/Private/Templates/Conference/List.fluid.html
<f:link.page pageType="1762214400">Subscribe to this list as a feed</f:link.page>
Copied!

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 CONTENT or RECORDS .
  • EXTBASEPLUGIN placed directly in the PAGE object 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 page 0 if 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:

EXT:my_extension/Configuration/Sets/MyExtension/setup.typoscript
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
}
Copied!

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:

EXT:my_extension/Configuration/Sets/MyExtension/setup.typoscript
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
    }
  }
}
Copied!

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_flexform 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_INT , 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 PAGE object. 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 PAGE object starts from the global config of the site, which is why page type examples switch off options such as disableAllHeaderCode and admPanel . A site-wide option added later reaches the page type as well.
The page type exists on every page
A PAGE object applies wherever its TypoScript applies, usually to the whole site. Selecting the content with CONTENT , 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 PAGE object 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 as 1533906435 in EXT:seo, makes a collision unlikely.
The configuration spans several places
The plugin configuration in ext_localconf.php, the PAGE object 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.