Czy kiedykolwiek znalazłeś się w sytuacji, w której chcesz dodać własne ustawienia do bloków Gutenberga w WordPressie? W tym poście omówimy szczegółowo, jak to zrobić. Znajdziesz dwa przykładowe kody rzeczywistych przypadków dodawania niestandardowych ustawień do bloków WordPressa.

Pamiętaj, że ponieważ bloki Gutenberga są JavaScriptem, ich modyfikacja wymaga napisania kodu w JavaScript. Tak jak kod PHP WordPressa ma haki i filtry, które pozwalają twórcom motywów lub wtyczek modyfikować jego kod, tak samo istnieją filtry w kodzie JavaScript WordPressa. Podobnie jak w przypadku PHP [add_filter](https://developer.wordpress.org/reference/functions/add_filter/)()mamy funkcję Javascript [addFilter](https://developer.wordpress.org/block-editor/packages/packages-hooks/#api-usage)().

Napiszę kod w składni Javascript ES6, która wymaga kompilatora do jego przekształcenia. Możesz pisać w składni ES5, ale polecam ES6/ESNext. Mam post, który wyjaśnia, jak skonfigurować transformator dla ES6/ESNext. Zakładam również, że masz pewną znajomość React/JSX, być może pewne doświadczenie w tworzeniu własnych niestandardowych bloków Gutenberga.

Co możesz filtrować na blokach Gutenberga

Nie ma całej dokumentacji w dostępnych hookach i filtrach Gutenberga. Ale w celu dodania niestandardowych ustawień i zastosowania ich w istniejących blokach; to właśnie znalazłem do tej pory. Skupiłem się na dodawaniu prostych ustawień – a nie na operacjach, które wymagają drastycznych zmian komponentów lub złożonego zachowania.

Istnieją trzy kroki, aby dodać niestandardowe ustawienia do istniejących bloków:

Dodajemy filtr do [registerBlockType](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/#registerblocktype)tablicy ustawień istniejącego bloku. To pozwala nam dodawać nowe atrybuty do attributestablicy, co pozwala nam na zapisanie dodatkowych informacji w bloku. Musimy gdzieś zapisać nasze niestandardowe ustawienie.
Zaczep się do editkomponentu bloku (komponentu odpowiedzialnego za renderowanie bloku w edytorze). W tym haczyku możemy podpiąć się pod Inspektora (pasek boczny) i dodać własne komponenty. Możemy albo dodać nową sekcję/panel, albo podpiąć się pod sekcję „Zaawansowane", która jest zawsze obecna we wszystkich blokach. Następnie od nas zależy wyrenderowanie danych wejściowych ustawień, takich jak wprowadzanie tekstu, pola wyboru lub cokolwiek innego.
saveFiltruj rekwizyty bloku. Możemy dostosować props do zapisu, który odpowiada zarówno za zapisanie bloku, jak i renderowanie go w interfejsie użytkownika (poza edytorem). W naszym przypadku chcemy dodać klasę lub styl inline.

Możemy celować w określone bloki lub wszystkie. Zawsze mamy dostęp do tego, w jakim bloku się znajdujemy.

Innymi słowy: dodajemy kilka niestandardowych ustawień w Inspektorze i zapisujemy je w niestandardowych atrybutach, które dodaliśmy do bloku. Możemy wtedy wpłynąć na nazwę klasy bloku lub styl inline (w niektórych przypadkach), w zależności od zapisanych atrybutów. Dzięki niestandardowym nazwom klas możemy łatwo dodać niestandardowe CSS, który wizualnie nadaje efekt naszym ustawieniom.

Czego nie możemy zrobić (na razie?)

Niestety są pewne rzeczy, do których nie możemy uzyskać dostępu za pomocą filtrów w istniejących blokach. Jeśli chodzi o dodawanie prostych niestandardowych ustawień do bloków, są to typowe rzeczy, na które nie mamy wpływu.

Brak dostępu do stylu wbudowanego bloku w edytorze

W niektórych przypadkach ustawienia, które wpływają na projekt bloku, musimy dodać styl wbudowany w węźle zawijania bloku. Tylko nazwa klasy nie wystarczy. Na przykład, jeśli dodasz niestandardowe ustawienie koloru, a użytkownik wybierze niestandardowy kolor (z próbnika kolorów), nie możesz rozwiązać tego problemu, dodając klasę – potrzebujesz stylu wbudowanego.

Niestety wygląda na to, że domyślne bloki WordPressa obsługują styl inline w edytorze całkowicie niezależnie, bez opcji filtrowania lub „podpinania się”. W ostatnim przykładzie poniżej pokażę sposób na obejście tego problemu, ale nie we wszystkich przypadkach jest to idealne.

Możesz zapytać, dlaczego blok wygląda inaczej w edytorze niż w interfejsie? Celem Gutenberga jest zaimplementowanie wizualnego sposobu edycji treści, w której to, co widzimy, jest faktycznie tym, co otrzymujemy. Chcemy osiągnąć ten sam wygląd wizualny zarówno w edytorze, jak i frontendzie.

Niektóre bloki nie zawierają nazwy klasy w edytorze

Jak wspomniano powyżej, możemy filtrować nazwę klasy opakowania bloku, ponieważ jest to właściwość przekazywana do wszystkich bloków Gutenberga. Niestety, istnieją pewne bloki, które w ogóle nie stosują klasy bloku w programie edit. Jednym z przykładów jest blok Cover. Dużo się bawiłem, używając bloków okładki jako „sekcji” na pierwszych stronach i ciągle napotykam problemy, ponieważ blok okładki buduje własną klasę wewnątrz edit. Całkowicie pomija klasę „global” bloku (do której mamy dostęp poprzez filtry).

Ale przynajmniej możemy być pewni, że filtrowane nazwy klas są zawsze stosowane w save(frontendzie). Dzieje się to automatycznie poza określonym kodem każdego bloku.

Jeśli się mylę co do któregokolwiek z powyższych, PROSZĘ daj mi znać w komentarzach poniżej! Nieustannie uczę się Gutenberga, a jednocześnie Gutenberg również ewoluuje. Mam nadzieję, że w którymś momencie powyższe będzie możliwe lub że jest możliwe, ale brakuje mi tylko kilku istotnych informacji!

Pomijając to, zacznijmy szukać kodu.

Przykład 1: Dodaj pole przełączania, aby ukryć blok okładki na urządzeniu mobilnym

Załóżmy, że opracowujemy motyw, w którym bloki okładki będą używane jako „sekcje” na pierwszej stronie. I chcemy zapewnić użytkownikowi możliwość ukrycia określonej sekcji przed telefonem komórkowym. Aby rozwiązać ten problem, możemy dodać pole przełączania w sekcji „Zaawansowane” w Inspektorze bloku okładki. Jeśli pole jest włączone, blok Cover otrzyma dodatkową niestandardową klasę, do której możemy kierować zapytaniami CSS i mediami.

Przy okazji: jest to przypadek, w którym kwestia Cover block niestosująca naszych niestandardowych nazw klas w edytorze faktycznie jest zaletą! Wyobraź sobie, że tak; wtedy użytkownik nie będzie mógł edytować bloku w edytorze, jeśli ma mały ekran!

Jak wspomniano wcześniej, musimy kodować trzy kroki. Musimy również dodać trochę PHP, aby umieścić nasz plik JavaScript w kolejce do edytora. Zróbmy to najpierw.

Dodanie naszego skryptu do edytora

Podłączamy funkcję do akcji [enqueue_block_editor_assets](https://developer.wordpress.org/reference/hooks/enqueue_block_editor_assets/). Wewnątrz naszej funkcji umieszczamy w kolejce skrypt, tak jak zwykle robimy to w wp_enqueue_scriptshooku.


add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script('awp-gutenberg-filters', get_template_directory_uri(). '/assets/js/gutenberg-filters.js', ['wp-edit-post']);
});

Pamiętaj, aby dostosować ścieżkę do miejsca, w którym znajduje się Twój skrypt! Uwaga: Jeśli piszesz w ES6 z webpackiem kompilującym Twój Javascript, pamiętaj, aby ustawić ścieżkę do kompilacji skryptu, a nie źródło.

Lubię dodawać „ wp-edit-post” jako zależność do skryptu, aby upewnić się, że ładuje się wystarczająco późno.

To wszystko, co musimy zrobić w PHP. Reszta jest napisana w naszym pliku JavaScript.

Dodaj niestandardowy atrybut

Pierwszym filtrem, którego użyjemy, jest obiekt ustawień blocks.registerBlockTypefiltrów .registerBlockType

Ale najpierw trochę o dodawaniu filtrów w JavaScript. Ponieważ nie znalazłem żadnej dobrej dokumentacji na ten temat, wyjaśnię to nieco tutaj. Funkcja addFilterznajduje się w wp.hooksprzestrzeni nazw i akceptuje cztery argumenty.

addFilter('hookName', 'namespace', 'functionName', 'priority');

Pierwszy parametr, ‘hookName’, to nazwa filtra, do którego chcemy się podłączyć. Jest to odpowiednik pierwszego parametru używanego w PHP add_filter(). Drugi parametr, „namespace”, to niestandardowa nazwa w przestrzeni nazw dla Twojego kodu. Ma to na celu uniknięcie kolizji nazw. Możesz tutaj ustawić wszystko, co chcesz, po prostu nie używaj przestrzeni nazw WordPress (‘wp’). Użyj krótkiej formy swojego imienia lub nazwy projektu. Trzeci parametr, ‘functionName’, to przechwycona funkcja – która jest taka sama, jak add_filter()drugi argument PHP. I wreszcie czwarty parametr, „priorytet”, jest opcjonalny. Znowu jest to to samo, co add_filter()trzeci argument PHP.

Proces filtrów w JavaScript jest taki sam jak w PHP. Definiujemy funkcję, która musi zwrócić przefiltrowaną zmienną. Czasami zmienna jest napisem, obiektem lub komponentem. Wewnątrz funkcji modyfikujemy zmienną według własnego uznania.

W naszym przypadku chcemy dodać nowy atrybut do attributeobiektu bloku. Wywołamy nowy atrybut hideOnMobilei ustawimy jego typ na boolean. Odbywa się to tak:


function addCoverAttribute(settings, name) {
    if (typeof settings.attributes !== 'undefined') {
        if (name == 'core/cover') {
            settings.attributes = Object.assign(settings.attributes, {
                hideOnMobile: {
                    type: 'boolean',
                }
            });
        }
    }
    return settings;
}
 
wp.hooks.addFilter(
    'blocks.registerBlockType',
    'awp/cover-custom-attribute',
    addCoverAttribute
);

W wierszu #3upewniamy się, że kierujemy tylko bloki typu „ core/cover“. Drugim argumentem do blocks.registerBlockTypefiltrowania dogodnie jest nazwa bloku. Następnie dodajemy nowy element obiektu do settings.attributesobiektu. Na koniec upewniamy się, że zwracamy przefiltrowaną zmienną settings.

W tym momencie wizualnie nic się nie zmienia w Gutenbergu. Ale wszystkie bloki Cover mają teraz dodatkowy atrybut, którego możemy użyć do przechowywania naszych ustawień.

Dodaj ustawienie do Inspektora (panel Zaawansowane)

Drugi filtr jest wywoływany editor.BlockEditi filtruje składnik bloku edit. Ten filtr otrzymuje składnik oryginalnego bloku BlockEditi zwraca nowy opakowany składnik. Musimy użyć wp.compose.createHigherOrderComponent, aby zwrócić opakowany komponent.

Wewnątrz naszego komponentu upewniamy się, że renderujemy opakowany komponent BlockEditniezależnie od tego. Ale jeśli blok jest typu Cover, również podpinamy się pod komponent InspectorAdvancedControls(który jest panelem „Zaawansowane” w Inspektorze) i dodajemy ToggleControl. Piszemy, ToggleControlaby pokazać wartość i zaktualizować atrybut niestandardowy, który dodaliśmy wcześniej, hideOnMobile.

Nie zapomnij zawsze zwrócić oryginału BlockEdit, co robimy w kolejce #9. W linii #10 sprawdzamy, czy typem bloku jest Cover i renderujemy InspectorAdvancedControlskomponent. Wewnątrz dodajemy a ToggleControl, który jest kontrolką wejściową, która wyświetla się jako przełączanie między prawdą a fałszem. Ustawiamy etykietę i łączymy jej wartość z hideOnMobileatrybutem. Jeśli wcześniej dodałeś ustawienia do Inspektora, powinno to być dla Ciebie całkiem proste.

W powyższym kodzie powinniśmy teraz umieścić to w panelu „Zaawansowane” w blokach Inspektora okładki:

Dane wejściowe zaktualizują teraz nasz niestandardowy atrybut hideOnMobile. Ostatnim krokiem jest zrobienie czegoś w zależności od wartości tego atrybutu. W tej chwili atrybut jest zapisany, ale w rzeczywistości na nic nie wpływa.

Dodaj niestandardową klasę

Ostatnim krokiem jest dodanie własnej klasy do klasy bloku. Robimy to z filtrem blocks.getSaveContent.extraProps. Ten filtr wpływa na właściwości savekomponentu bloku. Jednym z nich jest prop className, który zawsze będzie stosowany do frontendu. Po prostu dołączamy po niej naszą niestandardową klasę, jeśli atrybut był true, a następnie zwracamy ją. Postanowiłem dodać klasę „ hide-on-mobile“, ale możesz ją nazwać, jak chcesz.

Ten kod jest dość oczywisty. W linii #4sprawdzamy czy atrybut hideOnMobileistnieje i czy jest true. Jeśli tak, dołączamy do ciągu niestandardową klasę className.

Dzięki wszystkim powyższym trzem filtrom powinniśmy teraz uzyskać niestandardową klasę „ukryj na urządzeniu mobilnym” zastosowaną do naszego bloku Cover za każdym razem, gdy ustawienie jest włączone.

Pozostaje tylko dodać trochę CSS do arkusza stylów frontendu twojego motywu. Coś takiego;


.wp-block-cover.hide-on-mobile { display: none; }
@media (min-width: 480px) {
    .wp-block-cover.hide-on-mobile { display: block; }
}

Przykład 2: Dodaj panel Inspektora z niestandardowym ustawieniem koloru tła dla bloku dystansowego

W drugim przypadku chcemy dodać niestandardowe ustawienia kolorów do bloku Spacer. Domyślnie blok dystansowy nie ma innych ustawień poza jego wysokością. Załóżmy, że chcemy dodać kolor tła, który pokoloruje pełną wysokość bloku Spacer. Dzięki temu użytkownik może dodawać puste, kolorowe „paski” w treści. W tym przypadku chcemy dodać ustawienia kolorów do osobnego panelu w Inspektorze, zgodnie ze zwykłym oczekiwanym zachowaniem ustawień kolorów.

Uwaga: Obsługa kolorów jest nieco bardziej skomplikowana, ponieważ musimy użyć (innego) komponentu wyższego rzędu withColors. Ponieważ już musimy zaimplementować komponent wyższego rzędu w editor.BlockEditpotrzebujemy composewielu komponentów. Dodatkowo musimy dodać dwa atrybuty dla każdego ustawienia koloru. Jeden będzie zawierał slug palety kolorów, a drugi będzie zawierał szesnastkowy kod koloru – tylko wtedy, gdy użytkownik wybrał niestandardowy kolor (użył selektora kolorów). To typowe zachowanie podczas pracy z programem withColors. Mam <a href="https://wordpress.mediadoma.com/pl/jak-dodac-ustawienia-kolorow-do-niestandardowego-bloku-gutenberga/" title="post wyjaśniający dodawanie ustawień kolorów i withColorsszczegółowo” >post wyjaśniający dodawanie ustawień kolorów i withColorsszczegółowo, jeśli się pomylisz.

Po drugie, w tym przypadku napotkamy problem wyjaśniony powyżej; gdzie nie możemy dodać odpowiedniego stylu wbudowanego do edytora. Rozwiązaniem, na które zdecydowałem się w tym przypadku, jest zawinięcie bloku Spacer wewnątrz a divw edytorze i zastosowanie odpowiednich klas i stylu inline do wrapping div. Dzięki temu wybrany kolor jest widoczny w edytorze, gdy blok jest odznaczony. Jednak po wybraniu bloku WordPress dodaje do niego własne niestandardowe jasnoszare tło, obejmujące nasz niestandardowy kolor tła. Jeden CSS do edytora naprawi to. Więcej wyjaśnię na końcu.

Kroki są takie same jak w powyższym przykładzie. Najpierw umieszczamy nasz skrypt w kolejce do edytora w PHP. Następnie w JavaScript filtrujemy attributesobiekt, editskładnik Spacera i na końcu składnik Spacera save.

Dodanie naszego skryptu do edytora


add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script('awp-gutenberg-filters', get_template_directory_uri(). '/assets/js/gutenberg-filters.js', ['wp-edit-post']);
});

