#MaskToContentBlocks

[t-3-planet]

Migrating from Mask to Content Blocks in TYPO3 – A Step Toward a Future-Proof System

For many TYPO3 users, the Mask extension has been a convenient way to create custom content elements without deep coding knowledge. However, TYPO3’s core development is shifting towards a more structured and future-proof solution—Content Blocks.

Migrating from Mask to Content Blocks is not just a recommendation but a necessary step to ensure long-term compatibility, maintainability, and performance in TYPO3 projects. This guide will walk you through why and how to transition smoothly.

Why Should You Migrate?

Mask has been widely used, but it has limitations when it comes to TYPO3’s evolving ecosystem. Here’s why Content Blocks are the better choice:

✅ TYPO3 Core Integration – Content Blocks are becoming the TYPO3 standard and will likely be integrated into future TYPO3 versions. ✅ Improved Maintainability – A structured file system makes it easier to manage, update, and customize content elements. ✅ Better Compatibility – Ensures your custom elements remain functional with upcoming TYPO3 releases. ✅ Version Control Friendly – Since Content Blocks are stored within your site extension, they can be easily tracked in Git.

If you plan to upgrade your TYPO3 website or ensure long-term stability, now is the perfect time to migrate!

How to Migrate from Mask to Content Blocks?

There are two ways to migrate: 🔹 Automatic Migration – Ideal for a quick, bulk transition. 🔹 Manual Migration – Recommended for highly customized content elements.

Automatic Migration (Best for Quick Transition)

For those with multiple Mask elements, an automatic migration tool makes the process easy.

Prerequisites:

Your TYPO3 installation should be version 13 or higher.

Ensure you have a backup of your site before making changes.

Your setup should be Composer-based for easier extension management.

Steps to Automatically Migrate:

1️⃣ Install the required extensions:

composer require friendsoftypo3/content-blocks composer require nhovratov/mask-to-content-blocks

2️⃣ Run the migration command:

bin/typo3 mask-to-content-blocks:migrate

3️⃣ Remove Mask and the migration tool:

composer remove mask/mask nhovratov/mask-to-content-blocks

4️⃣ Test & Validate: Open your TYPO3 backend and confirm that all migrated elements work correctly.

Manual Migration (For More Control)

If you have complex Mask elements with custom logic, you might prefer manual migration.

Steps to Manually Migrate:

1️⃣ Install the Content Blocks extension:

composer require friendsoftypo3/content-blocks

2️⃣ Create a new Content Block for each Mask element:

bin/typo3 content-blocks:make your_theme/element_name

3️⃣ Transfer CType & Field Names Ensure that the CType and field structure in Content Blocks match your existing Mask elements.

4️⃣ Move Templates & Configurations Copy your existing Fluid templates and TypoScript settings from Mask to the new Content Blocks folder.

5️⃣ Test & Debug After migration, thoroughly test the elements in the backend and frontend.

Final Thoughts

Migrating from Mask to Content Blocks might seem like a big step, but it ensures that your TYPO3 site remains future-proof, structured, and easier to manage. Whether you choose automatic or manual migration, this transition will benefit your TYPO3 project in the long run.