Lägg till en Custom Inspector Sidebar i WordPress Gutenberg med Post Meta

I den här handledningen kommer vi att undersöka hur man lägger till en anpassad sidofält till Inspector (höger sidofält) i WordPress Gutenberg. Inuti kommer vi att implementera ett fält kopplat till en postmeta. Allt är implementerat med Javascript, inuti Gutenberg-redigeraren, och är ett alternativ till att lägga till metaboxar på traditionellt sätt.

Se upp!

Det här är en handledning för att skapa din egen anpassade sidofält. Men om du är intresserad av att bara lägga till meta/inställningar till standardinspektörens sidofält ("Dokument"-fliken), har jag en handledning för exakt det:

Vad vi kommer att skapa

WordPress Gutenberg låter utvecklare skapa anpassade sidofält genom att skapa ett så kallat Javascript-plugin. (Inte att förväxla med traditionella WordPress-plugins). Genom att använda ett Javascript-plugin kan vi skapa ett nytt sidofält och även ansluta till menyn "Verktyg och alternativ".

Vi kommer att lägga till ett nytt menyalternativ i "Verktyg" som öppnar vårt anpassade sidofält. Innehållet i sidofältet är helt upp till dig, men jag ska gå igenom några exempel, inklusive hur man kopplar ett inläggsmetafält inuti det.

Konfigurera ditt Javascript

För den här handledningen kommer jag att skriva ES6/ESNext Javascript med JSX vilket betyder att vi måste ställa in en kompilator. Om du vill följa med och inte skriva ES5 Javascript måste du sätta upp en utvecklingsmiljö som kompilerar ditt Javascript allt eftersom. Om du inte är bekant med detta, följ mitt inlägg som förklarar hur du ställer in det här och kom sedan tillbaka hit.

Jag har ställt in min webpack.config.jsför att kompilera min Javascript-källfil till min temamapps /assets/js/sidebar-plugin.js. Den här kompilerade filen är vad vi behöver ställa i kö till Gutenberg-redigeraren. Medan jag skriver den här koden har jag startat runtime-kompilatorn som kompilerar om Javascript varje gång jag sparar ändringar i källkoden (npm run start). Allt detta förklaras ingående i den tidigare nämnda handledningen.

Jag skriver detta i ett tema, men det fungerar likadant i ett plugin. Kom bara ihåg att justera sökvägarna när du lägger till skriptet i editorn.

Lägger till skriptet i redigeraren

För att lägga till vårt skript till Gutenberg-redigeraren måste vi skriva lite PHP. Om du är i ett tema, functions.phpär ett bra ställe att börja, eller någonstans i dina plugin-filer. Observera att vi måste lägga till det slutliga kompilerade skriptet, inte källkoden. I mitt exempel finns det kompilerade Javascriptet i min temamapps /assets/js/sidebar-plugin.js.

Vi skapar en funktion kopplad till enqueue_block_editor_assets. Inuti gör vi som vanligt [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)(). Som beroenden till skriptet lägger vi till två; wp-plugins, och wp-edit-post. Dessa två paket måste laddas före vårt skript eftersom vi använder funktioner från dem.

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script('awp-sidebar-plugin', get_stylesheet_directory_uri(). '/assets/js/sidebar-plugin.js', ['wp-plugins', 'wp-edit-post']);
});

Eftersom vi ställer skriptet i kö i kroken enqueue_block_editor_assetskommer vårt skript bara att laddas när Gutenberg-redigeraren är aktiv. Bra! Nu är allt klart för att skriva vårt Javascript-plugin.

Registrera ett Javascript-plugin