Pamiętaj, aby dostosować ścieżkę do swojego skryptu. Lubię dodawać „ wp-edit-post” jako zależność do skryptu, aby upewnić się, że ładuje się wystarczająco późno.

To wszystko, co musimy zrobić w PHP. Reszta jest napisana w naszym pliku JavaScript.

Dodaj niestandardowe atrybuty

Podobnie jak w powyższym przykładzie dodajemy filtr blocks.registerBlockType, aby dodać dodatkowe elementy obiektu do obiektu bloku attributes.

Podczas pracy z withColorskażdym kolorem musimy dodać dwa atrybuty. Nazwa naszego atrybutu koloru tła to backgroundColor, co oznacza, że drugi atrybut musi być nazwany customBackgroundColor. To wszystko zostało wyjaśnione w moim poście dotyczącym obsługi ustawień kolorów w Gutenbergu. Oba powinny być typu string i stosowane tylko do bloków typu Spacer.


function addSpacerAttributes(settings, name) {
    if (typeof settings.attributes !== 'undefined') {
        if (name == 'core/spacer') {
            settings.attributes = Object.assign(settings.attributes, {
                backgroundColor: {
                    type: 'string',
                },
                customBackgroundColor: {
                    type: 'string'
                }
            });
        }
    }
    return settings;
}
 
