df_tabs

Table of Contents

1. Ext: df_tabs
2. Configuration reference
3. Upgrade instructions

---

Ext: df_tabs

License: GNU GPL, Version 2 or later

Repository: https://gitlab.sgalinski.de/typo3/df_tabs

Please report bugs here: https://gitlab.sgalinski.de/typo3/df_tabs/issues

About

df_tabs displays existing TYPO3 content elements or the content of selected pages in tabs. Editors choose the source records and can override individual tab titles. The default Fluid template uses Bootstrap 5 markup. Your theme supplies the Bootstrap styles and tab JavaScript; the extension does not load Bootstrap for you.

Requirements

• TYPO3 14.3.x, matching the extension's Composer constraint.
• A PHP version supported by your TYPO3 installation.
• Fluid Styled Content (typo3/cms-fluid-styled-content) for the default content element rendering.
• Bootstrap 5 CSS and its tab JavaScript for the default template, typically supplied by the theme.

Installation

1. Install the Composer package sgalinski/df-tabs and ensure Fluid Styled Content is installed.
2. Include the extension configuration through one of the following methods.
3. Ensure your theme loads Bootstrap 5 CSS and its tab JavaScript.
4. Create a Pages/Content Elements In Tabs content element in the TYPO3 backend.

Sites using site sets

Select the df_tabs set in the site configuration, or add its identifier to the dependencies of your site or site-package set:

dependencies:
    - sgalinski/df-tabs

Merge this entry into any existing dependency list. The set depends on typo3/fluid-styled-content and loads the shared TypoScript constants and rendering configuration without legacy CSS/JS includes. Your theme supplies Bootstrap 5. Existing static-template installations can retain their current integration; switching to the set is optional.

If your custom template needs the deprecated assets, explicitly select the additional df_tabs: Legacy frontend assets (deprecated) set (sgalinski/df-tabs-legacy-assets). It depends on the base set and adds the historical CSS/JS includes. See the asset integration notes.

Sites using TypoScript template records

In the template record, include Fluid Styled Content followed by the df_tabs static template. Static templates and site sets use separate include lists. The static template remains available for installations using template records and retains its existing legacy CSS/JS includes.

When mixing site sets with template records, leave the Clear flags for constants and setup unchecked so that the records do not discard configuration supplied by the site sets.

Usage

For an explicit selection, choose Combined mode and add pages or content elements in the Pages and Content That Shall be Rendered as Tabs field. Each selected record becomes one tab, in selection order. A page contributes its content elements rather than a complete rendered page.

Without an explicit selection, Show Pages uses the current page's direct subpages. Show Content Elements uses the configured content selection from the current page; see the selection details before relying on this fallback.

Under Override Tab Titles, enter one title per line. Use DEFAULT to keep a record's original title at that position. By default, page titles and content element headers supply the labels.

Selected content elements remain ordinary TYPO3 records. Referencing them in tabs does not remove them from their original frontend location; arrange the source records accordingly.

Configuration and customization

The configuration reference covers effective TypoScript settings, selection behavior, Fluid overrides, frontend assets and limitations. The current renderer always uses Fluid. Autoplay, hover navigation and configurable animation options described in older versions of this README are not implemented by the bundled frontend.

The legacy frontend JavaScript, CSS and Sass files are deprecated for removal in the next major release. This release retains the files and the existing static template's includes. The new base site set does not load them. See the deprecated asset list and preparation steps.

For an existing installation, also read UPGRADE.md.

Troubleshooting

• No df_tabs entry in the site-set selection: ensure the installed extension version contains Configuration/Sets/DfTabs/config.yaml. Installing an extension alone does not activate its set.
• Plain titles or inactive tabs: check that the selected template matches its frontend assets. The default template requires Bootstrap 5 CSS and tab JavaScript. The legacy tabs.js expects .m-tabs markup and does not initialize the default Bootstrap template. See the template options.
• Tab titles appear, but panels are empty: check the selected source records, their visibility, the page-content filters and the TypoScript used to render their content elements.
• Changes do not appear: clear the TYPO3 frontend caches after changing templates or configuration.

