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 jest od 2016 roku najczęściej używanym frameworkiem do Custom Content Elements w TYPO3. Ponad 1500 aktywnych instalacji (stan: packagist, kwiecień 2026) i włączenie do oficjalnej dokumentacji TYPO3 jako rekomendowany sposób tworzenia indywidualnych elementów treści potwierdzają status de facto standardu.

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 lub config/mask.json od Mask 8). 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ą pełny standard 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 8 dochodzą pola natywne JSON i ulepszone API.

Szablony Fluid znajdują się standardowo w fileadmin/templates/mask/ 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). Żadne dodatkowe rozszerzenia nie są potrzebne. 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 8 generowanie TCA jest znacznie wydajniejsze niż w poprzednich wersjach.

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. W Mask 8.x to zachowanie jest stabilniejsze niż w 7.x.

Migracja i kompatybilność wersji

Mask aktywnie wspiera TYPO3 v12 i v13. Aktualna stabilna wersja (Mask 8.x) działa na obu wydaniach LTS. TYPO3 v11 jest obsługiwane przez Mask 7.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.

Od TYPO3 v13 dostępne jest dodatkowo natywne Content Block API. Dla istniejących projektów Mask nie oznacza to pośpiechu: Mask i Content Blocks współistnieją bez problemów. Nowe projekty na czystym TYPO3 v13 mogą rozważyć, czy natywne podejście 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 jako tooltip. 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.