wp.hooks.addFilter(
    'blocks.registerBlockType',
    'awp/spacer-background-attribute',
    addSpacerAttributes
);

Dodaj panel ColorSettings do Inspektora

Drugim krokiem jest dodanie panelu ustawień kolorów do Inspektora bloku Spacer poprzez filtrowanie editor.BlockEdit.

Musimy użyć composedo połączenia składnika wyższego rzędu zwróconego przez ten filtr i withColors. Innymi słowy, po prostu zawijamy zwrócony komponent w withColors. Jako parametr withColorspodajemy nasz atrybut backgroundColor.

Wewnątrz owiniętego komponentu upewniamy się, że zawsze wracamy BlockEdit(linia #9i #39klocki Spacer). W przypadku bloku typu Spacer zaczepiamy się również, InspectorControlsaby dodać PanelColorSettingswybrany przez nas kolor. Jest to standardowa procedura dodawania ustawień kolorów.

W linii #17 - 34ręcznie generujemy niezbędną klasę i/lub styl inline. Następnie w linii #38dodajemy otaczający div BlockEditz tymi klasami i stylami wbudowanymi.

Rezultatem jest nowy panel ustawień kolorów w blokach Inspector for Spacer, w pełni funkcjonalny.

Wybór koloru palety lub koloru niestandardowego będzie rzeczywiście miał wpływ na zawijania div wewnątrz edytora. Ale możesz to zobaczyć tylko wtedy, gdy odznaczysz blok Spacer!

Dzieje się tak, ponieważ WordPress stosuje własny styl podczas wybierania bloku odstępnika. Naprawimy to na końcu, najpierw musimy tylko zastosować tę samą klasę i/lub styl inline również we frontendzie.

Dodaj niestandardową klasę i styl wbudowany, aby zapisać

Na koniec musimy przefiltrować blocks.getSaveContent.extraPropsi zastosować niezbędną klasę i/lub styl inline dla frontendu. Znowu jest to bardzo podobne do tego, co zrobiliśmy w przykładzie 1 powyżej. Jeśli wybrano kolor palety, musimy dodać nazwę klasy, która jest zgodna ze standardami WordPress dotyczącymi ustawień kolorów („ has-<PALETTESLUG>-background-color“). Jeśli wybrano kolor niestandardowy, musimy dodać styl wbudowany z kolorem szesnastkowym.

Uwaga: Jeśli często potrzebujesz obsługiwać nazwy klas, polecam zaimportować classnamesbibliotekę. Jest to często wykorzystywane w Gutenbergu, ponieważ znacznie upraszcza ustawianie właściwych nazw klas. Poniższy kod zakłada, że tego nie zrobiłeś i tworzysz nazwę klasy ręcznie.


function applySpacerBackground(props, blockType, attributes) {
    if (blockType.name == 'core/spacer') {
        const { backgroundColor, customBackgroundColor } = attributes;
 
        // For improved class name handling, use classnames library. Or do it manually like..
        let className = (props.className != undefined)? props.className: '';
        if (backgroundColor != undefined) {
            className += ' has-' + backgroundColor + '-background-color';
        }
        props.className = className;
        if (customBackgroundColor != undefined) {
            Object.assign(props, { style: { ...props.style, backgroundColor: customBackgroundColor }});
        }
    }
    return props;
}
 
wp.hooks.addFilter(
    'blocks.getSaveContent.extraProps',
    'awp/spacer-apply-class',
    applySpacerBackground
);

Dzięki powyższemu kodowi frontend będzie teraz doskonale renderować bloki Spacer z naszym niestandardowym wyborem kolorów!

Ostatnią (opcjonalną) poprawką jest dodanie CSS do edytora. Musisz dodać wbudowany CSS lub arkusz stylów edytora. Na przykład możesz umieścić arkusz stylów w kolejce w tym samym haczyku PHP, którego użyliśmy do umieszczenia w kolejce naszego pliku JavaScript. Nie będę wdawać się w szczegóły, jak to zrobić; ale CSS, którego potrzebujesz, jest podobny do poniższego. Jedyne co robi, to ustawia Spacer background-colorna odziedziczony kolor (będzie dziedziczył po naszym wrapping div) po zaznaczeniu bloku:


.block-library-spacer__resize-container.is-selected { 
    background-color: inherit; 
}

PS: Pamiętaj, że może się to zmienić w przyszłości. Gutenberg wciąż intensywnie się rozwija.

Wniosek

W tym poście poznaliśmy dwie metody implementowania niestandardowych ustawień do istniejących bloków WordPress Gutenberg. Jest to w pełni możliwe w przypadku prostych ustawień, które być może wymagają jedynie stylizacji klasowej lub wbudowanej. Przyjrzeliśmy się ostrzeżeniom, które mam nadzieję zostaną poprawione w późniejszych wersjach Gutenberga!

Źródło nagrywania: awhitepixel.com