The frontend regression tests in tests/Frontend/tabs.spec.ts cover the existing Bootstrap markup, theme styling, independent tab groups and keyboard navigation. In WebsiteBase they are registered as the Extension: df-tabs Playwright project, with and without legacy assets. The PHPUnit tests under tests/Unit/Configuration/ check effective TypoScript configuration, existing static-template behavior, optional legacy assets and preservation of theme-provided includes.

---

Configuration reference

This reference describes the current Fluid renderer and Bootstrap template. Existing legacy assets and configuration properties remain available in this release. They are documented here according to their actual effect; their presence does not mean the default template uses them.

Including the configuration

Follow the installation instructions before adding overrides. The existing static template and the new site sets share constants and rendering configuration:

Entry point	Rendering	Legacy CSS/JS includes
Static template df_tabs / Configuration/TypoScript/setup.typoscript	Yes	Yes, unchanged.
Site set sgalinski/df-tabs	Yes	No.
Optional site set sgalinski/df-tabs-legacy-assets	Through its dependency on sgalinski/df-tabs	Yes, explicitly enabled.

Configuration/TypoScript/constants.typoscript retains existing constants and defaults. Configuration/TypoScript/Rendering/setup.typoscript contains the shared rendering setup. Configuration/TypoScript/LegacyAssets/setup.typoscript contains only the historical asset includes. The original setup.typoscript imports both files, preserving direct imports and static-template behavior.

All entry points use the namespace plugin.tx_dftabs_plugin1. Constants and setup are separate configuration layers: place each example below in the indicated layer. Content element FlexForm values override TypoScript values when those FlexForm values are non-empty.

Frontend assets

The default template requires Bootstrap 5 CSS and the Bootstrap tab JavaScript from the site's theme. The extension does not load Bootstrap. WebsiteBase already provides this integration. Other themes must provide it before tab styling and switching will work.

The existing static template and optional legacy site set retain these includes. The base site set sgalinski/df-tabs does not add them:

Include	Default asset	Role
page.includeCSS.dftabs	EXT:df_tabs/Resources/Public/StyleSheets/df_tabs.css	Legacy styles, including .m-tabs selectors.
page.includeJSFooter.dftabs	EXT:df_tabs/Resources/Public/JavaScript/tabs.js	Initializes .m-tabs markup; does not initialize the default Bootstrap template.

These declarations and files are retained to avoid changing integrations that may use them with custom templates. They do not replace Bootstrap. WebsiteBase already removes both includes and uses the theme's assets instead.

For a new Bootstrap integration, activate only sgalinski/df-tabs. It does not load legacy assets and does not remove or overwrite existing theme asset entries.

If a custom template needs the deprecated CSS/JS, select df_tabs: Legacy frontend assets (deprecated) or add this dependency to your site or site-package set:

dependencies:
  - sgalinski/df-tabs-legacy-assets

Merge this entry into the site's existing dependency list. The optional set depends on sgalinski/df-tabs, so TYPO3 loads the base configuration before adding the legacy assets. Do not also add the static template when using the site sets.

For a manual TypoScript integration that imports only the rendering setup, the asset-only include can be added explicitly after the rendering setup:

@import 'EXT:df_tabs/Configuration/TypoScript/LegacyAssets/setup.typoscript'

Sites using the existing static template or importing Configuration/TypoScript/setup.typoscript already get these legacy assets; they do not need another include.

For a Bootstrap theme that does not use these legacy files, the includes can be removed explicitly in the site's TypoScript setup:

page.includeCSS.dftabs >
page.includeJSFooter.dftabs >

Existing custom integrations can still replace their paths through the plugin.tx_dftabs_plugin1.css and plugin.tx_dftabs_plugin1.js.dftabs constants. The extension does not remove these options or change their defaults in this release. If a custom template uses the legacy assets, retain the matching asset includes.

Deprecated frontend assets

The following files are deprecated and scheduled for removal in the next major release:

