W tym samouczku przyjrzymy się, jak dodać niestandardowy pasek boczny do Inspektora (prawy pasek boczny) w WordPress Gutenberg. Wewnątrz zaimplementujemy pole połączone z meta postu. Wszystko jest zaimplementowane za pomocą Javascript, wewnątrz edytora Gutenberga i jest alternatywą do dodawania metaboksów w tradycyjny sposób.
Heads-up!
To jest samouczek dotyczący tworzenia własnego niestandardowego paska bocznego. Ale jeśli interesuje Cię tylko dodanie meta/ustawień do standardowego paska bocznego Inspektora (zakładka „Dokument"), mam na to samouczek:
Co stworzymy
WordPress Gutenberg umożliwia programistom tworzenie niestandardowych pasków bocznych za pomocą tak zwanej wtyczki Javascript. (Nie mylić z tradycyjnymi wtyczkami WordPress). Za pomocą wtyczki JavaScript możemy stworzyć nowy pasek boczny, a także podłączyć do menu „Narzędzia i opcje”.
Dodamy nowy element menu w „Narzędzia”, który otworzy nasz niestandardowy pasek boczny. Zawartość paska bocznego zależy wyłącznie od Ciebie, ale omówię kilka przykładów, w tym sposób połączenia w nim pola meta postu.
Konfiguracja JavaScript
W tym samouczku napiszę JavaScript ES6/ESNext z JSX, co oznacza, że musimy skonfigurować kompilator. Jeśli chcesz podążać dalej i nie pisać JavaScript ES5, będziesz musiał skonfigurować środowisko programistyczne, które będzie kompilować Twój Javascript na bieżąco. Jeśli nie znasz tego, postępuj zgodnie z moim postem wyjaśniającym, jak to skonfigurować, a następnie wróć tutaj.
Skonfigurowałem mój, webpack.config.jsaby skompilować mój źródłowy plik JavaScript do mojego folderu motywu /assets/js/sidebar-plugin.js. Ten skompilowany plik jest tym, czego potrzebujemy do umieszczenia w kolejce do edytora Gutenberga. Kiedy piszę ten kod, uruchomiłem kompilator run-time, który rekompiluje JavaScript za każdym razem, gdy zapisuję zmiany w kodzie źródłowym (npm run start). Wszystko to zostało szczegółowo wyjaśnione we wcześniej wspomnianym samouczku.
Piszę to w motywie, ale działa tak samo we wtyczce. Pamiętaj tylko o dostosowaniu ścieżek podczas dodawania skryptu do edytora.
Dodanie skryptu do edytora
Aby dodać nasz skrypt do edytora Gutenberga, musimy napisać trochę PHP. Jeśli jesteś w motywie, functions.phpjest to dobre miejsce do rozpoczęcia lub gdzieś w plikach wtyczek. Zauważ, że musimy dodać ostateczny skompilowany skrypt, a nie kod źródłowy. W moim przykładzie skompilowany JavaScript znajduje się w moim folderze motywu /assets/js/sidebar-plugin.js.
Tworzymy funkcję podpiętą do enqueue_block_editor_assets. Wewnątrz robimy to co zwykle [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)(). Jako zależności do skryptu dodajemy dwa; wp-plugins, i wp-edit-post. Te dwa pakiety muszą zostać załadowane przed naszym skryptem, ponieważ używamy z nich funkcji.
add_action('enqueue_block_editor_assets', function() {
wp_enqueue_script('awp-sidebar-plugin', get_stylesheet_directory_uri(). '/assets/js/sidebar-plugin.js', ['wp-plugins', 'wp-edit-post']);
});Ponieważ umieszczamy skrypt w kolejce w hooku, enqueue_block_editor_assetsnasz skrypt zostanie załadowany tylko wtedy, gdy aktywny jest edytor Gutenberga. Świetny! Teraz wszystko jest gotowe do napisania naszej wtyczki Javascript.
Zarejestruj wtyczkę JavaScript
Pierwszym krokiem jest zarejestrowanie wtyczki. Robimy to za pomocą [registerPlugin](https://github.com/WordPress/gutenberg/tree/master/packages/plugins#registerPlugin)funkcji w wp.plugins z wnętrza wp.pluginspakietu.
Jako parametr registerPlugin podajemy nazwę (upewnij się, że jest unikalna) oraz obiekt z ustawieniami. Jako minimum musisz dostarczyć komponent dla właściwości renderowania. Możesz również opcjonalnie dodać ikonę z dashikonów WordPressa. Pamiętaj, że jeśli nie określisz ikony, powróci ona do ikony wtyczki. Do celów demonstracyjnych używam 'carrot'ikony.
Jeśli chodzi o komponent, zaczynamy od zdefiniowania podstawowego komponentu, który zwraca prosty div z losowym tekstem w nim. A przed całym kodem destrukturyzujemy funkcje z pakietów, których chcemy użyć.
Jeśli nic się nie stanie (nawet błędy), gdy odświeżysz Gutenberga, wszyscy jesteśmy gotowi. Nie widzimy naszego komponentu, ponieważ nie powiedzieliśmy WordPressowi, gdzie ma go renderować. Następnym krokiem jest podłączenie do niestandardowego menu paska bocznego i komponentów menu narzędzi do renderowania naszych rzeczy.
Zarejestruj niestandardowy pasek boczny
Ale najpierw wyjaśnienie, w jaki sposób Gutenberg obsługuje niestandardowe paski boczne i dlaczego musimy robić to, co zrobimy. Kiedy pomyślnie zarejestrujemy niestandardowy pasek boczny, na początku automatycznie wydarzy się jedna rzecz. Gutenberg doda skrót do naszego paska bocznego na górnym pasku narzędzi, obok menu Narzędzia. Dzieje się tak, ponieważ nasz pasek boczny jest automatycznie „przypinany”.
Problem z dodaniem niestandardowego paska bocznego polega na tym, że każdy użytkownik może „odpiąć” ten skrót. Kiedy to zrobią, nie ma punktu dostępu, aby ponownie otworzyć pasek boczny! Dlatego musimy również dodać element menu do menu Narzędzia.
Rejestracja niestandardowego paska bocznego odbywa się za pomocą komponentu PluginSidebarz wp.editPostpakietu. Dodanie pozycji menu do menu Narzędzia odbywa się za pomocą trafnie nazwanego komponentu PluginSidebarMoreMenuItem(również w wp.editPostpakiecie).
Dla PluginSidebarkomponentu musimy dostarczyć kilka rekwizytów. Powinieneś podać jako minimum namei title. Rekwizyt titlenie wymaga wyjaśnień, jest to nazwa, która pojawi się na górze paska bocznego. W rekwizycie namezapewnij unikalny ślimak. Po dodaniu elementu menu musisz odwołać się do tego ślimaka.
Dodanie PluginSidebarMoreMenuItemkomponentu (menu narzędzi) wymaga co najmniej jednego atrybutu; target. Tutaj podajesz taką samą nazwę, jaką podałeś w rekwizycie paska bocznego name. Jako zawartość komponentu wpisujesz tekst, który będzie wyświetlany jako pozycja menu. Zwykle będzie to to samo, co na pasku bocznym title.
Ponieważ React wymaga pojedynczego węzła zawijającego wokół zwrotu komponentu, zawijamy wszystko wewnątrz Fragmentkomponentu (z wp.elementpakietu). Zawijam również moje ciągi __()z wp.i18npakietu, aby umożliwić tłumaczenie.
Z powyższym kodem otrzymamy następujące dwie (najprawdopodobniej trzy) rzeczy, które się wydarzą. Otrzymasz skrót do ikony marchewki na pasku narzędzi (jeśli jeszcze go nie odpiąłeś). Kliknięcie tego otworzy pasek boczny. Otrzymasz również nowy element menu na pasku bocznym w menu Narzędzia, pod nagłówkiem „Wtyczki”.
Dodawanie treści do paska bocznego
Rzeczywista zawartość paska bocznego zależy wyłącznie od Ciebie. Musisz tylko dodać kod HTML lub komponenty wewnątrz PluginSidebarkomponentu z tym, co chcesz (zamiast tekstu „Witaj”.).
Możesz zauważyć, że w treści paska bocznego brakuje wypełnienia. Jest to celowe, ponieważ pomysł polega na tym, że tworzysz panele wewnątrz tego paska bocznego. Panele to składane sekcje na normalnym pasku bocznym Gutenberga. Są to komponenty, które możesz bardzo łatwo dodać do niestandardowego paska bocznego. Możesz dodać tyle paneli, ile chcesz i świetnie nadają się do grupowania różnych rzeczy.
Dodawanie paneli do naszego paska bocznego
Przyjrzyjmy się szybko, jak możemy dodać panele do naszego paska bocznego. Jeśli stworzyłeś własne niestandardowe typy bloków, być może znasz te komponenty. Używamy PanelBodyi opcjonalnie PanelRowz wp.componentspakietu.
Dla PanelBodykomponentu podajesz jako minimum rekwizyt title. Możesz opcjonalnie podać wartość true lub false do właściwości, initialOpenaby zdecydować, czy panel powinien być rozwinięty domyślnie, czy nie. Ponieważ zawartość wewnątrz komponentu to wszystko, co znajduje się w panelu.
Wewnątrz a PanelBodymożesz opcjonalnie użyć PanelRowkomponentów. Nie są one naprawdę potrzebne, ale mogą pomóc w uzyskaniu dobrego stylu treści panelu.
Na przykład dodajmy dwa panele do naszego niestandardowego paska bocznego.
Dzięki temu kodowi nasz niestandardowy pasek boczny zaczyna wyglądać tak, jakby należał do Gutenberga!
Dodawanie pól meta postu do niestandardowego paska bocznego
Teraz naprawdę wchodzimy w sedno przydatnych elementów niestandardowego paska bocznego; dodawanie ustawień i przechowywanie ich wartości. Ale najpierw musimy zrozumieć, jak.
Naprawdę łatwo jest dodać pola ustawień (wejściowe, pola wyboru, pola przełączania itp.) na pasku bocznym, korzystając z gotowych do użycia komponentów w pakietach WordPressa. Musimy jednak zastanowić się, jak przechowywać wartości. Oczywistą opcją jest przechowywanie ich jako post meta. Ale podłączenie ustawienia do pola meta postu wymaga dodatkowego kodu. Dokładniej, musimy użyć tak zwanych komponentów wyższego rzędu, aby pobrać i zaktualizować post meta wewnątrz Javascript. Musimy również zarejestrować każdą meta posta za pomocą PHP i udostępnić ją REST API.
Na zakończenie tego samouczka zademonstruję, jak dodać meta posta z kluczem awp_my_custom_meta, który powinien być przechowywany jako prawda lub fałsz. Na pasku bocznym będzie wyświetlany jako pole przełączania (składnik prawda/fałsz).
Zarejestruj meta posta dla REST API
Pierwszym krokiem do dodania meta postu w naszym pliku Javascript jest ich zarejestrowanie i zdefiniowanie jako dostępne w REST API. W tym celu ponownie wracamy do PHP.
Wewnątrz funkcji podpiętej do initakcji używamy [register_meta](https://developer.wordpress.org/reference/functions/register_meta/)()funkcji. Jako parametry musimy zdefiniować typ obiektu jako ‘ post‘ ponieważ używamy go jako meta postu (nie wyklucza to np. typu page post). Podajemy metaklucz, a następnie tablicę argumentów. Najważniejszą rzeczą do dodania w tablicy arguments jest ustawienie ‘ show_in_rest‘ na true. Post meta jest powszechnie używany jako „ single” (pomyśl, jak używasz get_post_meta()). Definiujemy również type. W naszym przypadku ustawiliśmy go na ‘ boolean‘.
Za pomocą tego kodu ‘ awp_my_custom_meta‘ post metapole jest dostępne z Gutenberga. Musisz powtórzyć register_meta()dla każdego meta postu, który chcesz dodać na pasku bocznym.
Wróćmy teraz do naszego JavaScriptu.
Dodawanie ustawienia do naszego paska bocznego
Zacznijmy od prostej części: dodania danych wejściowych do naszego paska bocznego. Później dodamy więcej kodu, aby faktycznie połączyć pole ustawień z postem meta. Ze względu na sposób, w jaki musimy to zrobić, definiujemy osobny nowy składnik dla naszego ustawienia. Tak więc w panelu, do którego chcesz dodać swoje ustawienia, po prostu nazwij ten nowy komponent.
Nazwijmy komponent CustomSidebarMetaComponent(możesz nazwać go czymś istotnym dla twojego projektu). Wewnątrz tego komponentu chcemy wyrenderować pole przełączania. W tym celu używamy ToggleControlkomponentu z wp.componentspakietu. Jako rekwizyty do ToggleControl dostarczamy etykietę dopasowania w rekwizycie title. ToggleControl potrzebuje również rekwizytów onChangedo aktualizacji wartości i checkedbieżącej wartości. Na razie pominiemy te dwie rzeczy do następnego kroku.
Z powyższym kodem powinieneś otrzymać pole przełączania na pasku bocznym. Nie jest zaznaczona i nic się nie dzieje po kliknięciu. To kolejny krok: połączenie go z naszą meta postu.
Dostęp do meta postu za pomocą funkcji withSelect i withDispatch
Aby uzyskać dostęp, a także zaktualizować post meta wartość, musimy użyć komponentów wyższego rzędu (HOC), aby uzyskać dostęp do wersji sklepów WordPress (podobnej do Redux). WordPress dostarcza nam kilka przydatnych KWR z funkcjami, które możemy wykorzystać w wp.datapakiecie.
Komponent wyższego rzędu [withSelect](https://developer.wordpress.org/block-editor/packages/packages-data/#withSelect)dostarcza naszemu komponentowi właściwości, które w naszym przypadku są pobierane z post meta. Używamy tego, aby uzyskać wartość naszej meta postu. Wewnątrz withSelectmożemy użyć select('core/editor').getEditedPostAttribute('meta')do pobrania meta bieżącego posta.
Z drugiej strony [withDispatch](https://developer.wordpress.org/block-editor/packages/packages-data/#withDispatch)jest komponentem wyższego rzędu, który może wykonywać akcje. W naszym przypadku chcemy zaktualizować meta postu, gdy odpowiednie ustawienie pola zostanie zmienione na naszym pasku bocznym. Wewnątrz tego komponentu używamy dispatch('core/editor').editPost()do poinformowania WordPressa, aby wysłał akcję. Wewnątrz dostarczonego obiektu mówimy WordPressowi, że to meta, którą chcemy zaktualizować.
Na koniec musimy połączyć withSelecti withDispatchz naszym komponentem, który obsługuje metapole postu (CustomSidebarMetaComponent). W tym celu używamy WordPressa composez wp.composepakietu. Idea jest taka withSelecti withDispatchdostarcza naszemu CustomSidebarMetaComponentkomponentowi rekwizyty. withSelectudostępnia wartość meta postu jako prop i withDispatchudostępnia funkcję, którą możemy wywołać, aby zaktualizować wartość jako prop. Ustawiamy te właściwości odpowiednio na nasze ToggleField checkedi onChange.
To dużo wyjaśniania. Spójrzmy na rzeczywisty kod:
Zacznijmy od początku. Który jest na dole. W linii #36zmieniamy komponent, który renderujemy na naszym pasku bocznym, na komponent, za pomocą którego stworzyliśmy compose(at line #15). Komponent CustomSidebarMetapołączy składniki withSelecti withDispatchi zwróci CustomSidebarMetaComponent.
CustomSidebarMetaComponentBędą mieli dostęp do rekwizytu customPostMetaValuez withSelect, a setCustomPostMetarekwizyt z withDispatchtych dwóch używamy do rekwizytów checkedi onChangerekwizytów w ToggleField.
Zauważ, że w linii #5dodajemy propsparametry do komponentów, aby udostępnić props w komponencie.
Podsumowanie i ostatnie słowa
Mam nadzieję, że ten samouczek był dla ciebie przydatny. To właśnie udało mi się zrozumieć na ten temat podczas wielu prób i błędów. Nie ma jeszcze prawie żadnej dokumentacji na ten temat. Nadal zmagam się z tym, zwłaszcza jeśli chodzi o sprawną obsługę wielu meta postów. Jeśli uda mi się nauczyć kilku dobrych sztuczek, na pewno zaktualizuję ten samouczek!
Mam nadzieję, że postępując zgodnie z tym samouczkiem, powinieneś mieć kod, który z powodzeniem doda nowy niestandardowy pasek boczny do edytora WordPress Gutenberg i, miejmy nadzieję, z pewną znaczącą treścią i ustawieniami. Oto ostateczny kod niestandardowego paska bocznego z polem meta postu.