Det första steget är att registrera ett plugin. Det gör vi med [registerPlugin](https://github.com/WordPress/gutenberg/tree/master/packages/plugins#registerPlugin)funktionen i wp.plugins inifrån wp.pluginspaketet.

Som parameter till registerPlugin tillhandahåller vi ett namn (se till att det är unikt) och ett objekt med inställningar. Som ett minimum måste du tillhandahålla en komponent för render-egenskapen. Du kan också valfritt lägga till en ikon från WordPresss dashcons. Tänk på att om du inte anger en ikon kommer den att falla tillbaka till plugin-ikonen. I demonstrationssyfte använder jag 'carrot'ikonen.

När det gäller komponenten börjar vi med att definiera en grundläggande komponent som returnerar en enkel div med lite slumpmässig text i. Och före all kod destrukturerar vi funktionerna från de paket vi vill använda.

Om inget händer (inte ens fel) när du uppdaterar Gutenberg är vi alla redo. Vi ser inte vår komponent eftersom vi inte har berättat för WordPress var den ska renderas. Nästa steg är att ansluta till den anpassade sidofältsmenyn och verktygsmenykomponenterna för att rendera våra saker.

Registrera ett anpassat sidofält

Men först en förklaring i hur Gutenberg hanterar anpassade sidofält och varför vi behöver göra vad vi ska göra. När vi lyckas registrera en anpassad sidofält kommer en sak att hända automatiskt initialt. Gutenberg kommer att lägga till en genväg till vårt sidofält i det övre verktygsfältet, bredvid menyn Verktyg. Detta händer eftersom vår sidofält automatiskt blir "fäst".

Problemet med att bara lägga till en anpassad sidofält är att alla användare kan "lösgöra" denna genväg. När de gör det finns det ingen åtkomstpunkt för att öppna sidofältet igen! Det är därför vi också måste lägga till ett menyalternativ till menyn Verktyg.

Registrering av ett anpassat sidofält görs med komponenten PluginSidebarfrån wp.editPostpaketet. Att lägga till ett menyalternativ till menyn Verktyg görs med den passande namngivna komponenten PluginSidebarMoreMenuItem(också i wp.editPostpaketet).

För PluginSidebarkomponenten måste vi tillhandahålla några rekvisita. Du bör tillhandahålla minst nameoch title. Rekvisiten titleär självförklarande, det här är namnet som kommer att visas överst i sidofältet. I rekvisitan nameger en unik snigel. När du lägger till menyalternativet måste du referera till denna snigel.

Att lägga till en PluginSidebarMoreMenuItem(verktygsmeny) komponent kräver minst en rekvisita; target. Här anger du samma namn som du gav i sidofältets namerekvisita. Som innehåll i komponenten skriver du texten som kommer att visas som menyalternativ. Vanligtvis skulle detta vara detsamma som sidofältets title.

Eftersom React kräver en enda omslagsnod runt komponentens retur, lindar vi in ​​allt inuti en Fragmentkomponent (från wp.elementpaketet). Jag lindar också in mina strängar __()från wp.i18npaketet för att möjliggöra översättning.

Med ovanstående kod kommer vi att få följande två (mest troligt tre) saker att hända. Du kommer att få en morotsikongenväg i verktygsfältet (om du inte har lossat den ännu). Om du klickar på detta öppnas sidofältet. Du kommer också att ha fått ett nytt menyalternativ till sidofältet i Verktygsmenyn, under rubriken "Plugins".

Lägger till innehåll i sidofältet

Det faktiska innehållet i sidofältet är helt upp till dig. Du behöver bara lägga till HTML eller komponenter inuti PluginSidebarkomponenten med vad du vill (i stället för texten "Hej där.").

Du kanske märker att innehållet i sidofältet saknar utfyllnad. Detta är avsiktligt eftersom tanken är att du ska skapa paneler inuti den här sidofältet. Paneler är de hopfällbara sektionerna i Gutenbergs normala sidofält. Det är komponenter som du mycket enkelt kan lägga till i ditt anpassade sidofält. Du kan lägga till så många paneler som du vill och de är bra för att gruppera olika saker.

Lägger till paneler i vår sidofält

Låt oss snabbt titta på hur vi kan lägga till paneler i vår sidofält. Om du har skapat dina egna anpassade blocktyper kanske du är bekant med dessa komponenter. Vi använder PanelBodyoch valfritt PanelRowfrån wp.componentspaketet.

För en PanelBodykomponent tillhandahåller du som minimum rekvisitan title. Du kan valfritt ange sant eller falskt till initialOpenrekvisiten för att avgöra om panelen ska utökas som standard eller inte. Som innehåll inuti komponenten är allt inuti panelen.

Inuti en PanelBodykan du valfritt använda PanelRowkomponenter. De är egentligen inte nödvändiga men kan hjälpa dig att få en bra styling för ditt panelinnehåll.

Låt oss till exempel lägga till två paneler i vår anpassade sidofält.

Med den här koden börjar vår anpassade sidofält verkligen se ut som om den hör hemma i Gutenberg!

Lägga till inläggsmetafält i det anpassade sidofältet

Nu börjar vi verkligen gå in på de användbara sakerna för en anpassad sidofält; lägga till inställningar och lagra deras värden. Men först måste vi förstå hur.

Det är väldigt enkelt att lägga till inställningsfält (indata, kryssrutor, växlingsfält, etc) i sidofältet genom att använda de färdiga att använda komponenterna i WordPress-paketen. Men vi måste överväga hur vi ska lagra värdena. Det uppenbara alternativet är att lagra dem som post-meta. Men att ansluta en inställning till ett postmetafält kräver lite extra kod. Mer specifikt behöver vi använda så kallade högre ordningskomponenter för att hämta och uppdatera postmeta inuti Javascript. Vi måste också registrera varje inläggsmeta med PHP och göra dem tillgängliga för REST API.

För att avsluta denna handledning kommer jag att visa hur man lägger till en postmeta med nyckel awp_my_custom_metasom ska lagras som antingen sant eller falskt. I sidofältet kommer det att visas som ett växlingsfält (en sann/falsk komponent).

Registrera inläggsmeta för REST API

Det första steget för att lägga till postmeta i vår Javascript-fil är att registrera dem och definiera dem som tillgängliga i REST API. För att göra detta återgår vi till PHP igen.

Inuti en funktion kopplad till inithandlingen använder vi [register_meta](https://developer.wordpress.org/reference/functions/register_meta/)()funktionen. Som parametrar måste vi definiera objekttypen som ‘ post‘ eftersom vi använder den som postmeta (det utesluter inte t.ex. sidposttyp). Vi tillhandahåller meta-nyckeln och sedan en rad argument. Det kritiska att lägga till i argumentarrayen är att ställa in ‘ show_in_rest‘ till true. Post-meta används vanligtvis som ‘ single‘ (tänk hur du använder get_post_meta()). Vi definierar också type. När det gäller vårt fall ställer vi in ​​den på ‘ boolean‘.

Med denna kod är awp_my_custom_metapostmetafältet tillgängligt från Gutenberg. Du måste upprepa register_meta()för varje inläggsmeta du vill lägga till i sidofältet.

Låt oss nu återgå till vårt Javascript.

Lägger till en inställning i vårt sidofält

Låt oss börja med den enkla delen: Lägga till input till vår sidofält. Senare kommer vi att lägga till mer kod för att faktiskt koppla inställningsfältet till postmeta. På grund av hur vi måste göra detta, definierar vi en separat ny komponent för vår inställning. Så inuti panelen som du vill lägga till dina inställningar, ringer du helt enkelt denna nya komponent.

Låt oss kalla komponenten CustomSidebarMetaComponent(du kan kalla den något som är relevant för ditt projekt). Inuti den här komponenten vill vi rendera ett växlingsfält. För att göra detta använder vi ToggleControlkomponenten från wp.componentspaketet. Som rekvisita till ToggleControl tillhandahåller vi en passande etikett i titlerekvisitan. En ToggleControl behöver också rekvisita onChangeför att uppdatera värdet och checkedför det aktuella värdet. Vi kommer att utelämna dessa två för nu tills nästa steg.

Med ovanstående kod bör du få ett växlingsfält i sidofältet. Den är avmarkerad och ingenting händer när du klickar på den. Det är nästa steg: koppla den till vår postmeta.

Åtkomst till postmeta med withSelect och withDispatch

För att komma åt och uppdatera ett postmetavärde måste vi använda högre ordningskomponenter (HOC) för att komma åt WordPress version av butiker (liknande Redux). WordPress ger oss några användbara HOC med funktioner vi kan använda i wp.datapaketet.

Komponenten av högre ordning [withSelect](https://developer.wordpress.org/block-editor/packages/packages-data/#withSelect)är att förse vår komponent med rekvisita som, i vårt fall, hämtas från post-meta. Vi använder detta för att få värdet av vår postmeta. Inuti withSelectkan vi använda select('core/editor').getEditedPostAttribute('meta')för att hämta det aktuella inläggets meta.

Å andra sidan [withDispatch](https://developer.wordpress.org/block-editor/packages/packages-data/#withDispatch)är det en komponent av högre ordning som kan utföra åtgärder. I vårt fall vill vi uppdatera inläggets meta när motsvarande fältinställning ändras i vår sidofält. Inuti den här komponenten använder vi dispatch('core/editor').editPost()för att informera WordPress om att skicka en åtgärd. Inuti objektet vi tillhandahåller säger vi till WordPress att det är meta vi vill uppdatera.

Slutligen måste vi kombinera withSelectoch withDispatchmed vår komponent som hanterar post-metafältet (CustomSidebarMetaComponent). För att göra detta använder vi WordPress’ composefrån wp.composepaketet. Tanken är det withSelectoch withDispatchförser vår CustomSidebarMetaComponentkomponent med rekvisita. withSelecttillhandahåller värdet av postmeta som prop, och withDispatchtillhandahåller en funktion som vi kan anropa för att uppdatera värdet som prop. Vi ställer in dessa rekvisita på vårt ToggleField checkedoch onChange, motsvarande.

Det är mycket att förklara. Låt oss titta på den faktiska koden:

Låt oss börja från början. Som ligger längst ner. På line #36ändrar vi komponenten vi renderar i vår sidofält till den komponent vi skapade med compose(vid line #15). Komponenten CustomSidebarMetakommer att kombinera komponenterna withSelectoch withDispatchoch returnera CustomSidebarMetaComponent.

De CustomSidebarMetaComponentkommer att ha tillgång till customPostMetaValuerekvisitan från withSelect, och setCustomPostMetarekvisitan från withDispatchDessa två vi använder för checkedoch onChangerekvisita i ToggleField.

Observera att #5vi i rad lägger propstill som parametrar till komponenterna för att göra rekvisita tillgängliga i komponenten.

Slutsats och sista ord

Jag hoppas verkligen att denna handledning var till någon nytta för dig. Detta är vad jag lyckades förstå om ämnet under mycket försök och misstag. Det finns knappt någon dokumentation om detta ämne ännu. Jag kämpar fortfarande med detta, särskilt när det gäller att effektivt hantera flera inläggsmeta. Om jag lyckas lära mig några bra knep kommer jag definitivt att uppdatera den här handledningen!

Förhoppningsvis genom att följa denna handledning bör du ha kod som framgångsrikt lägger till en ny anpassad sidofält till WordPress Gutenberg-redigeraren, och förhoppningsvis med något meningsfullt innehåll och inställningar. Här är den sista koden för det anpassade sidofältet med postmetafält.