• Resources/Public/JavaScript/tabs.js
• Resources/Public/Scripts/jquery.tabs.js
• Resources/Public/Scripts/tabAnimation.js
• Resources/Public/StyleSheets/df_tabs.css
• Resources/Public/Sass/df_tabs.scss

This release retains these files and their asset-path constants. Their existing includes remain in the static template and are available through the optional legacy set. The base site set never adds them. Deprecation does not add browser-console warnings or change frontend behavior. Backend preview styles, icons and images are outside this deprecation.

For new integrations, use the default Bootstrap template with Bootstrap 5 CSS and tab JavaScript provided by your theme. Before upgrading to the next major release, review custom templates, script imports, Sass imports and TypoScript asset overrides that reference the deprecated files. Replace their tab behavior and styles in your theme, then remove the obsolete includes. A custom .m-tabs or tx-dftabs template needs its matching frontend implementation; switching to the Bootstrap template may also require adapting project styles and selectors.

Source selection

The backend offers the following modes:

Mode	Selection and fallback
pages	Each selected page contributes one tab containing its content elements. With an empty selection, direct subpages of the current page are selected in sorting order.
tt_content	Each selected content element contributes one tab. With an empty selection, the fallback is based on styles.content.get, restricts the selection to the tabs element's colPos and skips the first selected record (begin = 1).
combined	Allows explicitly selected pages and content elements in one list. No automatic selection is configured for an empty list.

Choose Combined for a mixed selection explicitly. The selection field's existing backend help text says that this mode is forced automatically, but the current configuration service does not change the mode based on the selection.

The tt_content fallback does not calculate the current tabs element's position in the content sorting order. Use an explicit selection for predictable sources, and keep the tabs element out of its own source content, including content selected through a page.

Page content

These TypoScript constants control the content selected from each source page:

Constant below plugin.tx_dftabs_plugin1	Default	Meaning
pages.limit	999	Maximum number of content records per page; 0 removes this limit.
pages.orderBy	colPos,sorting	Comma-separated order fields for the page's content records.
pages.additionalWhere	AND colPos >= 0	Additional SQL condition for the page's content records.
pages.titleField	title	Page field used for the tab title.
tt_content.titleField	header	Content element field used for the tab title.
defaultTabTitle	Tab	Fallback when the resulting title is empty.
removeFromTitle	empty	Regular expression removed from titles before HTML escaping. Supply the pattern without surrounding / delimiters.

For example, to include only column zero from source pages and remove a trailing title suffix, place this in TypoScript constants:

plugin.tx_dftabs_plugin1 {
	pages.additionalWhere = AND colPos = 0
	removeFromTitle = Foo$
}

Page content is selected from default-language and all-language records; rendering through TYPO3's RECORDS object applies the record visibility and language handling. It does not render the source page's full page layout.

Titles and explicit record lists

The backend title override field uses one line per tab. DEFAULT keeps the original title. The complete field is trimmed before splitting, so leading blank lines cannot preserve initial titles; use DEFAULT for those positions.

For configuration through TypoScript setup, use data for source records and a comma-separated titles value. Prefix record IDs with their table for a mixed selection:

plugin.tx_dftabs_plugin1 {
	mode = combined
	data = pages_12,tt_content_34
	titles = Overview,DEFAULT
}

A content element's non-empty FlexForm values take precedence over these defaults. The data constant declared in constants.typoscript is not copied into setup; set the setup property directly as shown above.

For advanced content rendering overrides, the data provider merges the top-level setup property plugin.tx_dftabs_plugin1.records into the RECORDS configuration used for tab contents. The stdWrap.records placeholder in the shipped setup is not read by that data provider.

Fluid template

The default template is Resources/Private/Templates/Standard/Tabs.fluid.html. It preserves the existing Bootstrap structure: .nav.nav-pills, .nav-item, .nav-link, .tab-content, .tab-pane.fade and the data-bs-toggle="pill" / data-bs-target attributes. Bootstrap manages the active and show classes. Themes can continue styling these elements and supplying their own responsive navigation.

The default IDs retain the pills-{record}-{index} format and the tablist retains pills-tab-df-tabs. Repeating the same source records in multiple default instances can therefore produce duplicate IDs; use a project template override if your installation needs another ID scheme.

