WordPress Gutenberg Block API Blockera och känna

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 hur du ska arbeta med Block API och skapa dina egna innehållsblock som du kan använda för att bygga dina inlägg och sidor.

I den första inlägget i den här serien hade vi en översikt över Block API och skapade ett enkelt block för testning. Vi kommer snart att titta på Block API, men först låt oss redigera standardblocket vi skapade i föregående inlägg för att få en känsla för hur enkelt det är att göra ändringar i ett befintligt block.

Om du kommer ihåg att vårt anpassade block gjordes annorlunda på fram- och baksidan för att visa att du har fullständig kontroll över hur blocket görs inuti redigeraren och hur besökare ser blocket.

Om du har följt längs så öppnar du / Wp-content / plugins / my-custom-block / src / blockera mapp där blockkoden finns. Den mappen innehåller en JavaScript-fil och två Sass-filer, som styr blockets beteende och hur det görs inom redigeraren och på framsidan.

De block.js JavaScript-filen innehåller JSX, som transpileras under byggprocessen i giltigt JavaScript. På samma sätt konverteras de två Sass-filerna till standard CSS.

Under byggprocessen kräver dessa filer bearbetning för att skapa distributionsfilerna i pluginens dist / mapp. Det här är de faktiska filerna som skrivs av WordPress, eftersom de innehåller giltig JavaScript och CSS som alla webbläsare kan förstå.

Lyckligtvis, den skapa-guten-blocket verktygslådan handlar om att bygga och transpilera för oss genom att titta på ändringar i våra blockfiler. Det här är en riktigt bra funktion eftersom det är en sak för oss att oroa oss för. Vi kan bara fokusera på att skriva vår blockkod (och stilar), och pluginfilerna uppdateras automatiskt. Trevlig!

Se bara till att du kör npm start kommando från inuti plugin-rotmappen för att utlösa filsökning.

Tid för att redigera någon kod!

Oroa dig inte för detaljerna i JSX-koden i block.js precis som vi kommer att täcka det i detalj senare. För tillfället, låt oss bara fokusera på att göra några enkla ändringar i blockutmatningen för fram- och bakänden.

Öppna block.js, hitta redigera metod för objektet som det andra argumentet passerat till registerBlockType (), och ersätt det med följande:

redigera: funktion (rekvisita) return ( 
 
Redigeringsvy
 
Detta är vårt eget block inuti redigeraren.
 
Låt oss lägga till en oorderad lista!
 
 
Äpple
 
Orange
 
Päron
 
Plommon
 
 
 ); ,

Denna metod styr hur blocket görs i redigeringsfönstret. Hitta nu spara metod och ersätt det med:

spara: funktion (rekvisita) retur ( 
 
Frontend View
 
Detta är vårt anpassade block som ses av besökare på webbplatsen.
 
Låt oss lägga till en ordnad lista!
 
 
Röd
 
Blå
 
Rosa
 
Brun
 
 
 ); ,

Denna metod används för att göra blockutmatningen på framänden.

I style.scss, Byt ut alla stilar med:

.wp-block-cgb-block-my-custom-block bakgrund: # a7d9f1; färg: #ffffff; gräns: 1px fast # 62afd4; gränsstråle: 15px; marginal: 0 auto; max bredd: 740px; vaddering: 1.5rem; ol, ul margin-left: 20px! important;  li margin-bottom: 0;  h3 färg: #ffffff; marginal-topp: 0; 

Sedan i editor.scss, Byt ut alla stilar med:

.wp-block-cgb-block-my-custom-block bakgrund: # cba7f1; gränsen: 1px solid # a170d6; 

Du kan se på skärmdumparna nedan hur dessa förändringar påverkar återgivningen av vårt block beroende på om vi tittar på det i redigeringsfönstret eller i främre delen.

Vi kommer inte att täcka enqueueing block script ännu, men det räcker för att nu veta det editor.scss Stilar tillämpas bara i redigeringsfönstret och style.scssläggs till både redaktörsfönstret och frontänden. Därför kan stilar som används både i redigeraren och frontänden utelämnas från style.scss.

