Mask dla TYPO3

Redaktorzy potrzebują własnych elementów treści, a nie kolejnych obejść z polami tekstowymi

Każda witryna TYPO3 dochodzi do punktu, w którym wbudowane elementy treści przestają wystarczać. Karuzela zespołu, tabela cenowa z przełącznikami, teaser produktu z obrazem, tekstem i przyciskiem CTA - takie wymagania lądują w edytorze RTE jako bałagan HTML albo w przepełnionym kontenerze Flexform. Mask rozwiązuje ten problem fundamentalnie: redaktorzy otrzymują własne maski backendowe z dokładnie takimi polami, jakich potrzebują. Bez klas PHP, bez ręcznego TCA, bez ext_tables.sql.

Mask od lat należy do najczęściej używanych frameworków do Custom Content Elements w TYPO3. Ponad 1,7 mln pobrań z Packagist (stan: wrzesień 2026) i wzmianka w oficjalnej dokumentacji TYPO3 obok Content Blocks i DCE potwierdzają jego popularność.

Typowe scenariusze zastosowań

Witryny korporacyjne ze złożonymi strukturami stron. Zespoły marketingowe potrzebują od 15 do 30 różnych elementów treści: banery hero, referencje, akordeony, zakładki, pliki do pobrania z miniaturą, karty kontaktowe. Mask odwzorowuje każdy z nich jako osobny formularz backendowy. Redaktorzy widzą tylko pola dotyczące danego elementu - żadnego zamieszania z powodu nieistotnych opcji.

Projekty wielojęzyczne z konsystentną strukturą. Elementy Mask w pełni wspierają mechanizmy tłumaczeniowe TYPO3. Pola można konfigurować jako l10n_mode exclude (nietłumaczalne) lub prefixLangTitle (tłumaczalne z podpowiedzią). W witrynach z ponad 5 językami oszczędza to czas redakcji, ponieważ struktura pozostaje identyczna - tłumaczony jest jedynie kontekst.

Projekty relaunch z istniejącymi danymi. Kto migruje ze starego systemu (WordPress, TYPO3 z Gridelements lub TemplaVoila), potrzebuje czystych struktur treści. Elementy Mask można eksportować jako samodzielne rozszerzenie za pomocą mask_export. Dzięki temu definicje treści stają się wersjonowalne i wdrażalne przez pipeline CI/CD.

Architektura techniczna

Mask przechowuje konfigurację wszystkich elementów treści w jednym pliku JSON (mask.json, domyślnie w Configuration/Mask/ w Site Package). Ten plik opisuje pola, typy, palety i przypisania do szablonów Fluid. Przy aktywacji lub aktualizacji Mask automatycznie generuje z niego niezbędne konfiguracje TCA i pola bazy danych.

Typy pól obejmują najczęstsze typy TYPO3: String, Integer, Float, RichText, Date, DateTime, File (FAL), Inline (IRRE do zagnieżdżonych struktur), Select, Checkbox, Radio, Link, Slug, Color Picker, Tab, Palette. Od Mask 7.1 tę konfigurację można też podzielić na jeden plik JSON na element.

Szablony Fluid znajdują się standardowo w Site Package w Resources/Private/Mask/Frontend/Templates lub w konfigurowalnej ścieżce. Każdy element treści ma własny szablon, opcjonalnie z Partials i Layouts. Mask rejestruje elementy w New Content Element Wizard, włącznie z ikoną i opisem.

Zależności są minimalne: Mask wymaga jedynie TYPO3 Core (v11, v12, v13 są aktywnie wspierane). Dla v12 i v13 żadne dodatkowe rozszerzenia nie są potrzebne, dla v11 Mask 8.x wymaga fontawesome_provider. Do workflow eksportowego dochodzi mask_export jako opcjonalne uzupełnienie.

Częste problemy i rozwiązania

Zmiany pól na systemach produkcyjnych. Gdy pole Mask zostanie zmienione na systemie staging (typ, nazwa pola), ale baza danych na produkcji nie zostanie zaktualizowana, pojawiają się błędy. Rozwiązanie: korzystać z mask_export, aby zmiany konfiguracji przechodzily przez Git i pipeline wdrożeniowe. Alternatywnie: Database Compare w Install Tool po każdym wdrożeniu.

Wydajność przy wielu elementach treści. Witryny z ponad 40 różnymi elementami Mask generują dużą konfigurację TCA. TYPO3 ładuje ją przy każdym wywołaniu backendu. Rozwiązanie: sensowne grupowanie elementów, dezaktywacja nieużywanych, utrzymywanie aktywnego cache backendu. Od Mask 7.1 Mask przetwarza konfigurację jako obiekty zamiast tablic, co jest znacznie szybsze.

Zagnieżdżone elementy (IRRE) i sortowanie. Relacje inline (np. slajdy slidera wewnątrz elementu slidera) przy kopiowaniu/wklejaniu czasem tracą kolejność. Rozwiązanie: jawne zdefiniowanie pola sortowania i zabezpieczenie w szablonie Fluid <f:for> za pomocą sortBy. Po każdej aktualizacji Mask warto krótko przetestować to zachowanie.

Migracja i kompatybilność wersji

Mask aktywnie wspiera TYPO3 v12 i v13. Aktualna stabilna wersja (Mask 9.x) działa na obu wydaniach LTS. TYPO3 v11 jest obsługiwane przez Mask 8.x, ale nie otrzymuje już nowych funkcji.

Dla projektów, które nadal korzystają z TemplaVoila lub DCE, Mask oferuje klarowną ścieżkę migracji. Elementy DCE można ręcznie przenieść do Mask: odtworzyć pola w GUI Mask, dostosować szablony Fluid, zmigrować dane przez skrypt SQL. Gosign przeprowadził ten proces w projektach z ponad 20 elementami DCE, szacując nakład na 2 do 5 dni w zależności od złożoności.

Dla TYPO3 v13 i v14 dostępne jest dodatkowo rozszerzenie Content Blocks (friendsoftypo3/content-blocks). Dla istniejących projektów Mask nie oznacza to pośpiechu: Mask i Content Blocks współistnieją bez problemów. Nowe projekty na TYPO3 v13 lub v14 mogą rozważyć, czy Content Blocks wystarczy, czy Mask dzięki swojemu GUI i workflow eksportowemu oferuje przewagę. Gosign doradza w każdym projekcie indywidualnie, które podejście generuje najmniejszy nakład utrzymania w perspektywie długoterminowej.

Często niedocenianym aspektem jest dokumentacja. Elementy Mask są zrozumiałe dla programistów (pola, typy, szablony), ale redaktorzy potrzebują wskazówek: Które pola są obowiązkowe? Jaki rozmiar obrazu jest optymalny? Co się stanie, gdy pole opisu pozostanie puste? Mask od wersji 7 wspiera teksty opisowe na pole, które pojawiają się w backendzie pod nazwą pola. Gosign dodatkowo tworzy wewnętrzny podręcznik redakcyjny dla każdego projektu, w którym każdy element Mask jest udokumentowany ze zrzutem ekranu, opisem pól i najlepszymi praktykami. Nakład to pół godziny na element, ale oszczędza pytania zwrotne w trakcie eksploatacji.

Do początkowej konfiguracji projektu Mask z 15 do 20 elementami treści Gosign kalkuluje 3 do 5 dni deweloperskich, włącznie z szablonami Fluid, podglądem backendowym i konfiguracją mask_export. Pojedyncze nowe elementy w trakcie eksploatacji realizowane są w 1 do 4 godzin, w zależności od złożoności zagnieżdżenia i projektu szablonu.