Styleguide dla TYPO3

Dlaczego Styleguide to najważniejsze rozszerzenie QA dla programistów szablonów TYPO3

Rozwój szablonów w TYPO3 ma systematyczny problem z jakością: programiści testują swoje szablony Fluid z danymi, które aktualnie istnieją na stronie. Ale elementy treści mają dziesiątki wariantów - nagłówki z podtytułem i bez, bloki tekstowe z 3 słowami lub 3 akapitami, obrazy w pionie i poziomie, tabele z 2 lub 20 kolumnami. Kto sprawdza tylko aktualną stronę, pomija skrajne przypadki, które ujawniają się dopiero po uruchomieniu.

Rozszerzenie Styleguide rozwiązuje ten problem, automatycznie zakładając demonstracyjne drzewo stron, które pokazuje każdy element treści Core na osobnej stronie. Dzięki temu programista od razu widzi, czy jego CSS i szablony prawidłowo obsługują wszystkie warianty.

Typowe scenariusze zastosowań

Rozwój szablonów przy projektach relaunch. Firma zleca relaunch TYPO3 z nowym Corporate Design. Programista frontend tworzy szablony Fluid dla wszystkich elementów treści. Bez Styleguide musi dla każdego elementu tworzyć dane testowe w backendzie - proces trwający godziny przy ponad 30 elementach. Styleguide automatycznie generuje wszystkie dane testowe: elementy tekstowe o różnych długościach, obrazy o różnych proporcjach, listy, tabele, formularze. Programista przechodzi przez strony demo i widzi każdy element we frontendzie.

Testy regresji po aktualizacjach TYPO3. Aktualizacja TYPO3 z v11 na v12 subtelnie zmienia renderowanie poszczególnych elementów treści. Element Textmedia nagle renderuje dodatkowy wrapper-div, który łamie layout CSS. Bez Styleguide to wychodzi dopiero, gdy redaktor zgłosi błąd na stronie live. Z Styleguide programista po aktualizacji od razu widzi, które elementy się zmieniły.

Uzgadnianie między zespołem projektowym a deweloperskim. Designerzy dostarczają makiety Figma dla 10 elementów treści. Ale jak wyglądają pozostałe 25 standardowych elementów w nowym designie? Styleguide czyni tę lukę widoczną.

Architektura techniczna

Styleguide to oficjalne rozszerzenie TYPO3 Core System Extension, które od v13 leży w repozytorium Core, ale nie należy do pakietu źródłowego. Instaluje się je przez Composer (typo3/cms-styleguide), do v12 także z TER, a następnie aktywuje. Rozszerzenie działa na dwóch poziomach: generator TCA tworzy rekordy testowe dla własnych tabel demonstracyjnych (tx_styleguide_*), które pokazują prawie wszystkie typy pól TCA backendu. Moduł backendowy pozwala administratorowi tworzyć i usuwać dane testowe. Osobne drzewo stron wyświetla wygenerowane elementy treści w layoucie frontendowym, po jednej stronie na typ treści.

Styleguide nie ma zewnętrznych zależności. Jako rozszerzenie Core jest automatycznie aktualizowane z każdą aktualizacją TYPO3 i zawsze kompatybilne z daną wersją.

Częste problemy i rozwiązania

Strona Styleguide wyświetla puste obszary. Dane testowe zostały wygenerowane, ale strona frontendowa nie pokazuje wszystkich elementów. Przyczyna: strony demo działają jako osobna witryna z własnym szablonem głównym zamiast szablonu strony lub brakuje konfiguracji TypoScript. Rozwiązanie: sprawdzenie w module backendowym, czy drzewo stron jest prawidłowo założone.

Brak obrazów w wygenerowanych danych testowych. Styleguide próbuje dołączyć obrazy testowe przez FAL. Styleguide dostarcza własne obrazy przykładowe i kopiuje je do magazynu o UID 1; jeśli go brakuje lub jest źle skonfigurowany, pola obrazów pozostają puste. Rozwiązanie: sprawdzenie magazynu fileadmin (UID 1) przed generowaniem danych testowych.

Problemy z wydajnością strony Styleguide. Zakładanie demonstracyjnych drzew stron tworzy naraz wiele rekordów i według dokumentacji trwa kilka sekund. Rozwiązanie: aktywacja Styleguide tylko na środowisku deweloperskim lub staging, nigdy na systemie live.

Migracja i kompatybilność wersji

Styleguide od TYPO3 v13 leży w repozytorium Core i ukazuje się z każdą wersją TYPO3. Do v12 miało własne numery wersji, ostatnio 12.0.5.

Przy aktualizacji TYPO3 dane testowe Styleguide powinny być wygenerowane na nowo. Stare dane testowe mogą być niespójne na nowym systemie, ponieważ definicje TCA zmieniają się między wersjami TYPO3.

Gosign integruje Styleguide w każdy relaunch TYPO3 jako stały element procesu QA. Strona Styleguide jest tworzona na środowisku staging jako permanentna referencja i służy zespołowi projektowemu jako URL akceptacji. Zmiany w szablonach Fluid lub CSS stają się tam natychmiast widoczne, bez konieczności tworzenia treści testowej na poszczególnych stronach.