Handledning: Skapa ett skjutreglage som ett dynamiskt Gutenberg-block

Denna handledning kommer att gå igenom hur man skapar ett dynamiskt WordPress Gutenberg-block. Slutresultatet är ett reglage som visar utvalda bilder från valda kategoriinlägg. Koden inkluderar användning av en högre ordningskomponent (withSelect) för att hämta alla kategorier i blockredigeraren.

Vad vi ska göra

Blocket renderar ett enkelt skjutreglage med jQuery Cycle2- skriptet. Men du kan använda vilket annat reglageskript som helst. Blocket kommer inuti editorn att återge en lista över alla kategorier så att användaren kan välja en kategori. När blocket visas i frontend kommer det dynamiskt att hämta inlägg från den valda kategorin och visa deras utvalda bilder som bilder. Denna handledning kommer att hålla det ganska enkelt så att du kan expandera och justera på din reglage som du vill.

Jag har valt att inte rendera bildspelet i redigeraren. Vanligtvis skulle du se till att renderingen i editor och frontend är densamma. Men i fallet med ett reglage gillar jag att hålla det enkelt för att inte spränga användaren med konstanta animationer i redigeraren.

Blocket kommer bara att ha två inställningar; valet av kategori och antalet bilder (inlägg). Jag rekommenderar att du lägger till fler inställningar som bildhastighet, inställningar för visning av piller, pilar, text och andra typiska reglageinställningar. Det borde vara ganska enkelt att lägga till dessa inställningar själv.

All kod är skriven i Javascript ES6 / ES2015+. Tänk på att den här koden behöver Babel för att transformera och bygga de slutliga Javascript-filerna. Kolla in guiden nedan om du inte vet hur.

Ställ in filerna

I det här exemplet skapar vi blocket i ett tema. I temamappen har jag en undermapp ‘ gutenberg/‘ där jag har placerat mina package.jsonoch webpack-config.js. Inuti undermappen ‘ src/‘ i den här mappen placerar jag alla mina byggfiler. Min webpack-konfiguration är inställd för att placera byggfilerna i min temaundermapp ‘ assets/js/‘.

Skapa en ny tom källfil i theme-folder/gutenberg/src/block-slider.jsoch ställ in Webpack för att skapa byggfilen till theme-folder/assets/js/block-slider.js. Du kan ändra platserna och/eller filnamnen hur du vill, kom bara ihåg att justera koden nedan.

Vi måste också ladda ner det nödvändiga skjutskriptet. Du kan ladda ner Cycle2 på den här länken, eller så kan du använda något annat bildskript och justera koden nedan. Jag placerar jquery.cycle2.min.jsfilen i min temamapp /assets/js/.

Jag kommer också att förbereda en liten CSS-fil som endast kommer att laddas i editor. Vi bara en liten bit av styling för att göra kategorin välja optimal. Jag skapar en tom fil editor-block-slider.cssoch placerar den i theme-folder/assets/css/.

Slutligen går vi till en PHP-fil som laddas i temat. För enkelhetens skull gör jag PHP-delen i temats functions.php.

Registrera Gutenberg-blocket i PHP

