plugin

This is used for extensions in TYPO3 set up as frontend plugins. Typically you can set configuration properties of the plugin here. Say you have an extension with the key "myext" and it has a frontend plugin named "tx_myext_pi1" then you would find the TypoScript configuration at the position plugin.tx_myext_pi1 in the object tree!

Most plugins are USER and USER_INT objects which means that they have at least 1 or 2 reserved properties. Furthermore this table outlines some other default properties. Generally system properties are prefixed with an underscore:

Properties for all frontend plugin types

Name Type
userFunc
 (array of keys)
_CSS_DEFAULT_STYLE
 string / stdWrap

userFunc

userFunc
Type
(array of keys)

Property setting up the USER and USER_INT object of the plugin.

_CSS_DEFAULT_STYLE

_CSS_DEFAULT_STYLE
Type
string / stdWrap

Use this to have some default CSS styles inserted in the header section of the document. _CSS_DEFAULT_STYLE outputs a set of default styles, just because an extension is installed. Most likely this will provide an acceptable default display from the plugin, but should ideally be cleared and moved to an external stylesheet.

This value is read by the frontend RequestHandler script when collecting the CSS of the document to be rendered.

This is for example used by frontend and indexed_search. Their default styles can be removed with:

EXT:site_package/Configuration/TypoScript/setup.typoscript 
plugin.tx_frontend._CSS_DEFAULT_STYLE >
plugin.tx_indexedsearch._CSS_DEFAULT_STYLE >
Copied!

However, you will then have to define according styles yourself.

CSS_PAGE_STYLE

CSS_PAGE_STYLE
Type
string
Default
false

Deprecated since version 12.1

Integrators should avoid using _CSS_PAGE_STYLE on plugin level. They should switch adding CSS on a PAGE level. A direct replacement using page.cssInline looks like this:

Before:

plugin.tx_myPlugin._CSS_PAGE_STYLE (
    .myClass { text-align: center }
)
Copied!

After:

page.cssInline {
    10 = TEXT
    10.value (
        .myClass { text-align: center }
    )
}
Copied!

As a general note, the PAGE property includeCSS is often better suited to include CSS as files, especially when frontend CSS is generated by some processor like SCSS.

Properties for all frontend plugins based on Extbase

Extbase is an extension framework to create frontend plugins.

features.skipDefaultArguments

features.skipDefaultArguments
Type
boolean
Default
false

Deprecated since version 12.4

Only for Extbase plugins. Skip default arguments in URLs. If a link to the default controller or action is created, the parameters are omitted.

ignoreFlexFormSettingsIfEmpty

ignoreFlexFormSettingsIfEmpty
Type
string
Example
Ignore certain FlexForm settings if empty

New in version 12.3

Define FlexForm settings that will be ignored in the extension settings merge process, if their value is considered empty (either an empty string or a string containing 0).

Additionally, there is the PSR-14 event BeforeFlexFormConfigurationOverrideEvent available to further manipulate the merged configuration after standard override logic is applied.

persistence

persistence
Type
array of settings
Example
Set recursive storage PID for Extbase plugin

Settings, relevant to the persistence layer of Extbase.

persistence.enableAutomaticCacheClearing

persistence.enableAutomaticCacheClearing
Type
boolean
Default
true

Only for Extbase plugins. Enables the automatic cache clearing when changing data sets (see also Caching).

persistence.storagePid

persistence.storagePid
Type
string (comma separated list of integers)
Example
Set recursive storage PID for Extbase plugin

Only for Extbase plugins. List of page IDs, from which all records are read.

persistence.recursive

persistence.recursive
Type
integer
Example
Set recursive storage PID for Extbase plugin

Only for Extbase plugins. Number of sub-levels of the storagePid are read.

view.[settings]

view.[settings]
Type
settings
Example
Set template paths for Extbase plugin

View and template settings.

All root paths are defined as an array which enables you to define multiple root paths that will be used by Extbase to find the desired template files.

The root paths work just like the one in the FLUIDTEMPLATE.

view.layoutRootPaths.[array]

view.layoutRootPaths.[array]
Type
string
Example
Set template paths for Extbase plugin

Only for Extbase plugins. This can be used to specify the root paths for all Fluid layouts. If nothing is specified, the path EXT:my_extension/Resources/Private/Layouts is used.

view.partialRootPaths.[array]

view.partialRootPaths.[array]
Type
string
Example
Set template paths for Extbase plugin

Only for Extbase plugins. This can be used to specify the root paths for all Fluid partials. If nothing is specified, the path EXT:my_extension/Resources/Private/Partials is used.

view.templateRootPaths.[array]

view.templateRootPaths.[array]
Type
string
Example
Set template paths for Extbase plugin

Only for Extbase plugins. This can be used to specify the root paths for all Fluid templates in this plugin. If nothing is specified, the path EXT:my_extension/Resources/Private/Templates is used.

view.pluginNamespace.[array]

view.pluginNamespace.[array]
Type
string
Example
Set template paths for Extbase plugin

This can be used to specify an alternative namespace for the plugin. Use this to shorten the Extbase default plugin namespace or to access arguments from other extensions by setting this option to their namespace.

mvc.[setting]

mvc.[setting]
Type
array of settings

Only for Extbase plugins. These are useful MVC settings about error handling:

mvc.callDefaultActionIfActionCantBeResolved

