Cum să adăugați un buton la Editorul Gutenberg folosind @wordpress/scripts

În urmă cu aproape un an și jumătate, Antonio a scris această postare pe blog explicând una dintre dificultățile cu care ne-am confruntat atunci când ne adaptăm pluginurile la noul editor de blocuri WordPress. Rezultatul tutorialului său arăta cam așa:

Din fericire sau din păcate, Gutenberg s-a schimbat mult în acest an și jumătate. Stiva de dezvoltare s-a extins și s-a îmbunătățit, iar dezvoltatorii de pluginuri și teme au trebuit să îmbrățișeze și să adapteze noile tehnologii. Iar aceia dintre noi care scriem și despre experiența noastră și împărtășim ceea ce învățăm suntem acum „obligați” să ne actualizăm tutorialele pentru a putea fi la curent. Dar ne bucurăm de asta!

Acum câteva săptămâni, Ivan, unul dintre cititorii noștri, ne-a lăsat un comentariu în tutorialul lui Antonio în care ne-a cerut ajutor. Se pare că nu a putut să implementeze pluginul lui Antonio. Și, să fiu sincer, acest lucru nu mă surprinde, pentru că lucrurile s-au schimbat foarte mult în ultima perioadă. Așadar, pentru a vă ajuta pe Ivan și pe toți cei care ne citiți și doriți să continuați să învățați despre WordPress, să recreăm tutorialul despre cum să adăugați un buton în editorul de blocuri Gutenberg profitând de toate instrumentele noi pe care ni le oferă WordPress!

Creați un plugin

Primul lucru pe care trebuie să-l facem este să creăm un plugin WordPress. Acest lucru este destul de simplu. Practic, tot ce trebuie să facem este să creăm un folder în wp-content/plugins cu numele pe care vrem să-l dăm pluginului nostru (de exemplu, gutenberg-button ) și, în cadrul acestuia, să creăm un fișier cu același nume și un .php extensia .php . Apoi tastați următorul cod în fișierul dvs. de plugin:

Acum, să aruncăm o privire mai atentă la ceea ce face fragmentul anterior:

• Mai întâi deschidem o etichetă <?php . Nicio surpriză aici.
• Apoi, în acest fișier principal, adăugăm un comentariu pe mai multe rânduri. Comentariul include mai multe rânduri cu perechi „Cheie/Valoare”. De exemplu, vedem cum specificăm numele pluginului ( Plugin Name ), versiunea acestuia ( Version ) sau numele autorului ( Author ). Toate aceste informații vor fi apoi vizibile în secțiunea Plugin -uri din WordPress.
• În cele din urmă, adăugăm niște coduri standard:
  • specificăm un spațiu de namespace (am vorbit despre spații de nume aici),
  • ne asigurăm că, dacă fișierul rulează, acesta este rulat ca parte a WordPress și
  • definim câteva constante despre plugin (care vor fi de ajutor mai târziu).

Odată ce am făcut toate acestea, dacă mergem la ecranul Plugin -uri al WordPress-ului nostru, vom vedea că Butonul Gutenberg este acolo:

îl activăm și... voila! Sigur, nu va face nimic, dar este deja acolo.

Dezvoltare plugin JavaScript

În zilele noastre, dezvoltatorii WordPress trebuie să fie pricepuți cu JavaScript. Asta e una dintre consecințele faptului că Gutenberg este în miez, cred. Și acest tutorial nu face excepție.

Pregătirea mediului

Dacă vrem să adăugăm un nou buton la interfața Gutenberg, trebuie să codificăm această caracteristică în JavaScript. Deci, să pregătim mediul de dezvoltare JavaScript în pluginul nostru. Pentru a face acest lucru, pur și simplu rulați următoarea comandă din linia de comandă (asigurați-vă că sunteți în wp-content/plugins/gutenberg-button când faceți acest lucru):

 npm init

și urmați instrucțiunile:

 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) ...

Rezultatul acestui proces este un fișier package.json . După cum veți vedea în câteva momente, acest fișier vă va fi extrem de util în viitor.

După cum am dezvăluit deja în titlul acestei postări, vom folosi @wordpress/scripts pentru a crea pluginul nostru. Deci, să-l adăugăm ca dependență, rulând următoarea comandă:

 npm install --save-dev @wordpress/scripts

Această comandă va descărca o mulțime de dependențe în interiorul pluginului nostru (sub node_modules ) și va modifica package.json , astfel încât să fie clar că @wordpress/scripts este acum o dependență de dezvoltare.

