Share
Den nya WordPress-redigeraren (kodnamn Gutenberg) beror på release i version 5.0. Nu är det den perfekta tiden att ta tag i det innan den landar i WordPress-kärnan. I den här serien visar jag dig hur du arbetar med Block API och skapar dina egna innehållsblock som du kan använda för att bygga dina inlägg och sidor.
I föregående inlägg såg vi hur man använder skapa-guten-blocket verktygslåda för att skapa ett plugin som innehåller ett provblock redo för oss att arbeta med. Vi kan enkelt förlänga detta efter behov, men det är en bra idé att veta hur man skapar ett block från början för att fullt ut förstå alla aspekter av Gutenbergs blockutveckling.
I det här inlägget skapar vi ett andra block i vår my-custom-blocket plugin för att visa en slumpmässig bild från PlaceIMGs webbtjänst. Du kan också anpassa blocket genom att välja bildkategori från en rullgardinsmeny, välj kontroll.
Men först kommer vi att lära oss hur blockskript och format är kalkylerade innan vi går vidare till det viktigaste registerBlockType () funktion, vilket är grundläggande för att skapa block i Gutenberg.
För att lägga till JavaScript och CSS som krävs av våra block kan vi använda två nya WordPress-krokar från Gutenberg:
Accentsconagua
enqueue_block_editor_assetsenqueue_block_assetsDessa är bara tillgängliga om Gutenberg-plugin är aktiv, och de fungerar på samma sätt som vanliga WordPress-krokar för enkla skript. De är dock avsedda specifikt för att arbeta med Gutenberg-blocken.
De enqueue_block_editor_assets krok lägger till skript och stilar bara till administratörsredigeraren. Det här gör det idealiskt för enqueueing JavaScript för att registrera block och CSS till stil användargränssnitt för blockinställningar.
För blockutmatning vill du dock att dina block gör detsamma i redigeraren som de gör på fronten för det mesta. Använder sig av enqueue_block_assets gör det enkelt eftersom stilar automatiskt läggs till både redaktören och fronten. Du kan även använda denna krok för att ladda JavaScript om det behövs.
Men du kanske undrar hur man skämtar på skript och stilar endast på framsidan. Det finns inte en WordPress-krok som gör att du kan göra det direkt, men du kan komma runt detta genom att lägga till ett villkorligt uttalande inuti enqueue_block_assets hook callback-funktionen.
add_action ('enqueue_block_assets', 'load_front_end scripts'); funktion load_front_end scripts () if (! is_admin () // enqueue front end bara skript och stilar härFör att verkligen skicka skript och stilar med dessa två nya krokar kan du använda standarden wp_enqueue_style () och wp_enqueue_scripts () fungerar som du normalt skulle.
Men du måste se till att du använder rätt script beroende. För enqueueing-skript på redaktören kan du använda följande beroenden:
array ('wp-block', 'wp-i18n', 'wp-element', 'wp-komponenter') array ('wp-edit-blocks') Och när enqueueing stilar för både redaktören och fronten kan du använda detta beroende:
array ('wp-block')En sak som är värt att nämna här är att de faktiska filerna ankas av vår my-custom-blocket plugin är sammanställt versioner av JavaScript och CSS och inte de filer som innehåller källkoden JSX och Sass.
Detta är bara något att komma ihåg när man manuellt skriver in filer. Om du försöker skriva in rå källkod som innehåller React, ES6 + eller Sass kommer du att stöta på många fel.
Det är därför det är användbart att använda en verktygslåda som skapa-guten-blocket eftersom det behandlar och enklar skript för dig automatiskt!
För att skapa ett nytt block måste vi registrera det med Gutenberg genom att ringa registerBlockType () och passerar i blocknamnet plus ett konfigurationsobjekt. Detta objekt har en hel del egenskaper som kräver en korrekt förklaring.
För det första, låt oss ta en titt på blocknamnet. Det här är den första parametern och är en sträng som består av två delar, en namnrymd och själva namnet på blocket, åtskilda av ett snedstreck framåt.
Till exempel:
registerBlockType ("block-namespace / block-name", // konfigurationsobjekt);Om du registrerar flera block i ett plugin kan du använda samma namnrymd för att organisera alla dina block. Namnutrymmet måste vara unikt för din plugin, vilket hjälper till att förhindra namngivning av konflikter. Detta kan hända om ett block med samma namn redan har registrerats via ett annat plugin.
Den andra registerBlockType () parameter är ett inställningsobjekt och kräver ett antal egenskaper som ska anges:
titel (sträng): visas i redigeraren som sökbar blocketikettbeskrivning (valfri sträng): beskriver syftet med ett blockikon (valfritt Dashicon eller JSX element): ikon förknippad med ett blockkategori (sträng): där blocket visas i Lägg till block dialognyckelord (valfritt array): upp till tre nyckelord som används i block sökningarattribut (valfritt objekt): hanterar dynamiska blockdataredigera (funktion): en funktion som returnerar markering som ska göras i redigerarenspara (funktion): en funktion som returnerar markeringen som ska göras på framsidanuseOnce (valfri booleska): begränsa blocket från att läggas till mer än en gångbärare (valfritt objekt): definierar blockstödda funktionerAntag att vi använder JSX för blockutveckling, här är ett exempel registerBlockType () samtal kan se ut som ett mycket enkelt block:
registerBlockType ('my-unique-namespace / ultimate-block', title: __ ('Den bästa blocket någonsin', 'domän'), ikon: 'wordpress', kategori: 'common', nyckelord: [__ ',' domän '), __ (' Gutenberg ',' domän '), __ (' block ',' domän ')], redigera: Välkommen till Gutenberg Editor!
, spara: () => Hur ser jag på framsidan?
);Lägg märke till hur vi inte inkluderade en post för beskrivning, attribut, useOnce, och bärare egenskaper? Alla fält som är valfria (och inte relevanta för ditt block) kan säkert utelämnas. Eftersom det här blocket inte innebar någon dynamisk data behöver vi inte oroa oss för att ange några attribut.
Låt oss nu täcka registerBlockType () konfigurationsobjektegenskaper mer detaljerat en efter en.
När du lägger in eller söker efter ett block i redigeraren kommer titeln att visas i listan över tillgängliga block.
Den visas också i blockinspektionsfönstret, tillsammans med blockbeskrivningen om den är definierad. Om blockinspektören inte är synlig så kan du använda kugghjulsikonen i det övre högra hörnet av Gutenberg-redigeraren för att växla sikt.
Både titlarna och beskrivningsfälten borde helst vara inslagna i i18n-funktioner för att möjliggöra översättning till andra språk.
Det finns fem blockkategorier som för närvarande finns tillgängliga:
allmänningformateringlayoutwidgetarbädda inDessa bestämmer kategorisektionen där ditt block är listat inuti Lägg till block fönster.
De Blocks fliken innehåller Vanliga block, formatering, Layoutelement, och widgets kategorier, medan inbäddningar kategori har sin egen flik.
Kategorier är för närvarande fastställda i Gutenberg, men det kan komma att ändras i framtiden. Detta skulle vara användbart, till exempel om du utvecklade flera block i ett enda plugin och du ville att alla skulle listas under en gemensam kategori så att användarna lättare kunde hitta dem.
Som standard är ditt block tilldelat skyddsdashikonet, men du kan åsidosätta detta genom att ange en anpassad Dashicon i ikon fält.
Varje Dashicon är prefixad med dashicons- följt av en unik sträng. Till exempel har växelsymbolen namnet dashicons-admin-generic. För att använda detta som en blockikon, ta bara bort dashicons- prefix för att det ska erkännas, t.ex.. ikon: "admin-generic".
Men du är inte bara begränsad till att använda Dashicons som egenskapen för ikonen. Funktionen accepterar också ett JSX-element, vilket innebär att du kan använda en bild eller ett SVG-element som din blockikon.
Bara se till att ikonstorleken överensstämmer med andra blockikoner, som är 20 x 20 pixlar som standard.
Välj upp till tre översättbara nyckelord för att få ditt block att sticka ut när användarna söker efter ett block. Det är bäst att välja nyckelord som är nära relaterade till funktionaliteten i ditt block för bästa resultat.
nyckelord: [__ ('sök', 'domän'), __ ('för', 'domän'), __ ('jag', 'domän')]Du kan till och med förklara ditt företags namn och / eller plugin namn som nyckelord så att om du har flera block kan användarna börja skriva ditt företags namn och alla dina block kommer att visas i sökresultaten.
Även om du lägger till nyckelord är helt frivilligt, är det ett bra sätt att göra det enklare för användarna att hitta dina block.
Attribut hjälper till att hantera dynamiska data i ett block. Den här egenskapen är valfri eftersom du inte behöver den för mycket enkla block som matar ut statiskt innehåll.
Om ditt block handlar om data som kan förändras (som innehållet i ett redigerbart textområde) eller om du behöver lagra blockinställningar, är det dock tillåtet att använda attribut som attribut.
Attribut fungerar genom att lagra dynamiska blockdata antingen i postinnehållet som sparats i databasen eller i postmeta. I den här handledningen använder vi bara attribut som lagrar data tillsammans med inläggets innehåll.
För att hämta attributdata lagrad i inläggsinnehåll måste vi ange var den ligger i markeringen. Vi kan göra detta genom att ange en CSS-väljare som pekar på attributdata.
Till exempel, om vårt block innehåller en ankare tagg, kan vi använda dess titel fält som vårt attribut som följer:
attribut: linktitle: source: 'attribute', väljare: 'a', attribut: 'title'
Här är attributnamnet linktitle, vilket är en godtycklig sträng och kan vara allt du vill.
Till exempel kan vi använda det här attributet för att lagra länktiteln Det har skrivits in via en textruta i blockinställningar. Om du gör det plötsligt gör titelfältet dynamiskt och låter dig ändra sitt värde i redigeraren.
När posten sparas, läggs attributvärdet in i länkarna titel fält. På samma sätt, när redigeraren är laddad, värdet av titel taggen hämtas från innehållet och infogas i linktitle attribut.
Det finns fler sätt du kan använda källa för att bestämma hur blockinnehållet lagras eller hämtas via attribut. Till exempel kan du använda 'text' källa för att extrahera den inre texten från ett styckeelement.
attribut: paragraph: source: 'text', väljare: 'p'
Du kan också använda barn källa för att extrahera alla barn nodar till ett element i en array och lagra den i ett attribut.
attribut: editablecontent: source: 'children', selector: '.parent'
Detta väljer elementet med klassen .förälder och lagrar alla barnnoder i editablecontent attribut.
Om du inte anger en källa sparas attributvärdet i HTML-kommentarer som en del av postmarkeringen när den sparas i databasen. Dessa kommentarer tas bort innan posten görs på framsidan.
Vi får se ett visst exempel på denna typ av attribut när vi kommer in på att implementera vårt slumpmässiga bildblock senare i denna handledning.
Attribut kan ta lite att vänja sig, så oroa dig inte om du inte förstår dem först för första gången. Jag rekommenderar att du tittar på attributen i Gutenberghandboken för mer detaljer och exempel.
De redigera funktionen styr hur ditt block visas i redigeringsgränssnittet. Dynamisk data skickas till varje block som rekvisita, inklusive eventuella anpassade attribut som har definierats.
Det är vanligt att lägga till className = props.className till huvudblockelementet för att mata ut en CSS-klass som är specifik för ditt block. WordPress lägger inte till det här för dig inuti editoren, så det måste läggas till manuellt för varje block om du vill inkludera det.
Använder sig av props.className är standardpraxis och rekommenderas eftersom det ger ett sätt att skräddarsy CSS-stilar för varje enskilt block. Formatet för den genererade CSS-klassen är .wp-block- namespace - name. Som du kan se är detta baserat på blocknamn / namn och gör det idealiskt att användas som en unik blockidentifierare.
Redigeringsfunktionen kräver att du returnerar giltigt markup via göra() metod som sedan används för att göra ditt block inuti redigeraren.
Liknande till redigera fungera, spara visar en visuell representation av ditt block men på framsidan. Den mottar också dynamisk blockdata (om den definieras) via rekvisita.
En viktig skillnad är det props.className är inte tillgänglig inuti spara, men det här är inget problem eftersom det sätts in automatiskt av Gutenberg.
De bärare egendom accepterar ett objekt med booleska värden för att avgöra om ditt block stöder vissa kärnfunktioner.
De tillgängliga objektegenskaperna du kan ställa in är följande.
ankare (default false): tillåter dig att länka direkt till ett visst blockcustomClassName (sant): lägger till ett fält i blockinspektören för att definiera en anpassad klassnamn för blocket klassnamn (sant): lägger till a klassnamn till blockrotelementet baserat på blocknamnethtml (sant): gör det möjligt att redigera blockmarkeringen direktuseOnce Fast egendomDet här är en användbar egenskap som låter dig begränsa ett block från att läggas till mer än en gång till en sida. Ett exempel på detta är kärnan Mer block, som inte kan läggas till på en sida om den redan finns.
Som du kan se, en gång Mer block har lagts till, blockikonen är gråtonad och kan inte väljas. De useOnce fastigheten är inställd på falsk som standard.
Det är dags att använda den kunskap vi har fått hittills för att genomföra ett solidt fungerande exempel på ett block som gör något mer intressant än att bara mata ut statiskt innehåll.
Vi bygger ett block för att mata ut en slumpmässig bild som erhållits via en extern förfrågan till PlaceIMG-webbplatsen, vilket ger en slumpmässig bild. Dessutom kan du välja den kategori av bild som returneras via en välj nedrullningskontroll.
För enkelhets skyld lägger vi till vårt nya block till samma my-custom-blocket plugin, istället för att skapa en helt ny plugin. Koden för standardblocket är placerad inuti / Src / blocket mapp, så lägg till en annan mapp inuti / src kallad random-bild och lägg till tre nya filer:
Alternativt kan du kopiera / Src / blocket mapp och byt namn på det om du inte vill skriva ut allt för hand. Se till att du byter namn block.js till index.js inuti den nya blockmappen.
Vi använder index.js för huvudblockets filnamn, eftersom detta tillåter oss att förenkla importdeklarationen inuti blocks.js. I stället för att inkludera sökvägen och hela filnamnet på blocket kan vi bara ange sökvägen till blockmappen och importera kommer automatiskt leta efter en index.js fil.
Öppna /src/blocks.js och lägg till en referens till vårt nya block högst upp i filen, direkt under den befintliga importdeklarationen.
importera "./random-image";
Inuti /src/random-image/index.js, lägg till följande kod för att starta vårt nya block.
// Importera CSS. importera "./style.scss"; importera "./editor.scss"; const __ = wp.i18n; const registerBlockType, query = wp.blocks; registerBlockType ('cgb / block-random-image', title: __ ('Slumpmässig bild'), ikon: 'format-image', kategori: 'common', nyckelord: [__ ('random'), __ bild]), redigera: funktion (rekvisita) returnera ( Slumpmässigt bildblock (redaktör)
); , spara: funktion (rekvisita) retur ( Slumpmässigt bildblock (främre änden)
); );Detta ställer in ramarna för vårt block och är ungefär som koden för blockplattformen som genereras av skapa-guten-blocket toolkit.
Vi börjar med att importera redigeringsbladet och framsidans stilark, och sedan tar vi ut några vanliga funktioner från wp.i18n och wp.blocks in i lokala variabler.
Inuti registerBlockType (), värden har angivits för titel, ikon, kategori, och nyckelord egenskaper, medan redigera och spara funktioner som just matar ut statiskt innehåll.
Lägg till det slumpmässiga bildblocket till en ny sida för att se produktionen som hittills genererats.
Se till att du fortfarande tittar på filer för ändringar så att alla blockkällkod (JSX, ES6 +, Sass, etc.) transpileras till giltigt JavaScript och CSS. Om du inte tittar på filer för ändringar, öppnar du ett kommandoradsfönster i my-custom-blocket plugin root mapp och skriv in npm start.
Du kanske undrar varför vi inte behövde lägga till någon PHP-kod för att skriva in ytterligare blockskript. Blockskript för my-custom-blocket blocket är enkodad via init.php, men vi behöver inte skicka skript specifikt för vårt nya block, eftersom det här tas hand om för oss av skapa-guten-blocket.
Så länge vi importerar vår huvudsakliga blockfil till src / blocks.js (som vi gjorde ovan) behöver vi inte göra något extra arbete. Alla JSX, ES6 + och Sass-kod kommer automatiskt att sammanställas i följande filer:
Dessa filer innehåller JavaScript och CSS för alla block, så endast en uppsättning filer måste skrivas in, oberoende av antalet block skapade!
Vi är nu redo att lägga till lite interaktivitet i vårt block, och vi kan göra det genom att först lägga till ett attribut för att lagra bildkategorin.
attribut: kategori: typ: 'sträng', standard: 'natur'
Detta skapar ett attribut som heter kategori, som lagrar en sträng med ett standardvärde på 'natur'. Vi angav inte en plats i markeringen för att lagra och hämta attributvärdet, så speciella HTML-kommentarer kommer att användas istället. Detta är standardbeteendet om du släpper bort en attributkälla.
Vi behöver något sätt att ändra bildkategori, som vi kan göra via en välj nedrullningskontroll. Uppdatera redigera funktion till följande:
redigera: funktion (rekvisita) const attribut: category, setAttributes = rekvisita; funktion setCategory (händelse) const selected = event.target.querySelector ('option: checked'); setAttributes (category: selected.value); event.preventDefault (); lämna tillbaka ( Aktuell kategori är: category ); Så här ser det ut:
Det här är helt annorlunda än det föregående statiska redigera funktion, så låt oss springa igenom förändringarna.
Först har vi lagt till en vald nedrullningskontroll med flera alternativ som matchar de bildkategorier som finns på PlaceIMG-webbplatsen.
När nedrullningsvärdet ändras, ändras setCategory funktionen heter, vilken hittar den aktuella valda kategorin och sedan kallas den setAttributes fungera. Detta är en grundläggande Gutenberg-funktion och uppdaterar ett attributvärde korrekt. Det rekommenderas att du bara uppdaterar ett attribut med den här funktionen.
Nu när en ny kategori väljs uppdateras attributvärdet och skickas tillbaka till redigera funktion, som uppdaterar utmatningsmeddelandet.
Vi måste slutföra ett sista steg för att få den slumpmässiga bilden att visas. Vi måste skapa en enkel komponent som tar i den aktuella kategorin och matar ut en
Den begäran vi behöver göra till PlaceIMG är av formuläret: https://placeimg.com/[width]/[height]/[category]
Vi håller fast bredden och höjden för nu, så vi behöver bara lägga till den aktuella kategorin på slutet av begäran URL. Till exempel, om kategorin var 'natur' då skulle den fullständiga begäran URL vara: https://placeimg.com/320/220/nature.
Lägg till en RandomImage komponent ovan registerBlockType ():
funktionen RandomImage (category) const src = 'https://placeimg.com/320/220/' + category; lämna tillbaka;
För att använda den, lägg bara till den i redigeringsfunktionen och ta bort det statiska utmatningsmeddelandet. Medan vi är på det, gör samma för spara funktionen.
Hela index.js filen ska nu se ut så här:
// Importera CSS. importera "./style.scss"; importera "./editor.scss"; const __ = wp.i18n; const registerBlockType, query = wp.blocks; funktionen RandomImage (category) const src = 'https://placeimg.com/320/220/' + category; lämna tillbaka); , spara: funktion (rekvisita) const attribut: category = rekvisita; lämna tillbaka (
Slutligen (för nu) lägg till följande stilar till editor.scss för att lägga till en färgad kant runt bilden.
.wp-block-cgb-block-slumpmässig bild select padding: 2px; marginal: 7px 0 5px 2px; gränsstråle: 3px;
Du behöver också några stilar i style.css.
.wp-block-cgb-block-slumpmässig bild bakgrund: # f3e88e; färg: #fff; gränsen: 2px solid # ead9a6; gränsstråle: 10px; vaddering: 5px; bredd: -webkit-fit-innehåll; bredd: -moz-fit-innehåll; bredd: passform-innehåll img border-radius: arv; gräns: 1px prickad # caac69; display: rutnät;
När sidan uppdateras i redigeraren eller på framsidan visas en ny slumpmässig bild.
Om du ser samma bild som visas om och om igen kan du göra en hård uppdatering för att förhindra att bilden visas i webbläsarens cacheminne.
I den här handledningen har vi täckt en hel del mark. Om du har gjort det hela vägen, ge dig en välförtjänt klapp på baksidan! Gutenberg block utveckling kan vara mycket roligt, men det är definitivt utmanande att förstå varje koncept vid första exponeringen.
Längs vägen har vi lärt oss hur vi ska betrakta blockskript och stilar och täckte registerBlockType () fungera djupt.
Vi följde upp detta genom att sätta teorin i bruk och skapa ett anpassat block från början för att visa en slumpmässig bild från en viss kategori med hjälp av PlaceIMGs webbtjänst.
I nästa och sista delen av denna handledningsserie lägger vi till fler funktioner i vårt slumpmässiga bildblock via inställningspanelen i blockinspektören.
Om du har följt med denna handledning och bara vill experimentera med koden utan att skriva in allt, kan du ladda ner finalen my-custom-blocket plugin i nästa handledning.