Lägg märke till hur i Sass-filerna vi hänvisar till en lång CSS-väljare för att rikta våra blockelement.

.wp-block CGB block-my-custom-blocket

Denna klass läggs automatiskt av Gutenberg till blockbehållarelementet på framsidan, men vi måste tillämpa det manuellt i redigeringsfönstret för att få samma klass som du kan se i redigera metod nedan.

Klassnamnet som genereras av Gutenberg bestäms enligt följande: wp-block- [block namespace] - [block namn.

I vårt fall använde vi skapa-guten-blocket verktygslåda för att skapa vårt block, vilket använder cgb för namnrymden som standard och block my-custom-blocket baseras på det blocknamn som vi angav. Detta resulterar i CSS klassnamn wp-block CGB block-my-custom-blocket läggs till blockbehållaren. Namnrymden och blocknamnet används av Gutenberg internt för att unikt identifiera block.

När jag gjorde ändringar för att blockera filer där hittade jag ett par smärtpunkter som var värda att nämna.

För det första när man gör ändringar i redigera metod fann jag att jag måste rensa webbläsarens cache innan du uppdaterar redigeringsfönstret för att se de senaste ändringarna. Detta hände inte hela tiden, men det var ganska ofta fallet. Om du hittar detsamma som händer med dig, raderar du bara webbläsarens cache och försöker igen.

För det andra, när du redigerar innehållet i spara metod, något märkligt verkar hända med redigeringsfönstret när det nästa uppdateras.

För att visa detta lade jag till ett nytt listobjekt (

Indigo

) i spara metod och sedan uppdateras postredigeraren (efter att ha tvingat cachen igen, förstås!). Här är resultatet:

Om du väljer antingen Konvertera till block eller Redigera som HTML då får du presentera innehållet i spara metod, som är tänkt att ses på framsidan och inte i redigeraren.

Det här är väldigt förvirrande, och det enda uppenbara sättet att återgå till normalitet var att ta bort blocket från redigeringsfönstret och sätt tillbaka det igen. Som jag nämnde i föregående inlägg är Gutenberg fortfarande ett pågående arbete, och detta är ett bra exempel på det!

Förhoppningsvis kommer detta att bli mer intuitivt i framtida versioner, men för nu är det bara något att se upp för. När ändringar görs i spara funktion, var beredd att ta bort de relaterade blocken i redigeringsfönstret och lägg till dem igen.

Som tidigare nämnts har produktionen från spara och redigera metoder kan vara helt olika. Men i de flesta fall kommer du förmodligen att ha den främre änden för att matcha redigeringsutmatningen så att redigeringsupplevelsen är så konsekvent som möjligt med frontend-rendering.

I vårt övertygade exempel ovan har jag bara lagt till olika innehåll och stilar i redigeraren och front-end-visningen för demonstrationsändamål.

Blockera API-översikt

Block API består av en uppsättning JavaScript-objekt som läggs till globalt wp admin objekt. Och eftersom wp är global, behöver vi inte importera det specifikt i vår källkod, det är tillgängligt på begäran.

Föremålen finns i wp beror på administratörssidan du tittar på. Till exempel, om du anpassar din webbplats då wp innehåller det viktigaste anpassnings API-objektet. 

För närvarande är dock Gutenberg Block API endast tillgängligt på postredigeraren. Jag förutser att detta kommer att förändras i framtiden när integrationen mellan postredigeraren och webbplatsanpassaren rör sig närmare.

Du kan se strukturen på wp genom att öppna Gutenberg-redaktören och skriva in wp i webbläsarkonsolen.

Som du kan se, wp innehåller många objekt, men de som vi är mest intresserade av är:

• wp.elements
• wp.blocks
• wp.components
• wp.data
• wp.i18n

Dessa objekt ger dig tillgång till alla verktyg som behövs för att skapa några mycket komplexa block. Försök skriva sina fullständiga objektnamn i webbläsarkonsolen för att utforska dessa objekt ytterligare.

Om du till exempel skriver in wp.blocks och expandera objektet så ser du att en av de tillgängliga funktionerna är registerBlockType (). Det här är en mycket viktig funktion som vi kommer att täcka djupt i nästa post

De wp.elements Objekt

Detta objekt är abstraktionsskiktet ovanpå React (och ReactDom) som exponerar Reaktionalitet på ett förutsägbart och konsekvent sätt. Detta gäller även om det underliggande genomförandet ändras eller ändras helt.

Så länge gränssnittet förblir detsamma kommer plugins som interagerar med Block API inte att påverkas i framtiden.

De wp.blocks Objekt

Kärnfunktionen för att skapa ett block (registerBlockType ()) finns i wp.blocks tillsammans med andra funktioner som är nödvändiga för allmän blockhantering som:

• getBlockType ()
• getBlockContent ()
• getBlockAttributes ()
• hasBlockSupport ()
• isValidBlock ()

Detta objekt innehåller också en uppsättning återanvändbara block som du kan inkludera i dina egna block för att tillhandahålla funktionalitet utan extra kostnader. Dessa färdiga block som inte är färdiga kan påskynda blockutvecklingen dramatiskt, och vi kommer att använda vissa av dem i nästa inlägg när vi gräver vidare till block skapande.

Några av de tillgängliga är:

• justeringsverktygsfältet
• autoslutförande
• media uppladdare
• färgpalett
• rik textredigerare

De wp.components Objekt

De wp.components objekt innehåller även återanvändbara komponenter, men dessa är mer generiska och används vanligtvis för att skapa ytterligare UI-element i redigeringsfönstret, såsom kontrollpaneler för blockinställningar.

Dessa inkluderar:

• knapp
• checkbox
• kodredigerare
• streckikon
• datum Tid
• falla ner
• menyalternativ
• Radio knapp
• intervallkontroll

De wp.data Objekt

Datamodulen hanterar applikationstillstånd i Gutenberg-redigeraren, som innehåller lagring av inställningar för varje block. Vi tar en titt på olika sätt att lägga till inställningar i ett block i det sista inlägget i den här serien.

wp.data implementeras ovanpå Redux, så när Gutenberg slås samman med kärnan kommer vi inte bara ha tillgång till React utan även till en komplett centraliserad datalager som drivs av Redux! 

Objektet wp.i18n

Plugins och teman har lätt kunnat översätta PHP-strängar i flera år nu, och en liknande metod är också tillgänglig för att översätta strängar i JavaScript tack vare wp.i18n objekt. Det betyder att alla strängar som finns i ditt block - inklusive blocknamn, nyckelord och etiketter - kan översättas till vilket språk som helst.

Om du har använt de vanliga PHP-översättningsfunktionerna innan kommer du känna dig riktigt hemma eftersom processen är ungefär densamma. Jag tycker att detta är ett smart drag eftersom det kommer att uppmuntra utvecklare att aktivera strängöversättningar i sina block från början.

Inne i din blockkod är det enkelt att översätta en sträng som:

wp.i18n .__ ('Denna sträng är översättbar', 'text-domän');

Slutsats

I den här handledningen har vi implementerat ett grundläggande block och redigerat koden. Vi har också sett att vi har total kontroll över blockreferens och kan ha olika blockvyer i redigeraren jämfört med frontänden.

Redaktören har fortfarande vissa problem som kan överraska dig från tid till annan. Detta tjänar som en påminnelse om att Gutenberg fortfarande är i utveckling och kanske inte är redo att användas på produktionsplatser.

Slutligen slutade vi med en översikt över block API, som introducerar flera nya objekt på global wp JavaScript-objekt för att skapa och hantera block.

I nästa inlägg tar vi upp takten och skapar ett mer omfattande block. För att göra det ska vi utforska registerBlockType () fungera djupt. Vi kommer också att titta närmare på huruvida dina blockskript är korrekt.