Upgrade Guide

Mask tries to minimize breaking changes between each version. But sometimes small changes have to be done, which require actions to be performed.

From v8.0.x or lower

The persistence / matching of type Content fields has changed. It is necessary to run the upgrade wizard with the title Migrate Mask Content fields.

Command with TYPO3 CLI:

// composer mode
vendor/bin/typo3 upgrade:run migrateContentFields

// classic mode
typo3/sysext/core/bin/typo3 upgrade:run migrateContentFields

From v7.0.x or lower

To further streamline the Mask API, the options key has to be removed from the elements section in the json file. It was used to resolve field types, which didn't have enough information by their own (e.g. type richtext).

There is a compatibility layer in Mask v7 which will trigger a deprecation warning, if the field was migrated. This fallback will be removed in Mask v8.

Note

This only affects installations, which were originally created on TYPO3 v7 / Mask v2 (or lower).

Either use the Upgrade Wizard manually and run "Update Mask JSON file (RTE options)" or use cli commands. The Upgrade Wizard will only show up, if necessary.

Command with TYPO3 CLI:

./typo3/sysext/core/bin/typo3 upgrade:run moveRteOptions

Or with typo3_console:

./typo3cms upgrade:run moveRteOptions

From v6 or lower

When upgrading to v7 you might experience an error in the Mask module: The requested resource "/module/tools/MaskMask" was not found.. This can be fixed by clearing the browser cache (CTRL + F5). The error is caused by a changed way of how the module is registered.

From v5 or lower

richtextConfiguration has to be removed

Because of a changed loading order of the RTE configuration it is required to remove the richtextConfiguration entry from mask.json or else all of your RTE fields will have the TYPO3 default RTE config set.

New in version 6.2.0

Mask provides the UpgradeWizard RemoveRichtextConfiguration.php to remove all entries at once.

Important

This upgrade wizard is only available in Mask v6. The reason is that since v7 the richtext configuration can be edited in mask directly. If you are planning to update to v7, first update to v6, run the upgrade wizard and then continue updating to v7.

Command with TYPO3 CLI:

./typo3/sysext/core/bin/typo3 upgrade:run removeRichtextConfiguration

Or with typo3_console:

./typo3cms upgrade:run removeRichtextConfiguration

Another way is to go to the Upgrade module and open the Upgrade Wizard. There you will find Remove "richtextConfiguration" in mask.json. Click on Execute to start the upgrade.

From v3 or lower

New template name format

Since version v4 Mask is based on the FLUIDTEMPLATE content object. This requires all template files to be named in UpperCamelCase.

Before: my_element.html

After: MyElement.html

New in version 6.2.0

If you have a lot of templates you can rename them with the UpgradeWizard ConvertTemplatesToUppercase.php.

Command with TYPO3 CLI:

./typo3/sysext/core/bin/typo3 upgrade:run convertTemplatesToUppercase

Or with typo3_console:

./typo3cms upgrade:run convertTemplatesToUppercase

Another way is to go to the Upgrade module and open the Upgrade Wizard. There you will find Convert Mask templates to uppercase.. Click on Execute to start the upgrade.

From 3.1.0 or lower

New filename format for preview images

Remove the ce_ prefix from all content element preview images. Example: from ce_key.png to key.png

From TYPO3 v7 / Mask v2 or lower

New in version 7.1

TYPO3 v8 introduced a new language field l10n_source. While it provided an upgrade wizard for the tt_content table, other tables weren't updated. Mask now provides an UpgradeWizard, which updates its custom tables. Custom tables are created, if you use the inline field of Mask.

Either go to the Upgrade module and check for updates, or use it from the command line.

Command with TYPO3 CLI:

// composer mode
vendor/bin/typo3 upgrade:run fillTranslationSourceField

// classic mode
typo3/sysext/core/bin/typo3 upgrade:run fillTranslationSourceField