Alla Gutenberg-block måste vara registrerade med [register_block_type](https://developer.wordpress.org/reference/functions/register_block_type/)(). Jag föredrar att kalla det inuti en funktion kopplad till init. Den första parametern är ditt blocknamn inklusive namnutrymme. Jag har bestämt mig för att kalla mitt reglageskript awp/slider(justera som du vill). Det andra argumentet är en rad argument.

Inom samma funktion kommer jag att registrera byggskriptet med [wp_register_script](https://developer.wordpress.org/reference/functions/wp_register_script/)()och registrera min editor CSS-fil med [wp_register_style](https://developer.wordpress.org/reference/functions/wp_register_style/)(). Båda dessa handtag kommer att läggas till som argument till ‘ editor_script‘ respektive ‘ editor_style‘. När det gäller beroenden har jag lagt till några av de mest grundläggande paketen för skriptet för att säkerställa att vårt blockskript laddas i rätt ordning. När det gäller redigeringsstilen wp-edit-blocksär att använda ‘ ‘ ett bra beroende för att undvika att dina stilar åsidosätts.

Och slutligen eftersom detta är ett dynamiskt block, måste vi också lägga till render_callbackargumentet ‘ ‘, som pekar på en funktion som är ansvarig för att rendera blocket i frontend.

Slutligen definierar vi renderingsfunktionen. Vi får två parametrar till funktionen callback; en uppsättning attribut från blocket och det inre innehållet (används inte i detta block). Jag kommer helt enkelt att lämna tillbaka ett dummysnöre. Vi kommer tillbaka och utvecklar renderingsfunktionen senare. Kom ihåg att returnera en sträng, inte eko.

function awp_gutenberg_slider_render($attributes, $content) {
    return 'Slider render comes here.';
}

Vi kommer tillbaka till PHP-renderingsfunktionen i slutet av denna handledning. Nu är det dags att gå vidare till Javascript!

Registrera ett anpassat Gutenberg-block i Javascript

Låt oss öppna vår block-slider.jskällfil. Vid det här laget startar jag skriptet (npm run start) för att omvandla allt vi gör i den här filen till byggfilen när vi går. Vi måste registrera blocket med [registerBlockType](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/)(). Kolla in länken för att se alla möjliga argument.

Som vi bestämde oss i register_block_type()PHP heter vårt block awp/slider. Vi vill också lägga till två attribut till blocket, som tidigare nämnts: ett för det valda term-ID och ett för antalet bilder.

Jag gillar att lägga till blockjusteringsfunktionen också. Det kommer att läggas till automatiskt genom att lägga till ‘ align‘ till supportsobjektet. Om du vill ha alla blockjusteringar kan du helt enkelt ställa in aligntill sant. Men ett vänster- eller högerjusterat skjutreglage är inte så meningsfullt så jag kommer att definiera de specifika typerna av blockjusteringar som detta block stöder: "Align center" (‘ center‘), "Wide width" (‘ wide‘) och " Full width" (‘ full‘). För att definiera en standardjustering och göra den tillgänglig från PHP lägger jag till ‘ align‘ som attribut till vårt block.

Jag ställer in blockets editargument till en separat komponent som vi skapar härnäst. Och slutligen savereturnerar funktionen helt enkelt null, eftersom detta är ett dynamiskt block.

Vi måste definiera komponenten för editfastigheten. Innan registreringskoden definierar jag en funktionskomponent BlockEditsom helt enkelt återger a divoch a Placeholdermed lite dummytext.

[Placeholder](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/placeholder)är en trevlig komponent för att rendera ett område för inställningar – och inte nödvändigtvis för ett blocks faktiska rendering. Inuti Placeholderkomponenten återger vi en lista med termer att välja mellan.

Vid det här laget borde vårt block vara tillgängligt i WordPress Gutenberg! Låt oss skapa ett nytt inlägg, lägga till ett nytt block och hitta vårt block i kategorin Common. Så här ser vårt block ut just nu:

Lägger till Inspector-inställningar

Låt oss lägga till några inställningar i Inspektören (redigerarens högra sidofält). Som nämnts har vårt block bara en inställning; antal bilder. Det är här jag rekommenderar att du lägger till fler inställningar för ditt reglageblock. Kom ihåg att registrera attribut för varje inställning du lägger till.

För att lägga till något till inspektören använder vi komponenten [InspectorControls](https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/inspector-controls)( ). wp.blockEditorInuti renderar vi en [PanelBody](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/panel#panelbody)( wp.components) för att lägga till en ny hopfällbar sektion. Sedan renderar vi helt enkelt en [RangeControl](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/range-control)( wp.components) för att skapa en inmatningsinställning för att välja antalet bilder. Vi sätter minimum till 1 och maximum till 10. Vi kopplar händelsen valueoch till attributet .onChange``numSlides

Med ovanstående kod bör vi nu få en snygg sektion med en intervallreglage för att ställa in antalet bilder.

Återigen, jag rekommenderar att du leker med att lägga till fler inställningar till din reglage. Nästa steg är att skapa elementet för att rendera en lista med kategorier att välja mellan.

Skapa en kategorivalskomponent

För att hålla vår kod snygg och återanvändbar, låt oss skapa kategoriväljarkomponenten i en separat fil. Inuti build-mappen skapar jag en ny fil awp-category-picker.js.

Inuti den här filen definierar vi en komponent som går igenom alla kategorier för närvarande i WordPress, och renderar dem på något sätt. För att få kategorier måste vi linda in den i en så kallad högre ordningskomponent, som kommer att förse vår komponent med det vi behöver via rekvisita. För att göra detta kommer vi att använda [withSelect](https://developer.wordpress.org/block-editor/packages/packages-data/#withSelect). Inuti withSelectkan vi göra en begäran om att hämta alla kategorier i WordPress genom att använda butiksväljaren [select](https://developer.wordpress.org/block-editor/packages/packages-data/#select)(). Vi kan använda:

för att hämta alla termer inom den angivna taxonomisnigeln. Om du inte är bekant med komponenter och väljare av högre ordning i WordPress Gutenberg, har jag ett inlägg som förklarar detta koncept mer detaljerat: Skapa ett anpassat Gutenberg-block – Del 10: Hämta inlägg och komponenter med högre ordning.

Eftersom vi behöver exportera en komponent från den här filen, placerar vi kombinationen av withSelectoch vår definierade komponent vid export defaultsatsen. Vår CategorySelectkomponent returnerar helt enkelt en div med lite dummytext så att vi kan se att det fungerar. Den withSelectbör tillhandahålla rekvisitan ‘ terms‘ till CategorySelect. Jag har lagt till en console.log()på denna rekvisita så att vi kan se att det fungerar.

Det sista vi behöver göra är att faktiskt importera och använda denna kategoriväljarkomponent i vårt anpassade block.

Tillbaka in block-slider.jsmåste vi först importera komponenten överst i filen. Och inuti vår Placeholderkomponent renderar vi helt enkelt ut komponenten.

Med ovanstående kod bör ditt block nu rendera div från CategorySelectkomponenten. Om du öppnar konsolen i din webbläsare bör du också se några loggar. Kom ihåg att det withSelectär en asynkfråga, vilket betyder att den kan återges flera gånger. Första gången/er rekvisiten är null. Men den eller de sista loggarna bör sluta med en rad kategoritermer.

Bra! Låt oss fortsätta att arbeta med vår CategorySelectkomponent och få den att faktiskt återge listan med termer så att användaren kan välja en!

Återger en lista med termer att välja mellan

Det finns många sätt att rendera en lista med val där användaren kan välja ett objekt. Om du vill ha något riktigt enkelt kan du göra en standardvalsrullgardinsmeny ([SelectControl](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/select-control)). Det är helt upp till dig. Jag har valt ett renare och snyggare tillvägagångssätt genom att använda [MenuGroup](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/menu-group)( wp.components) och [MenuItem](https://github.com/WordPress/gutenberg/tree/master/packages/components/src/menu-item)( wp.components).

Inuti en MenuGroupkomponent måste vi gå igenom props.termsarrayen, och för varje objekt vill vi visa en MenuItemkomponent som återger termens namn. Och naturligtvis vill vi bara rendera detta om det props.termsfaktiskt innehåller något (async request, minns du?).

Jag har gett MenuGroupkomponenten en anpassad klass, eftersom vi måste rikta in oss på detta med CSS. Och jag har ställt in rekvisitan rolepå MenuItem‘ menuitemradio‘ för att se till att bara en kan väljas åt gången. Som standard fungerar de som kryssrutor, vilket gör att flera objekt kan väljas.

Med ovanstående kod bör vårt block nu (efter en liten sekund) rendera en snygg lista över alla kategorier i din WordPress-instans.

Du kanske märker att vårt block kommer att utökas till att innehålla alla kategorier. Om vi ​​är i en WordPress-instans med många kategorier blir detta snabbt ett problem. Vi vill se till att väljaren är en behållare med maxhöjd som får en vertikal rullningslist om det finns många kategorier. Det är här vår CSS-fil kommer in.

Lägg till i vår editor-block-slider.cssfil:

.awp-categoryselect div {
    max-height: 200px;
    overflow: hidden scroll;
    border: 1px solid #b3bcc0;
}

Denna CSS riktar sig till det inre divi vårt MenuGroupoch ser till att det aldrig blir högre än 200px. Om innehållet MenuGroupblir större (fler kategorier) kommer det att visa en vertikal rullningslist. Detta är det absoluta minimum av CSS för vårt block, men du kan naturligtvis lägga till mer CSS om du vill.

Det sista vi behöver fixa i vår kategoriväljare är funktionen för att visa det aktuella valda objektet, och att låta användaren välja en term från listan. För detta måste vi skicka några rekvisita till den här komponenten från vårt block.

I block-slider.jsmåste vi skicka den aktuella valda termen (värdet av attributet termId) och en funktion för att uppdatera den valda termen (setAttributes) som rekvisita till vår kategoriväljarkomponent.

I ovanstående kod på rad #6definierar vi en funktion som helt enkelt uppdaterar attributet termId. Vi skickar detta funktionsnamn som prop till CategorySelectat line #17. Och vid raden #16passerar vi det aktuella värdet av termId. Med kan vi uppdatera vår CategorySelectkomponent för att återspegla det valda objektet och låta användaren faktiskt välja en term.

Tillbaka i awp-category-picker.jslägger vi till några nya rekvisita på MenuItem. Vi återkommer trueeller falseför rekvisitan isSelectedom det aktuella term-ID är detsamma som det nuvarande valda. Vi initierar selectTermfunktionen i onClickhändelsen, passerar termen ID. Och för att göra det valda objektet visuellt lägger vi villkorligt till en ikon före varje objekt.

Med detta bör vår kategoriväljare se ut så här:

Listan ska tydligt markera den valda termen med en bockikon, och du kan klicka på valfri term för att välja den termen istället.

Det var allt för redaktören och Javascript-delen! Det som återstår nu är frontend-renderingen, vilket vi kommer att göra i PHP.

Rendera det dynamiska blocket i PHP

Innan vi dyker in i renderingsfunktionen låt oss ta hand om några saker först.

Först måste vi ställa cycle2-skriptet i kö i frontend så att vår reglagekod faktiskt förvandlas till en reglage. Det gör vi med en enkel funktion kopplad till wp_enqueue_scripts. Justera nedan om du valde ett annat reglageskript.

add_action('wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'cycle2-slider-js', 
        get_template_directory_uri(). '/assets/js/jquery.cycle2.min.js', 
        ['jquery'], 
        '', 
        true
    );
});

För det andra vill vi återgå till register_block_type()funktionsanropet. När vi hanterar dynamiska block bör vi definitivt lägga till ett nytt argument; attributes. I det här argumentet definierar vi alla attribut som vi har definierat registerBlockTypei Javascript, inklusive deras standardvärden. Om vi ​​inte gör det kommer inte alla attribut att vara tillgängliga i vår återuppringning. Om ett attribut lämnades oförändrat i blockredigeraren, kommer attributet och dess värde inte att vara tillgängliga i attributmatrisen i PHP. Så jag rekommenderar att du alltid ser till att lägga till attributesarrayen i PHP- register_block_type()funktionen när du arbetar med dynamiska block. För vårt block skulle det se ut så här:

Nu återgår vi till vår callback-renderingsfunktion awp_gutenberg_slider_render(). Utdata är helt upp till dig, särskilt om du har valt att använda ett annat reglageskript. Nedanstående är ett enkelt exempel.

Huvudtanken är att vi kontrollerar om en term har valts eller inte ($attributes['termId']). Om den är ifylld skapar vi ett [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/)()med argument för antalet inlägg ($attributes['numSlides']) och valt kategori-ID. Sedan gäller det att skapa rätt HTML för att cykel2 ska fungera, gå över inläggen och visa deras utvalda bilder som diabilder.

Notera hur jag lägger till rätt blockjusteringsklass i rad #12. Resultatet bör vara ett skjutreglage av de utvalda bilderna. Tänk på att detta är ett grundläggande exempel som har vissa brister. Till exempel hämtar vi de tre sista inläggen från den valda kategorin. Men förutsatt att en av dem inte har en utvald bild, kommer reglaget bara att visa två inlägg.

Det viktiga att komma ihåg är att returnera en sträng och inte eka den. Jag rekommenderar också att du använder någon form av mallfunktionalitet i ditt tema för dynamiska blockrenderingar som dessa. Det kan snabbt bli rörigt att fixa och bygga HTML som en sträng.

Slutord

Den här handledningen har visat dig hur du skapar ett anpassat dynamiskt WordPress Gutenberg-block där du renderar dess frontend-innehåll i PHP. Och du har sett hur du använder komponenten med högre ordning för withSelectatt fråga efter alla kategoritermer och en metod för att visa en valbar lista.

All kod ovan är skriven så enkelt som möjligt. Jag har bara lagt till det absoluta minimum av inställningar. Reglaget fungerar men vanligtvis vill du ha mer – till exempel att göra bildlänkarna, visa titlar från inläggen, skjutpilar eller möjligheten att anpassa hastigheten eller andra skjutreglageinställningar. Tanken är att visa dig grunderna och göra det enkelt för dig att utöka, bygga vidare på och ändra för att passa ditt projekts behov.