I den här delen kommer vi att skriva Javascript för att registrera och konfigurera vårt anpassade block. I slutet kommer vi att registrera skriptet med PHP och göra den nödvändiga PHP-koden för att WordPress ska känna igen det som ett nytt block.
Först en snabb notering om hur du kommer åt WordPress Gutenbergs funktioner och komponenter.
Det globala wppaketet och destrukturering
När vi är i en Javascript-fil i kö i Gutenberg-editorn har vi tillgång till ett globalt objekt/paket: wp. Detta är ett mycket, varierande stort Javascript-objekt och det innehåller en hel massa användbara komponenter och funktioner som vi kommer att använda för att skapa block. När du skriver Javascript för anpassade block kommer du att referera till wpen hel del.
Därför är det vanligt, både i modernt Javascript och i React, att destrukturera det vi vill använda ur det. I grund och botten betyder det bara att vi definierar lokala variabler från delar av en större struktur. Till exempel är den första funktionen vi kommer att använda registerBlockType()som finns inom wp.blocks. Vi skulle kunna anropa funktionen så här:
wp.blocks.registerBlockType();Men det är lättare att destrukturera det så här:
const { registerBlockType } = wp.blocks;
registerBlockType();Nu kan du referera till funktionen direkt utan att prefixa den med dess struktur. Det blir mycket mer användbart när vi hänvisar till funktioner eller komponenter som vi kommer att upprepa ofta.
Vi kommer att göra omstruktureringar i den här serien, och när vi går vidare i handledningen kommer vi att se hur mycket mer läsbar och kortare vår kod blir.
Registrerar ett nytt block
Funktionen för att registrera ett nytt anpassat block registerBlockType()finns i wp.blockspaketet. Den accepterar två parametrar; först en sträng med blockets namnutrymme och namn, och sedan ett objekt med den fullständiga blockkonfigurationen.
Gutenberg förväntar sig att alla block ska ha ett namnutrymme och ett namn, definierade med ett snedstreck däremellan. Namnutrymmet är för att säkerställa att ditt blocknamn inte kommer i konflikt med några andra block som kan använda samma namn. Alla block i WordPress använder namnutrymmet core. Till exempel har standardstyckeblocket i WordPress namnet core/paragraph. Om du väljer ett annat namnområde kan du också skapa ett block med namnet stycke utan att orsaka några problem.
Bestäm ett namnutrymme i slug-version som är unikt för dig. Jag kommer att använda namnutrymmet awp(kort version av A White Pixel) i den här serien.
Öppna källfilen vi skapade i det sista steget; src/block-awhitepixel-myfirstblock.js, i en redaktör. Först ringer vi registerBlockTypefrån destrukturerad wp.blocks, med namnet awp/firstblock. Justera ditt namn och namnutrymme allt eftersom.
const { registerBlockType } = wp.blocks;
registerBlockType('awp/firstblock', {
// Your block configuration and code here
});I den andra parametern, blockkonfigurationsobjektet, måste vi definiera några egenskaper för att det ska kunna registreras framgångsrikt. Kom ihåg att blockkonfigurationen är ett objekt, vilket innebär att du måste skriva allt som nyckel + värdepar, separerade med kommatecken. Det finns en hel del möjliga konfigurationsegenskaper så låt oss gå igenom dessa så ser vi den slutliga koden i slutet.
Obligatorisk: titel
Den första nödvändiga egenskapen är title. Detta är namnet som det kommer att visas när du väljer mellan block. Ställ in den här egenskapen som vilket namn du vill ha i en sträng.
Vi lägger till följande som en titel:
title: 'My first block',PS: Vi kommer att återkomma till hur vi skriver alla strängar i vårt block för att säkerställa att de kan översättas i del 8. Men för nu ska vi hålla det enkelt och helt enkelt skriva strängar.
Obligatorisk: kategori
Egenskapen categorydefinierar var i vilken blockkategori ditt block kommer att visas när du väljer block för infogning i editorn. Möjliga värden är common, formatting, layout, widgets, embed.
Låt oss lägga det i common, den första blockkategorin.
category: 'common',Valfritt: ikon
Om du har använt Gutenberg har du förmodligen märkt att alla block har ikoner. Du kan lägga till en ikon i ditt block med antingen en sträng som hänvisar till någon av WordPresss Dashicons, eller så kan du tillhandahålla ett anpassat svgelement.
Jag väljer bara en av WordPresss dashikoner, smileyen – men du kan välja vilken du vill. Observera att du hoppar över att inkludera "dashicons-" i ditt ikonklassnamn.
icon: 'smiley',Valfritt: beskrivning
Du kan ge en beskrivning som kommer att visas i sidofältet Inställningar (på höger sida) när blocket är aktivt.
Jag lägger bara till en snabb text som exempel:
description: 'Learning in progress',Valfritt: sökord
Gutenberg stöder en sökfunktion vid val av blocktyper. Du kan tillhandahålla en mängd möjliga matchningar i fastigheten keywords. Utan keywordsskulle du bara hitta ditt block genom att söka på dess namn.
Jag lägger till exampleoch test, så att vi enkelt kan hitta vårt anpassade block när vi börjar skriva ett av dessa sökord.
keywords: ['example', 'test'],Valfritt: attribut
Egenskapen attributesär en mycket viktig egenskap som vi kommer att återkomma till ganska ofta i den här handledningsserien. Det är här du lagrar din strukturerade data och användarindata för ditt block. Du kan föreställa dig det som variabler. Vi kommer inte att lägga till det för nu, men vi kommer definitivt att återkomma till det här ganska snart.
(Sorts) krävs: redigera och valfritt: spara
Inom editoch saveegenskaper är faktiskt där du kommer att lägga till all din kod för både redaktörsutdata och frontend-rendering. Båda dessa egenskaper förväntar sig en funktion som bör returnera viss utdata.
Egenskapen editbeskriver strukturen för ditt block i editorn. Fastigheten savehanterar i princip två saker; din blockutgång i frontend, men också strukturen för hur ditt block sparas i databasen. Du kommer att arbeta mestadels i editeftersom det är här du lägger till ingångar för att mata in eller välja saker och uppdatera blockets data. Funktionen saveska inte uppdatera eller redigera data på något sätt, den ska bara matas ut.
Gutenberg måste kunna rekonstruera ditt block med alla dess inställningar i editorn från det som matas ut i savefunktionen (och attributen). Om Gutenberg någonsin öppnar ett inlägg där den tidigare sparade blockutgången skiljer sig (även bara något) från vad som definieras i save, kommer ditt block att bli ogiltigt.
Jag kan garantera dig att du kommer att stöta på detta mycket när du utvecklar anpassade block. När detta händer måste du ta bort blocket (från prickarna i verktygsfältet) och lägga till det igen. Jag rekommenderar också att göra en webbläsaruppdatering (F5 eller CTRL+R).
WordPress har en dedikerad dokumentationssida för blockets redigerings- och sparafunktioner om du vill lära dig mer.
När det gäller vårt första block, låt oss skriva ut något grundläggande. Vi kommer att returnera samma sak för både editoch save; ett ":)" insvept i <div>. Blockets ikon är trots allt en smiley.
Övriga fastigheter
Det finns fler valfria egenskaper för registerBlockType; parent, supports, transforms, example, och styles. Vi hoppar över dessa för nu eftersom de flesta är för mer avancerad eller anpassad blockbyggnad. Om du är intresserad av att läsa mer om dessa, ta en titt på WordPress dokumentation.
Slutlig registerblockkod
Vår kod ser nu ut ungefär så här.
Med detta har vi tillräckligt för att vårt block ska kunna registreras som ett anpassat block. Låt oss se det i praktiken i Gutenbergs redaktör.
Kom du ihåg att kompilera ditt Javascript? I föregående steg lärde vi oss att vi inte kan ladda den här Javascript-filen i Gutenberg; vi behöver den kompilerade versionen. Du brukar utvecklas med npm run startatt springa i bakgrunden, eller så kan du bara springa npm run builden gång nu. Det borde kompilera vårt käll-Javascript och placera det var du än definierade det för att placeras och namnges i din webpack.config.js.
PHP-delen av att registrera ett block
För varje block måste du registrera Javascript-filen och detta är precis som du skulle registrera alla andra skript i WordPress – genom att använda [wp_register_script](https://developer.wordpress.org/reference/functions/wp_register_script/)(). Observera att vi registrerar skriptet, inte ställer det i kö. Detta beror på att vi också måste anropa en PHP-funktion för att registrera varje anpassat block, och den funktionen är ansvarig för att ställa skriptet i kö när det behövs.
Jag föredrar att behålla Gutenberg-relaterad kod i en separat fil i mina teman. Men du kan, och vi kommer att i den här handledningen, helt enkelt skriva all PHP-kod direkt inuti temat functions.phpför enkelhetens skull.
Jag rekommenderar att du använder initkroken för din funktion, och inte enqueue_block_assets. Vi kan lägga både registrering av skriptet och registrering av blocket tillsammans.
PHP-funktionen vi kommer att använda för att registrera ett nytt block är [register_block_type](https://developer.wordpress.org/reference/functions/register_block_type/)(). På samma sätt som Javascript registerBlockType()accepterar den två parametrar; blockets namnområde och namn, och en array med argument. Se till att du anger exakt samma namnutrymme och namn i PHP som i Javascript.
I det andra argumentet finns det några möjliga argument (av vilka några kommer vi tillbaka till senare i den här serien). Men det viktigaste är editor_scriptvar du tillhandahåller handtaget (första parametern av wp_register_script()) för det registrerade skriptet.
Och det är allt!
Vårt block i Gutenberg editor
Nu när du uppdaterar din editor i något inlägg bör du hitta vårt block – antingen genom att öppna Gemensam kategori eller genom att söka efter något av nyckelorden eller namnet du angav.
Vårt block återger ett enkelt ":)" både i editorn och i frontend. Från och med nu kan du inte redigera något i blocket, men det är vad vi kommer att lära oss i nästa steg!