Copy the default template to your site package at Resources/Private/Templates/DfTabs/Standard/Tabs.fluid.html and add a higher-priority root path in TypoScript setup:

plugin.tx_dftabs_plugin1.view.templateRootPaths.20 = EXT:site_package/Resources/Private/Templates/DfTabs/

You can similarly add partialRootPaths.20 and layoutRootPaths.20 beneath plugin.tx_dftabs_plugin1.view. Do not edit the installed extension template directly.

The view receives:

Variable	Contents
tabElements	Tab objects with title, record, link and rendered content properties. Titles are already HTML-escaped by the repository; content is rendered HTML.
tabId	Identifier generated for this rendering of the tabs element.

Frontend behavior and remaining legacy settings

With the default template, Bootstrap controls panel switching, selected states and keyboard navigation. Responsive navigation is supplied by the theme; WebsiteBase provides its own mobile dropdown. The extension does not add a second tab implementation to the default template.

The link property is available to custom templates but is not used by the default template to navigate to source pages. The default panel IDs continue to use record IDs and iteration indexes; the generated tabId variable is available for custom templates but does not change those IDs.

The following settings do not configure the default Fluid template or Bootstrap integration:

• enableAutoPlay, autoPlayInterval, enableMouseOver
• enableJavascript, hashName, changeHashOnTabChange, pollingInterval, startIndex
• animationSpeed, animationCallback, slideOffset, forceUsageOfLeft
• menuNodeType, contentNodeType and the events callbacks
• stdWrap.tabTitle, stdWrap.tabContents, stdWrap.tabContent, stdWrap.tabMenu and stdWrap.tabMenuEntry
• stdWrap.typoscriptData and stdWrap.typoscriptLinks

classPrefix still controls the outer plugin wrapper, but it does not rename the Bootstrap classes in the template. renderer does not select an alternative renderer: the controller uses Fluid, and the factory only provides content-element and page data providers. There is no supported typoscript data-provider mode in this rendering path. The old files under Resources/Public/Scripts/ are not the assets loaded by the current setup.

Setting the backend Hash field does not change the panel IDs used by the bundled frontend. Autoplay, hover navigation, configurable animations and legacy renderer options are not enabled by the default integration. Existing files and settings remain in this release; the frontend assets listed above are deprecated for removal in the next major release. Further cleanup of legacy settings requires a separate assessment of consumers and upgrade impact.

---

Upgrade instructions

Switching to site sets (optional)

• Remove the existing df_tabs static include if you activate sgalinski/df-tabs. The base site set uses the same rendering configuration but does not load the deprecated CSS/JS assets.
• If your custom template still needs those assets, activate sgalinski/df-tabs-legacy-assets instead; it depends on the base set and adds the historical includes. Keep your theme's Bootstrap integration for the default template.
• If you retain the existing static template, no change is required.

Prepare for the next major release

• If custom templates or theme assets use the deprecated frontend JavaScript, CSS or Sass files, replace those dependencies before upgrading to the next major release. See the asset list and preparation steps. No changes are required for this deprecation in the current release.

Version 11

• Use TYPO3 14.3.x; other TYPO3 release lines are outside the Composer constraint for this version.

Version 10

• Upgrade installations still using TYPO3 12 to the TYPO3 version required by the target release.
• Replace PHP 8.0, 8.1 or 8.2 with a PHP version supported by the target release.
• For old list plugins, run the existing Migrate "SGalinski DfTabs" plugins to content elements. upgrade wizard. It migrates records and backend user permissions to CType = df_tabs_plugin1. Update project-owned TypoScript that still targets the old list-plugin registration.

Version 9

• Upgrade installations still using TYPO3 10 or 11, or PHP 7, before installing this release line.

Version 8

• Replace custom integrations using the TypoScript renderer with Fluid template overrides.
• Replace references to the removed _alternative and _flat stylesheets and check custom styles against the distributed CSS.
• Upgrade installations still using TYPO3 9 before installing this release line.

Version 7

• Upgrade installations still using TYPO3 8 before installing this release line.