mvc.callDefaultActionIfActionCantBeResolved
Type
boolean
Default
false
Example
Call default action if action cannot be resolved

Only for Extbase plugins. If set, causes the controller to show its default action if the called action is not allowed by the controller.

mvc.throwPageNotFoundExceptionIfActionCantBeResolved

mvc.throwPageNotFoundExceptionIfActionCantBeResolved
Type
boolean
Default
false
Example
Show 404 (page not found) page if action cannot be resolved

Same as Properties for all frontend plugins based on Extbase but this will raise a "page not found" error.

format

format
Type
string
Default
html
Example
Define alternative output formats for RSS feeds

Define the default file ending of the template files. The template files have to take care of creating the desired format output.

_LOCAL_LANG.[lang-key].[label-key]

_LOCAL_LANG.[lang-key].[label-key]
Type
string
Example
Override a language key in an Extbase plugin

Can be used to override the default language labels for Extbase plugins. The lang-key setup part is default for the default language of the website or the 2-letter (ISO 639-1) code for the language. label-key is the 'trans-unit id' XML value in the XLF language file which resides in the path Resources/Private/Language of the extension or in the typo3conf/l10n/[lang-key] (var/labels/[lang-key] in composer mode) subfolder of the TYPO3 root folder. And on the right side of the equation sign '=' you put the new value string for the language key which you want to override.

All variables, which are used inside an Extbase extension with the ViewHelper <f:translate> can that way be overwritten with TypoScript. The locallang.xlf file in the plugin folder in the file system can be used to get an overview of the entries the extension uses.

settings.[setting]

settings.[setting]
Type
array of custom settings

Here all the settings, both extension-wide and plugin-specific, reside. These settings are available in the controllers as the array variable $this->settings and in any Fluid template with {settings}.

The settings for a specific plugin can be overridden by FlexForm values of the same name.

Extbase plugin TypoScript examples

Plugin general examples

Examples: Ignore certain FlexForm settings if empty

Demonstrates:

Definition for all plugins of an extension:

EXT:my_extension/Configuration/TypoScript/setup.typoscript 
plugin.tx_myextension.ignoreFlexFormSettingsIfEmpty = field1,field2
Copied!

Definition for one plugin of an extension:

EXT:my_extension/Configuration/TypoScript/setup.typoscript 
plugin.tx_myextension_myplugin.ignoreFlexFormSettingsIfEmpty = field1,field2
Copied!

If an extension already defined ignoreFlexFormSettingsIfEmpty, integrators are advised to use addToList or removeFromList to modify existing settings:

EXT:my_extension/Configuration/TypoScript/setup.typoscript 
plugin.tx_myextension_myplugin.ignoreFlexFormSettingsIfEmpty := removeFromList(field1)
plugin.tx_myextension_myplugin.ignoreFlexFormSettingsIfEmpty := addToList(field3)
Copied!

Plugin persistence Examples

Example: Disable automatic cache clearing for an Extbase plugin

Demonstrates:
EXT:blog_example/Configuration/TypoScript/setup.typoscript 
plugin.tx_blogexample_admin {
    persistence {
        enableAutomaticCacheClearing = 0
    }
}
Copied!

Example: Set recursive storage PID for Extbase plugin

Demonstrates:
EXT:blog_example/Configuration/TypoScript/setup.typoscript 
plugin.tx_blogexample {
    persistence {
        storagePid = 42
        # Includes 4 sub-levels of the storagePid
        recursive = 4
    }
}
Copied!

Plugin view Examples

Example: Set template paths for Extbase plugin

Demonstrates:
EXT:blog_example/Configuration/TypoScript/setup.typoscript 
plugin.tx_blogexample {
    view {
        layoutRootPaths {
            0 = EXT:blog_example/Resources/Private/Layouts/
            10 = EXT:my_extension/Resources/Private/Layouts/
        }
        partialRootPaths {
            0 = EXT:blog_example/Resources/Private/Partials/
            10 = EXT:my_extension/Resources/Private/Partials/
        }
        templateRootPaths {
            0 = EXT:blog_example/Resources/Private/Templates/
            10 = EXT:my_extension/Resources/Private/Templates/
        }
    }
}
Copied!

Plugin MVC Examples

Example: Call default action if action cannot be resolved

Demonstrates:
EXT:blog_example/Configuration/TypoScript/setup.typoscript 
plugin.tx_blogexample {
    mvc {
        callDefaultActionIfActionCantBeResolved = 1
    }
}
Copied!

Example: Show 404 (page not found) page if action cannot be resolved

Demonstrates:
EXT:blog_example/Configuration/TypoScript/setup.typoscript 
plugin.tx_blogexample {
    mvc {
        throwPageNotFoundExceptionIfActionCantBeResolved = 1
    }
}
Copied!

Plugin format examples

Example: Define alternative output formats for RSS feeds

Demonstrates:
EXT:blog_example/Configuration/TypoScript/setup.typoscript 
plugin.tx_blogexample_rssfeedxml {
    // Use template List.xml
    format = xml
}
plugin.tx_blogexample_rssfeedatom {
    // Use template List.atom
    format = atom
}
Copied!

Plugin localization examples

Example: Override a language key in an Extbase plugin

Demonstrates:
EXT:site_package/Configuration/TypoScript/setup.typoscript 
plugin.tx_myext_pi1._LOCAL_LANG.de.list_mode_1 = Der erste Modus
Copied!