Dacă aruncați o privire la documentația acestui pachet, veți vedea că acesta include o mulțime de scripturi pentru a construi, valida sintaxa, codul de format, etc:

 { "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" } }

deci haideți să edităm fișierul package.json , astfel încât secțiunea "scripts" să conțină toate comenzile recomandate.

Cum să verifici dacă totul funcționează...

Să creăm un folder src la rădăcina proiectului și să adăugăm un fișier index.js în interiorul acestuia. Acesta va fi fișierul JavaScript principal al pluginului nostru și va conține tot codul dvs. (puteți organiza apoi codul după cum doriți, atâta timp cât fișierul principal este src/index.js ).

Să încercăm dacă lucrurile funcționează conform așteptărilor adăugând următoarea declarație index.js :

 console.log( 'Hi!' );

și construirea proiectului folosind npm run build . Acest lucru vă va transpila codul în ceva pe care îl poate rula un browser (de fapt nu era necesar acum, dar va fi în doar câteva minute) și va build un nou script într-un folder de compilare.

Tot ce trebuie să facem acum este să spunem WordPress că acest script există, astfel încât să îl poată încărca. Pentru a face acest lucru, pur și simplu deschideți fișierul principal al pluginului dvs. ( gutenberg-button.php ) și adăugați următoarele rânduri la sfârșit:

 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' );

Dacă acordați atenție, veți vedea că pur și simplu îi spunem WordPress să pună în coadă noul nostru script /build/index.js ca resursă de editor de blocuri. În acest fel, atunci când un utilizator accesează editorul de blocuri, scriptul nostru va face parte din activele pe care editorul le va include.

Deci, hai să verificăm asta. Accesați tabloul de bord WordPress, editați o postare și uitați-vă la consola JavaScript a browserului dvs. Dacă lucrurile au mers conform așteptărilor, ar trebui să vedeți „Bună!” scris pe consola:

Replicarea tutorialului nostru pentru a adăuga un buton la Gutenberg

Bine, acum că am văzut că putem scrie cod JavaScript și npm run build în ceva ce browserele noastre vor înțelege, este timpul să reproducem tutorialul lui Antonio. Și asta, dragă cititor, este extrem de simplu.

Deschideți fișierul src/index.js și înlocuiți instrucțiunea anterioară console.log cu următoarea:

După cum puteți vedea, acesta este aproape același cod pe care l-a scris Antonio acum câteva luni. Principala diferență este faptul că nu mai folosim variabila globală wp pentru a accesa funcțiile și componentele lui Gutenberg; în schimb, acum ne bazăm pe declarațiile de import . Dar în afară de asta, este cam la fel.

Odată ce ați scris codul, doar npm run build -l și gata! Acum aveți butonul în Gutenberg:

Să ne asigurăm că funcționează selectând un text și făcând clic pe butonul:

și gata, vedem că textul apare din nou în consolă!

O notă finală despre dependențe...

Dacă aruncați o privire în folderul de compilare, veți vedea că @wordpress/scripts nu numai că a build un fișier index.js , dar are un fișier index.asset.php . Acest fișier definește un obiect mic cu două proprietăți:

• o listă de dependențe (și anume, scripturi WordPress) cerute de pluginul nostru
• o versiune build

Putem (și ar trebui) să folosim ambele proprietăți atunci când punem în coadă scriptul nostru în WordPress dacă vrem să ne asigurăm că scriptul va rula corect. Pentru a face acest lucru, mergeți înapoi la gutenberg-button.php și schimbați-l așa cum se arată mai jos:

 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' );

Pur și simplu încărcați obiectul în index.asset.php folosind o instrucțiune include și înlocuiți lista de dependențe pe care o aveam ( [] ) cu dependențele reale și utilizați numărul de compilare ca versiune de plugin.

Concluzii

Crearea de pluginuri WordPress cu adevărat utile este dificilă. Trebuie să înțelegeți bine cum funcționează JavaScript și să fiți familiarizat cu toate resursele de care dispune WordPress. Dar datorită pachetului @wordpress/scripts , pregătirea mediului de dezvoltare JavaScript și construirea unui plugin JavaScript care poate rula în WordPress este mai ușoară ca niciodată.

Sper că ți-a plăcut postarea de azi. Și, ca întotdeauna, dacă rămâneți blocat în orice moment sau aveți întrebări, vă rugăm să lăsați un comentariu și vă vom ajuta.

A, și, apropo, iată un link către proiect, gata de descărcat și testat dacă doriți. Doar clonează proiectul, npm install toate dependențele, npm run build -l și încearcă!

Imagine prezentată de Ashim D'Silva pe Unsplash.