Jak dodać przycisk do edytora Gutenberga za pomocą @wordpress/scripts

Prawie półtora roku temu Antonio napisał ten wpis na blogu, wyjaśniając jedną z trudności, jakie napotkaliśmy podczas dostosowywania naszych wtyczek do nowego edytora bloków WordPress. Wynik jego samouczka wyglądał mniej więcej tak:

Na szczęście lub niestety Gutenberg bardzo się zmienił w tym półtora roku. Stos programistyczny rozwija się i ulepsza, a twórcy wtyczek i motywów musieli przyjąć i dostosować nowe technologie. A ci z nas, którzy również piszą o swoim doświadczeniu i dzielą się tym, czego się dowiadujemy, są teraz „zmuszeni” do aktualizowania naszych samouczków, abyście mogli być na bieżąco. Ale cieszymy się z tego!

Kilka tygodni temu Ivan, jeden z naszych czytelników, zostawił nam komentarz w tutorialu Antonio, prosząc o pomoc. Najwyraźniej nie był w stanie zaimplementować wtyczki Antonio. I szczerze mówiąc, nie dziwi mnie to, bo ostatnio wiele się zmieniło. Tak więc, aby pomóc Ivanowi i wszystkim, którzy nas czytają i chcą kontynuować naukę o WordPressie, odtwórzmy samouczek dotyczący dodawania przycisku do edytora bloków Gutenberga, korzystając ze wszystkich nowych narzędzi, które oferuje nam WordPress!

Utwórz wtyczkę

Pierwszą rzeczą, którą musimy zrobić, to stworzyć wtyczkę WordPress. To całkiem proste. Zasadniczo wszystko, co musimy zrobić, to utworzyć folder w wp-content/plugins o nazwie, którą chcemy nadać naszej wtyczce (na przykład gutenberg-button ) i w nim utworzyć plik o tej samej nazwie i .php rozszerzenie .php . Następnie wpisz następujący kod w pliku wtyczki:

Teraz przyjrzyjmy się bliżej temu, co robi poprzedni fragment:

• Najpierw otwieramy tag <?php . Tutaj nie ma niespodzianek.
• Następnie w tym głównym pliku dodajemy wielowierszowy komentarz. Komentarz zawiera kilka wierszy z parami „Klucz/Wartość”. Na przykład widzimy, jak określamy nazwę wtyczki ( Plugin Name ), jej wersję ( Version ) lub nazwisko autora ( Author ). Wszystkie te informacje będą widoczne w sekcji Wtyczki w WordPressie.
• Na koniec dodajemy kod wzorcowy:
  • określamy namespace (mówiliśmy tutaj o przestrzeniach nazw),
  • upewniamy się, że jeśli plik działa, jest uruchamiany jako część WordPressa i
  • definiujemy pewne stałe dotyczące wtyczki (które przydadzą się później).

Gdy już to zrobimy, jeśli przejdziemy do ekranu Wtyczki naszego WordPressa, zobaczymy, że jest tam przycisk Gutenberg :

aktywujemy go i… voila! Jasne, to nic nie da, ale już tam jest.

Rozwój wtyczek JavaScript

W dzisiejszych czasach programiści WordPress muszą biegle posługiwać się JavaScript. To chyba jedna z konsekwencji tego, że Gutenberg jest w centrum, jak sądzę. A ten samouczek nie jest wyjątkiem.

Przygotowanie środowiska

Jeśli chcemy dodać nowy przycisk do interfejsu Gutenberga, musimy zakodować tę funkcję w JavaScript. Przygotujmy więc środowisko programistyczne JavaScript w naszej wtyczce. Aby to zrobić, po prostu uruchom następującą komendę z wiersza poleceń (upewnij się, że podczas robienia jesteś w wp-content/plugins/gutenberg-button ):

 npm init

i postępuj zgodnie z instrukcjami:

 This utility will walk you through creating a package.json file. It only covers the most common items, and tries to guess sensible defaults. See `npm help json` for definitive documentation on these fields and exactly what they do. Use `npm install <pkg>` afterwards to install a package and save it as a dependency in the package.json file. Press ^C at any time to quit. package name: (gutenberg-button) version: (1.0.0) description: Adding a formatting button in Gutenberg. entry point: (index.js) ...

Wynikiem tego procesu jest plik package.json . Jak zobaczysz za chwilę, ten plik będzie niezwykle pomocny w przyszłości.

Jak już zdradziłem w tytule tego posta, do stworzenia naszej wtyczki użyjemy @wordpress/scripts . Dodajmy więc to jako zależność, uruchamiając następujące polecenie:

 npm install --save-dev @wordpress/scripts

To polecenie pobierze kilka zależności wewnątrz naszej wtyczki (pod node_modules ) i zmodyfikuje nasz plik package.json , aby było jasne, że @wordpress/scripts jest teraz zależnością programistyczną.

Jeśli zajrzysz do dokumentacji tego pakietu, zobaczysz, że zawiera ona wiele skryptów do zbudowania, walidacji składni, kodu formatu, itp.:

 { "scripts": { "build": "wp-scripts build", "check-engines": "wp-scripts check-engines", "check-licenses": "wp-scripts check-licenses", "format:js": "wp-scripts format-js", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "lint:md:docs": "wp-scripts lint-md-docs", "lint:md:js": "wp-scripts lint-md-js", "lint:pkg-json": "wp-scripts lint-pkg-json", "packages-update": "wp-scripts packages-update", "start": "wp-scripts start", "test:e2e": "wp-scripts test-e2e", "test:unit": "wp-scripts test-unit-js" } }

