--- title: "plugin" manual: "TypoScript Explained" version: "main" permalink: "https://docs.typo3.org/permalink/t3tsref:plugin@main" source: "TopLevelObjects/Plugin.rst" rendered: "2026-09-18T06:55:17+00:00" --- # plugin {#plugin-1} 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_myextension_pi1` in the object tree! Most plugins are [USER and USER_INT](https://docs.typo3.org/permalink/t3tsref:cobj-user@main) 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](https://docs.typo3.org/permalink/t3tsref:properties-for-all-frontend-plugin-types@main) - [Properties for all frontend plugins based on Extbase](https://docs.typo3.org/permalink/t3tsref:properties-for-all-frontend-plugins-based-on-extbase@main) - [Extbase plugin TypoScript examples](https://docs.typo3.org/permalink/t3tsref:extbase-plugin-typoscript-examples@main) ## Properties for all frontend plugin types {#properties-for-all-frontend-plugin-types} **userFunc** - **userFunc** - *Type:* (array of keys) Property setting up the [USER and USER_INT](https://docs.typo3.org/permalink/t3tsref:cobj-user@main) object of the plugin. **\_CSS_DEFAULT_STYLE** - **\_CSS_DEFAULT_STYLE** - *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@main) / [stdWrap](https://docs.typo3.org/permalink/t3tsref:stdwrap@main) 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/Sets/Main/setup.typoscript** ```typoscript plugin.tx_frontend._CSS_DEFAULT_STYLE > plugin.tx_indexedsearch._CSS_DEFAULT_STYLE > ``` However, you will then have to define according styles yourself. ## Properties for all frontend plugins based on Extbase {#properties-for-all-frontend-plugins-based-on-extbase} [Extbase](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/Extbase/Index.html#extbase) is an extension framework to create frontend plugins. **ignoreFlexFormSettingsIfEmpty** - **ignoreFlexFormSettingsIfEmpty** - *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@main) - *Example:* [Ignore certain FlexForm settings if empty](https://docs.typo3.org/permalink/t3tsref:setup-plugin-configuration-ignoreflexformsettingsifempty-example@main) Define [FlexForm](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/FlexForms/Index.html#flexforms) 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](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Events/Events/Extbase/Configuration/BeforeFlexFormConfigurationOverrideEvent.html#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](https://docs.typo3.org/permalink/t3tsref:setup-plugin-persistence-storagepid-example@main) Settings, relevant to the persistence layer of Extbase. **persistence.enableAutomaticCacheClearing** - **persistence.enableAutomaticCacheClearing** - *Type:* [boolean](https://docs.typo3.org/permalink/t3tsref:data-type-boolean@main) - *Default:* `true` **Only for Extbase plugins**. Enables the automatic cache clearing when changing data sets (see also [Caching for Extbase plugins](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/Extbase/Caching/Index.html#extbase_caching)). **persistence.storagePid** - **persistence.storagePid** - *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@main) (comma separated list of integers) - *Example:* [Set recursive storage PID for Extbase plugin](https://docs.typo3.org/permalink/t3tsref:setup-plugin-persistence-storagepid-example@main) **Only for Extbase plugins**. List of page IDs, from which all records are read. **persistence.classes.\[classname\].newRecordStoragePid** - **persistence.classes.\[classname\].newRecordStoragePid** - *Type:* [integer](https://docs.typo3.org/permalink/t3tsref:data-type-integer@main) - *Example:* [Set storage PID for new records of Extbase plugin](https://docs.typo3.org/permalink/t3tsref:setup-plugin-persistence-classes-classname-newrecordstoragepid-example@main) **Only for Extbase plugins**. Page ID, where new records for objects of the class `[classname]` are stored. **persistence.recursive** - **persistence.recursive** - *Type:* [integer](https://docs.typo3.org/permalink/t3tsref:data-type-integer@main) - *Example:* [Set recursive storage PID for Extbase plugin](https://docs.typo3.org/permalink/t3tsref:setup-plugin-persistence-storagepid-example@main) **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](https://docs.typo3.org/permalink/t3tsref:setup-plugin-view-example@main) 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](https://docs.typo3.org/permalink/t3tsref:cobj-fluidtemplate-properties-templaterootpaths@main). **view.layoutRootPaths.\[array\]** - **view.layoutRootPaths.\[array\]** - *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@main) - *Example:* [Set template paths for Extbase plugin](https://docs.typo3.org/permalink/t3tsref:setup-plugin-view-example@main) **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](https://docs.typo3.org/permalink/t3tsref:data-type-string@main) - *Example:* [Set template paths for Extbase plugin](https://docs.typo3.org/permalink/t3tsref:setup-plugin-view-example@main) **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](https://docs.typo3.org/permalink/t3tsref:data-type-string@main) - *Example:* [Set template paths for Extbase plugin](https://docs.typo3.org/permalink/t3tsref:setup-plugin-view-example@main) **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** - **view.pluginNamespace** - *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@main) - *Example:* [Set template paths for Extbase plugin](https://docs.typo3.org/permalink/t3tsref:setup-plugin-view-example@main) 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](https://docs.typo3.org/permalink/t3tsref:data-type-boolean@main) - *Default:* `false` - *Example:* [Call default action if action cannot be resolved](https://docs.typo3.org/permalink/t3tsref:setup-plugin-mvc-calldefaultactionifactioncantberesolved-example@main) **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](https://docs.typo3.org/permalink/t3tsref:data-type-boolean@main) - *Default:* `false` - *Example:* [Show 404 (page not found) page if action cannot be resolved](https://docs.typo3.org/permalink/t3tsref:setup-plugin-mvc-throwpagenotfoundexceptionifactioncantberesolved-example@main) Same as [Properties for all frontend plugins based on Extbase](https://docs.typo3.org/permalink/t3tsref:setup-plugin-mvc-calldefaultactionifactioncantberesolved@main) but this will raise a "page not found" error. **mvc.showPageNotFoundIfTargetNotFoundException** - **mvc.showPageNotFoundIfTargetNotFoundException** - *Type:* [boolean](https://docs.typo3.org/permalink/t3tsref:data-type-boolean@main) - *Default:* `false` **Only for Extbase plugins**. By default, when calling an extbase controller action that is not registered for an Extbase plugin, a fatal exception `TargetNotFoundException` is thrown (usually an internal error message is shown). When this configuration option is set to `1` (true), instead the default "Page not Found" page will be shown instead (with a 404 HTTP header by default). The configuration option can be either set on the global `config.tx_extbase` scope, or also plugin-specific via `plugin.tx_yourextension.mvc.showPageNotFoundIfTargetNotFoundException` / `plugin.tx_yourextension_pluginName.mvc.showPageNotFoundIfTargetNotFoundException`. **mvc.showPageNotFoundIfRequiredArgumentIsMissingException** - **mvc.showPageNotFoundIfRequiredArgumentIsMissingException** - *Type:* [boolean](https://docs.typo3.org/permalink/t3tsref:data-type-boolean@main) - *Default:* `false` **Only for Extbase plugins**. By default, when calling an extbase controller action with missing/invalid required arguments a fatal exception `RequiredArgumentMissingException` is thrown (usually an internal error message is shown). When this configuration option is set to `1` (true), instead the default "Page not Found" page will be shown instead (with a 404 HTTP header by default). The configuration option can be either set on the global `config.tx_extbase` scope, or also plugin-specific via `plugin.tx_yourextension.mvc.showPageNotFoundIfRequiredArgumentIsMissingException` / `plugin.tx_yourextension_pluginName.mvc.showPageNotFoundIfRequiredArgumentIsMissingException`. Note that extension authors can also implement the Controller method `ActionController->handleArgumentMappingExceptions()` to individually operate on invalid arguments. **format** - **format** - *Type:* [string](https://docs.typo3.org/permalink/t3tsref:data-type-string@main) - *Default:* `html` - *Example:* [Define alternative output formats for RSS feeds](https://docs.typo3.org/permalink/t3tsref:extbase-format-example@main) > [!WARNING] > Using this parameter is considered bad practice. In most cases it is better > use different actions for different output formats. 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](https://docs.typo3.org/permalink/t3tsref:data-type-string@main) - *Example:* [Override a language key in an Extbase plugin](https://docs.typo3.org/permalink/t3tsref:setup-plugin-local-lang-example@main) 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 `` 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 {#extbase-plugin-typoscript-examples} - [Plugin general examples](https://docs.typo3.org/permalink/t3tsref:plugin-general-examples@main) - [Plugin persistence Examples](https://docs.typo3.org/permalink/t3tsref:plugin-persistence-examples@main) - [Plugin view Examples](https://docs.typo3.org/permalink/t3tsref:plugin-view-examples@main) - [Plugin MVC Examples](https://docs.typo3.org/permalink/t3tsref:plugin-mvc-examples@main) - [Plugin format examples](https://docs.typo3.org/permalink/t3tsref:plugin-format-examples@main) - [Plugin localization examples](https://docs.typo3.org/permalink/t3tsref:plugin-localization-examples@main) ### Plugin general examples {#plugin-general-examples} #### Examples: Ignore certain FlexForm settings if empty {#examples-ignore-certain-flexform-settings-if-empty} - **Demonstrates:** - [plugin.\[extension\].ignoreFlexFormSettingsIfEmpty](https://docs.typo3.org/permalink/t3tsref:confval-plugin-ignoreflexformsettingsifempty@main) Definition for *all* plugins of an extension: **EXT:my_extension/Configuration/Sets/Main/setup.typoscript** ```typoscript plugin.tx_myextension.ignoreFlexFormSettingsIfEmpty = field1,field2 ``` Definition for *one* plugin of an extension: **EXT:my_extension/Configuration/Sets/Main/setup.typoscript** ```typoscript plugin.tx_myextension_myplugin.ignoreFlexFormSettingsIfEmpty = field1,field2 ``` If an extension already defined `ignoreFlexFormSettingsIfEmpty`, integrators are advised to use `addToList` or `removeFromList` to modify existing settings: **EXT:my_extension/Configuration/Sets/Main/setup.typoscript** ```typoscript plugin.tx_myextension_myplugin.ignoreFlexFormSettingsIfEmpty := removeFromList(field1) plugin.tx_myextension_myplugin.ignoreFlexFormSettingsIfEmpty := addToList(field3) ``` ### Plugin persistence Examples {#plugin-persistence-examples} #### Example: Disable automatic cache clearing for an Extbase plugin {#example-disable-automatic-cache-clearing-for-an-extbase-plugin} - **Demonstrates:** - [plugin.\[extension\].persistence.enableAutomaticCacheClearing](https://docs.typo3.org/permalink/t3tsref:confval-plugin-persistence-enableautomaticcacheclearing@main) **EXT:blog_example/Configuration/Sets/BlogExample/setup.typoscript** ```typoscript plugin.tx_blogexample_admin { persistence { enableAutomaticCacheClearing = 0 } } ``` #### Example: Set recursive storage PID for Extbase plugin {#example-set-recursive-storage-pid-for-extbase-plugin} - **Demonstrates:** - [plugin.\[extension\].persistence.storagePid](https://docs.typo3.org/permalink/t3tsref:confval-plugin-persistence-storagepid@main) - [plugin.\[extension\].persistence.classes.\[classname\].newRecordStoragePid](https://docs.typo3.org/permalink/t3tsref:confval-plugin-persistence-classes-classname-newrecordstoragepid@main) - [plugin.\[extension\].persistence.recursive](https://docs.typo3.org/permalink/t3tsref:confval-plugin-persistence-recursive@main) **EXT:blog_example/Configuration/Sets/BlogExample/setup.typoscript** ```typoscript plugin.tx_blogexample { persistence { storagePid = 42 # Includes 4 sub-levels of the storagePid recursive = 4 T3docs\BlogExample\Domain\Model\Post { newRecordStoragePid = 43 } T3docs\BlogExample\Domain\Model\Comment { newRecordStoragePid = 44 } } } ``` ### Plugin view Examples {#plugin-view-examples} #### Example: Set template paths for Extbase plugin {#example-set-template-paths-for-extbase-plugin} - **Demonstrates:** - [plugin.\[extension\].view.layoutRootPaths.\[array\]](https://docs.typo3.org/permalink/t3tsref:confval-plugin-view-layoutrootpaths@main) - [plugin.\[extension\].view.partialRootPaths.\[array\]](https://docs.typo3.org/permalink/t3tsref:confval-plugin-view-partialrootpaths@main) - [plugin.\[extension\].view.templateRootPaths.\[array\]](https://docs.typo3.org/permalink/t3tsref:confval-plugin-view-templaterootpaths@main) **EXT:blog_example/Configuration/Sets/BlogExample/setup.typoscript** ```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/ } } } ``` ### Plugin MVC Examples {#plugin-mvc-examples} #### Example: Call default action if action cannot be resolved {#example-call-default-action-if-action-cannot-be-resolved} - **Demonstrates:** - [plugin.\[extension\].mvc.callDefaultActionIfActionCantBeResolved](https://docs.typo3.org/permalink/t3tsref:confval-plugin-mvc-calldefaultactionifactioncantberesolved@main) **EXT:blog_example/Configuration/Sets/BlogExample/setup.typoscript** ```typoscript plugin.tx_blogexample { mvc { callDefaultActionIfActionCantBeResolved = 1 } } ``` #### Example: Show 404 (page not found) page if action cannot be resolved {#example-show-404-page-not-found-page-if-action-cannot-be-resolved} - **Demonstrates:** - [plugin.\[extension\].mvc.throwPageNotFoundExceptionIfActionCantBeResolved](https://docs.typo3.org/permalink/t3tsref:confval-plugin-mvc-throwpagenotfoundexceptionifactioncantberesolved@main) **EXT:blog_example/Configuration/Sets/BlogExample/setup.typoscript** ```typoscript plugin.tx_blogexample { mvc { throwPageNotFoundExceptionIfActionCantBeResolved = 1 } } ``` ### Plugin format examples {#plugin-format-examples} #### Example: Define alternative output formats for RSS feeds {#example-define-alternative-output-formats-for-rss-feeds} - **Demonstrates:** - [plugin.\[extension\].format](https://docs.typo3.org/permalink/t3tsref:confval-plugin-format@main) **EXT:blog_example/Configuration/Sets/BlogExample/setup.typoscript** ```typoscript plugin.tx_blogexample_rssfeedxml { // Use template List.xml format = xml } plugin.tx_blogexample_rssfeedatom { // Use template List.atom format = atom } ``` ### Plugin localization examples {#plugin-localization-examples} #### Example: Override a language key in an Extbase plugin {#example-override-a-language-key-in-an-extbase-plugin} - **Demonstrates:** - [plugin.\[extension\].\_LOCAL_LANG](https://docs.typo3.org/permalink/t3tsref:confval-plugin-local-lang@main) **EXT:site_package/Configuration/Sets/Main/setup.typoscript** ```typoscript plugin.tx_myextension_pi1._LOCAL_LANG.de.list_mode_1 = Der erste Modus ```