Dlaczego domyślne widgety w Magento 2 to koszmar dla marketingu?
Domyślnie Magento 2 traktuje parametry widgetów po macoszemu. Jeśli tworzysz dedykowany moduł z własnym widgetem CMS — na przykład sliderem, siatką banerów promocyjnych, sekcją korzyści czy blokiem z referencjami — silnik e-commerce daje Ci do dyspozycji niemal wyłącznie jednolinijkowe pole tekstowe (text) oraz proste listy rozwijane (select). W praktyce oznacza to, że redaktor treści lub marketer, chcąc wstawić sformatowany opis czy wybrać zdjęcie do baneru, musi ręcznie wklejać surowy kod HTML albo wpisywać bezwzględne ścieżki do plików, takie jak wysiwyg/homepage/banner-lato.jpg. Nasz moduł Widget Parameters rozwiązuje ten problem raz na zawsze, przywracając cywilizowane standardy do panelu administracyjnego.
Ręczne wpisywanie ścieżek i znaczników w małym polu tekstowym bez podglądu to prosty przepis na awarię produkcyjną. Wystarczy jedna literówka w adresie URL, niezamknięty tag <div> albo cudzysłów wklejony z edytora tekstu w formacie typographicznym, aby rozjechać układ strony głównej lub uniemożliwić jej wyrenderowanie. Co gorsza, osoba zarządzająca treścią nie ma żadnego podglądu wybranego pliku z poziomu biblioteki mediów Adobe Commerce / Magento, co wymusza żonglowanie kartami w przeglądarce i manualne kopiowanie nazw plików.
Jakie nowe typy parametrów powinny znaleźć się w każdym wdrożeniu?
Zamiast zmuszać zespół contentowy do nauki składni HTML i zgadywania adresów grafik, panel administracyjny powinien udostępniać dokładnie takie same komponenty interfejsu, jakie znamy z edycji standardowych stron CMS czy bloków statycznych. W realnych wdrożeniach e-commerce kluczowe są trzy typy kontrolek:
- Pełny edytor WYSIWYG (TinyMCE) – pozwala redagować sformatowany tekst (nagłówki, listy punktowane, pogrubienia, linki) bezpośrednio w oknie modalnym konfiguracji widgetu, z zachowaniem reguł typograficznych i czyszczeniem stylów wklejanych z zewnętrznych źródeł.
- Pole wielowierszowe (Textarea) – idealne na czysty tekst bez formatowania, zajawki artykułów, surowe fragmenty konfiguracji JSON, kody śledzące czy wieloliniowe cytaty, gdzie pole jednolinijkowe staje się zupełnie nieczytelne.
- Przeglądarka i selektor mediów (Image Chooser) – natywny przycisk wywołujący standardowe drzewo katalogów Magento Media Gallery. Pozwala wybrać istniejący plik, wgrać nowy obraz bezpośrednio z dysku, podejrzeć miniaturę i automatycznie zapisać poprawny względny identyfikator zasobu.
Jak skonfigurować własne pola w pliku widget.xml?
Architektura widgetów w Magento 2 opiera się na plikach konfiguracyjnych etc/widget.xml wewnątrz Twojego modułu. Standardowo definiuje się w nich węzły <parameter>. Aby skorzystać z rozszerzonych typów kontrolek, zamiast atrybutu xsi:type="text" wskazujemy dedykowaną klasę renderującą blok administracyjny.
Oto praktyczny przykład pliku widget.xml, który definiuje komponent baneru promocyjnego wyposażony w nagłówek, edytor wizualny oraz selektor grafiki z galerii:
<?xml version="1.0" encoding="UTF-8"?>
<widgets xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Widget:etc/widget.xsd">
<widget id="custom_promo_banner" class="Vendor\Module\Block\Widget\PromoBanner">
<label translate="true">Baner Promocyjny (Rozszerzony)</label>
<description translate="true">Sekcja banerowa z edytorem wizualnym i wyborem grafiki</description>
<parameters>
<parameter name="banner_title" xsi:type="text" visible="true" required="true" sort_order="10">
<label translate="true">Tytuł sekcji</label>
</parameter>
<parameter name="banner_content" xsi:type="block" visible="true" required="false" sort_order="20">
<label translate="true">Treść promocyjna (WYSIWYG)</label>
<block class="Dmatthew\WidgetParameters\Block\Adminhtml\Widget\Type\Wysiwyg"/>
</parameter>
<parameter name="banner_image" xsi:type="block" visible="true" required="true" sort_order="30">
<label translate="true">Obraz tła</label>
<block class="Dmatthew\WidgetParameters\Block\Adminhtml\Widget\Type\Image"/>
</parameter>
<parameter name="extra_notes" xsi:type="block" visible="true" required="false" sort_order="40">
<label translate="true">Dodatkowe uwagi (Textarea)</label>
<block class="Dmatthew\WidgetParameters\Block\Adminhtml\Widget\Type\Textarea"/>
</parameter>
</parameters>
</widget>
</widgets>Wewnątrz szablonu .phtml odbierasz te dane dokładnie tak samo, jak w przypadku każdego innego parametru widgetu — poprzez metody gettera (np. $block->getData('banner_content') lub $block->getData('banner_image')). W przypadku pola graficznego moduł zwraca ścieżkę zapisaną w strukturze katalogu pub/media, którą możesz przekazać bezpośrednio do helpera renderującego responsywne tagi <picture> czy formaty WebP/AVIF.
Co stało się z oryginalnym modułem dmatthew i dlaczego powstał fork SISL?
Przez lata nieoficjalnym standardem w społeczności Magento 2 dla tego typu zadań był moduł stworzony przez Matthew Beane'a (dmatthew/magento2-widget-parameters). Było to lekkie, eleganckie rozszerzenie, które robiło dokładnie to, co do niego należało — bez zbędnego narzutu i bez ingerencji w tabele bazy danych.
Niestety, oryginalne repozytorium zostało oficjalnie zarchiwizowane przez autora w 2022 roku. Projekt przestał otrzymywać jakiekolwiek aktualizacje, brakowało w nim przypięcia wersji frameworka, a pojawienie się rygorystycznych typowań w PHP 8.1, 8.2, a wkrótce 8.3 i 8.4 doprowadziło do problemów z kompatybilnością w nowszych wersjach Magento (od 2.4.6 wzwyż).
Jako studio wdrażające i utrzymujące sklepy oparte o Magento 2 w nowoczesnych stosach technologicznych, nie mogliśmy pozwolić sobie na porzucenie tak wygodnego narzędzia ani na korzystanie z przestarzałego kodu generującego błędy deprecation czy konflikty z kompilatorem DI. Z tego powodu zespół SISL przejął pieczę nad kodem, tworząc i aktywnie utrzymując publiczny fork zgodny z Magento 2.4.7, 2.4.8 oraz nadchodzącym 2.4.9 na środowiskach PHP 8.3 i 8.4. Kod jest w pełni otwarty i dostępny w naszym repozytorium GitHub: https://github.com/SISL-source/magento2-widget-parameters.
Jak zainstalować moduł krok po kroku w projekcie Magento?
Instalacja w środowisku developerskim lub produkcyjnym opartym o Composer sprowadza się do wskazania naszego repozytorium VCS oraz pobrania pakietu. Nie musisz modyfikować przestrzeni nazw w istniejących plikach widget.xml — zachowaliśmy oryginalne nazewnictwo klas (Dmatthew\WidgetParameters), dzięki czemu migracja ze starego, porzuconego modułu jest bezdotykowa.
W terminalu głównym Twojego projektu wykonaj następujące polecenia:
composer config repositories.sisl-widget-parameters vcs https://github.com/SISL-source/magento2-widget-parameters
composer require dmatthew/magento2-widget-parameters:dev-main
bin/magento module:enable Dmatthew_WidgetParameters && bin/magento setup:upgradePo zrealizowaniu aktualizacji schematu i wyczyszczeniu pamięci podręcznej (bin/magento cache:flush), nowe typy bloków będą natychmiast dostępne dla każdego widgetu zdefiniowanego w Twoim motywie lub modułach dedykowanych. W środowisku produkcyjnym pamiętaj o standardowym wykonaniu bin/magento setup:di:compile oraz bin/magento setup:static-content:deploy.
Kiedy warto napisać własny widget zamiast polegać na Page Builderze?
Wielu właścicieli sklepów i początkujących deweloperów zakłada, że wbudowany w Magento Page Builder eliminuje potrzebę tworzenia własnych widgetów. To pułapka. Page Builder świetnie sprawdza się na stronach lądowania (landing pages) czy w artykułach blogowych, gdzie układ jest unikalny i dynamicznie się zmienia. Jednak w przypadku powtarzalnych elementów strukturalnych strony głównej, stałych boksów produktowych czy zaawansowanych sekcji z filtrami, Page Builder generuje potężny narzut DOM, dziesiątki zagnieżdżonych kontenerów i utrudnia zachowanie spójnego design systemu.
Dedykowany widget z parametrami WYSIWYG i Image Chooser daje Ci:
- Perfekcyjny kod HTML – semantyczny, czysty markup zoptymalizowany pod Core Web Vitals i Lighthouse, bez zbędnych stylów inline.
- Bezpieczeństwo spójności wizualnej – redaktor decyduje wyłącznie o treści i zdjęciach, natomiast układ, marginesy, zachowanie na mobile i animacje pozostają pod ścisłą kontrolą stylów motywu.
- Szybkość edycji – formularz widgetu otwiera się natychmiast, a pola są dokładnie dostosowane do logiki biznesowej danego komponentu.
Jeśli planujesz uporządkować architekturę frontendu w swoim sklepie, potrzebujesz audytu wydajności lub szukasz zespołu, który realnie programuje Magento bez zbędnego narzutu agencji korporacyjnych — napisz do nas. Przeanalizujemy Twój projekt i dobierzemy rozwiązania, które działają stabilnie przez lata.