edytujmy więc nasz plik package.json , aby sekcja "scripts" zawierała wszystkie zalecane polecenia.

Jak sprawdzić, czy wszystko działa…

Utwórzmy folder src w katalogu głównym projektu i dodajmy do niego plik index.js . Będzie to główny plik JavaScript naszej wtyczki i będzie zawierał cały Twój kod (możesz następnie uporządkować kod według własnego uznania, o ile głównym plikiem jest src/index.js ).

Sprawdźmy, czy wszystko działa zgodnie z oczekiwaniami, dodając następującą instrukcję index.js :

 console.log( 'Hi!' );

i budowanie projektu za pomocą npm run build . To przetranspiluje twój kod do czegoś, co przeglądarka może uruchomić (nie było to teraz potrzebne, ale zajmie to tylko kilka minut) i wygeneruje nowy skrypt w folderze build .

Wszystko, co musimy teraz zrobić, to powiedzieć WordPressowi, że ten skrypt istnieje, aby mógł go załadować. Aby to zrobić, po prostu otwórz główny plik wtyczki ( gutenberg-button.php ) i dodaj na końcu następujące wiersze:

 function enqueue_script() { wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', [], GUTENBERG_BUTTON_VERSION ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

Jeśli zwrócisz uwagę, zobaczysz, że po prostu mówimy WordPressowi, aby umieścił nasz nowy skrypt /build/index.js w kolejce jako zasób edytora bloków. W ten sposób, gdy użytkownik uzyska dostęp do edytora bloków, nasz skrypt będzie częścią zasobów, które edytor będzie zawierał.

Sprawdźmy to. Przejdź do pulpitu WordPress, edytuj post i spójrz na konsolę JavaScript w przeglądarce. Jeśli wszystko poszło zgodnie z oczekiwaniami, powinieneś zobaczyć „Cześć!” napisane na konsoli:

Replikowanie naszego samouczka, aby dodać przycisk do Gutenberga

Dobra, teraz, gdy widzieliśmy, że możemy pisać kod JavaScript i npm run build go w coś, co zrozumieją nasze przeglądarki, nadszedł czas, aby powtórzyć samouczek Antonio. A to, drogi czytelniku, jest niezwykle proste.

Otwórz plik src/index.js i zastąp poprzednią instrukcję console.log następującą:

Jak widać, jest to prawie ten sam kod, który Antonio napisał kilka miesięcy temu. Główna różnica polega na tym, że nie używamy już zmiennej globalnej wp , aby uzyskać dostęp do funkcji i komponentów Gutenberga; zamiast tego polegamy teraz na instrukcjach import . Ale poza tym jest prawie tak samo.

Gdy już masz napisany kod, po prostu npm run build go i to wszystko! Masz teraz przycisk w Gutenberg:

Upewnijmy się, że to działa, zaznaczając jakiś tekst i klikając przycisk:

i proszę bardzo, widzimy, że tekst ponownie pojawia się w konsoli!

Ostatnia uwaga na temat zależności…

Jeśli zajrzysz do folderu build , zobaczysz, że @wordpress/scripts nie tylko utworzył plik index.js , ale ma też plik index.asset.php . Ten plik definiuje mały obiekt o dwóch właściwościach:

• lista zależności (czyli skryptów WordPress) wymaganych przez naszą wtyczkę
• wersja kompilacji

Możemy (i powinniśmy) użyć obu tych właściwości podczas kolejkowania naszego skryptu w WordPressie, jeśli chcemy mieć pewność, że skrypt będzie działał poprawnie. Aby to zrobić, po prostu wróć do gutenberg-button.php i zmień go, jak pokazano poniżej:

 function enqueue_script() { $asset = include GUTENBERG_BUTTON_PATH . '/build/index.asset.php'; wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', $asset['dependencies'], $asset['version'] ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

Po prostu załaduj obiekt w index.asset.php za pomocą instrukcji include i zamień listę zależności, które mieliśmy ( [] ) na rzeczywiste zależności i użyj numeru kompilacji jako wersji wtyczki.

Wnioski

Tworzenie naprawdę przydatnych wtyczek do WordPressa jest trudne. Musisz dobrze zrozumieć, jak działa JavaScript i znać wszystkie zasoby, jakie ma WordPress. Ale dzięki pakietowi @wordpress/scripts przygotowanie środowiska deweloperskiego JavaScript i zbudowanie wtyczki JavaScript, która może działać w WordPressie, jest łatwiejsze niż kiedykolwiek.

Mam nadzieję, że podobał Ci się dzisiejszy post. I jak zawsze, jeśli utkniesz w dowolnym momencie lub masz pytania, zostaw komentarz, a my Ci pomożemy.

A tak przy okazji, oto link do projektu, gotowy do pobrania i przetestowania, jeśli sobie tego życzysz. Po prostu sklonuj projekt, npm install wszystkie zależności, npm run build go i spróbuj!

Polecane zdjęcie Ashima D'Silvy na Unsplash.