Skapa och hämta anpassade REST-slutpunkter i Gutenberg-block

I det här inlägget ska jag försöka skapa en översikt över hur man skapar anpassade REST API-slutpunkter och utför förfrågningar för dem i ett anpassat Gutenberg-block. Det vill säga att göra förfrågningar med fetchmetoder för information som inte finns i WordPress registrerade datalager.

En vänlig påminnelse: den mesta grundläggande informationen finns redan i WordPress datalager. Till exempel är grundläggande förfrågningar av inlägg, sidor, anpassade inläggstyper, taxonomier, författare, media och mer tillgängliga i befintligt skick utan att behöva skapa dina egna anpassade slutpunkter. För att komma åt dessa butiker använder du hellre WordPress kärndatamodul (withSelectoch select()). Nedan finns en handledningsdel som går på djupet om hur man gör det.

WordPress REST API

Om du inte redan visste; WordPress REST API är ett JSON-gränssnitt för att skicka och ta emot data från din WordPress-webbplats. Den kan användas externt eller internt. Med Gutenberg-redigeraren och bytet till Javascript har användningen av REST API definitivt ökat. WordPress REST API har en hel massa slutpunkter som vi kan använda. Se en fullständig referens om alla REST API-slutpunkter här. Du hittar till exempel slutpunkter för inlägg och det mesta annat internt innehåll – både för läsning och uppdatering. Tema- eller plugin-utvecklare kan registrera sina egna anpassade slutpunkter.

Din WordPress-webbplats har en root REST API URL, som standard finns på <your domain>/wp-json. Till exempel kan en lokal WordPress med URL http://localhost/wordpress/komma åt REST API på http://localhost/wordpress/wp-json. Därifrån måste vi lägga till slutpunkter. Med hänvisning till ovanstående referens för slutpunkter kan vi hämta en lista över senaste inlägg i slutpunkten /wp/v2/posts. Det betyder att om du går till http://localhost/wordpress/wp-json/wp/v2/postsi din webbläsare får du ett JSON-formaterat svar på de senaste inläggen på din WordPress-webbplats.

En notering om namnrymder är på sin plats. En REST API-URL börjar med ett namnområde (‘ wp/v2‘ är WordPress’ namnområde som visas i exemplet med webbadresser ovan). Namnutrymmen är ett koncept för att undvika sammandrabbningar i kärnan i WordPress, teman och plugins som lägger till slutpunkter med samma namn. Skapa ditt eget unika namnområde – vanligtvis en snigelform av ditt tema- eller pluginnamn. Efter slug är en allmän regel att lägga till versionsnumret, normalt från v1. Som ett exempel är mitt temas slug ‘ awhitepixel‘, så om jag skulle skapa anpassade slutpunkter i mitt tema skulle jag använda namnområdet ‘ awhitepixel/v1‘. Med detta namnutrymme kunde jag registrera en slutpunkt ‘ posts‘ och det skulle inte orsaka några problem även om det är identiskt med WordPress’ slutpunktsnamn.

Att arbeta med REST API i WordPress är ett stort ämne med mycket bra information tillgänglig. I det här inlägget fokuserar jag på användbarhet i Gutenberg editor och hur man hämtar dem i Javascript.

Vad vi ska göra och vad vi behöver

Användbarheten för att begära anpassad information har ett brett utbud av användningsfall, så du behöver vanligtvis anpassa kodexemplen nedan för att passa dina behov. Data kan vara en anpassad post-fråga, en anpassad SQL-fråga eller något helt annat.

När vi skapar en anpassad slutpunkt har vi full kontroll över dess retur. Vi kan utföra alla typer av operationer och frågor i WordPress/PHP och skicka detta vidare som JSON. Och i vårt Gutenberg-block kommer vi att kunna hämta denna retur och göra vad vi vill med den inom blockets editfunktion. Vanligtvis skulle du använda data för att ge slutanvändaren ett val eller information i blockredigeraren, men du kan också lagra information från den i ditt block för vidare användning. Du kan också skapa dina egna anpassade butiker för denna data, men jag går inte in på hur man gör det.

Jag antar att du redan är bekant med hur man skapar anpassade Gutenberg-block så jag kommer inte att gå igenom detta i detalj här.

Skapa en REST API-slutpunkt

Registrering av en anpassad REST API-slutpunkt görs i PHP. Du skulle lägga till den här koden i ditt teman functions.phpeller en aktiv plugin-kod. Koppla en funktion till åtgärden rest_api_initoch kör funktionen [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()för varje slutpunkt du vill registrera.

Ange ditt namnområde som första parameter, din slutpunktsrutt som andra och en rad inställningar som tredje parameter till register_rest_route(). Den fjärde parametern styr om du vill åsidosätta en befintlig rutt eller inte; inte något vi ska titta på här. I arrayen för den tredje parametern bör du som minimum ställa in egenskapen ‘ callback‘ till en funktion som är ansvarig för att returnera slutpunktens data. Att ställa in ‘ method‘ är också vanligt, t.ex. att ställa in din slutpunkt på ‘ GET‘, ‘ POST‘, ‘ PUT‘ osv.

Låt oss börja med att registrera en enkel slutpunkt;

Mitt temas namnområde är ‘ awhitepixel/v1‘ och jag registrerar en slutpunkt ‘ mydata‘ inom detta namnområde. Det betyder att jag kan komma åt mitt anpassade REST API på http://localhost/wordpress/wp-json/awhitepixel/v1/mydata.

När du registrerar (eller ändrar) REST API-rutter måste du spola dina permalänkar för att det ska fungera. Du kan göra detta genom att gå till Inställningar > Permalänkar och helt enkelt klicka på Spara.

Ovanstående kod fungerar inte än, eftersom jag inte har definierat funktionsuppsättningen som callback: awhitepixel_rest_route_mydata. Återuppringningsfunktionen tar emot en parameter; en rad data med information och argument som skickas in från begäran. Slutligen måste du noga överväga återuppringningsfunktionens återkomst.

För det första måste du alltid returnera något från din slutpunktsuppringning. Alla returer kommer automatiskt att konverteras till JSON av WordPress. Det betyder att du kan returnera praktiskt taget alla former av data i din funktion; en sträng, null, en array eller [WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)instans. Du kan också välja att returnera ett [WP_REST_Response](https://developer.wordpress.org/reference/classes/wp_rest_response/)objekt för mer kontroll på t.ex. statuskod eller rubrikinformation. Jag rekommenderar att du lindar returen i funktionen [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)()för att säkerställa att ditt svar är ett giltigt REST-svar.

Låt oss definiera vår callback-funktion och returnera en enkel sträng som en början;

function awhitepixel_rest_route_mydata($data) {
    $response = 'Hello there!';
    return rest_ensure_response($response);
}

Med ovanstående kod (och tömda permalänkar) kan jag nu gå till URL:en http://localhost/wordpress/wp-json/awhitepixel/v1/mydata.

Härifrån kan vi lägga till vilken typ av kod som helst i vår återuppringningsfunktion för att generera korrekt data att returnera. Du kan fråga WordPress-innehåll med t.ex. [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/)göra frågor i databasen eller begära extern data. Den här delen är upp till dig.

Låt oss nu gå vidare till den motsatta sidan; hur man gör förfrågningarna.

Gör REST API-förfrågningar i Javascript

Att utföra REST-begäran görs vanligtvis med hjälp [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)av Javascript. WordPress tillhandahåller sitt eget omslag fetchsom förenklar WordPress REST API-förfrågningar; [wp.apiFetch](https://developer.wordpress.org/block-editor/packages/packages-api-fetch/). Detta är vad jag kommer att använda i mitt anpassade Gutenberg-block. Tänk på att en fetchbegäran returnerar ett "löfte" – så vi måste kedja ett .then()för att kunna hantera den faktiska förfrågningsreturen. Basanvändningen är ungefär så här;

apiFetchtillåter oss att tillhandahålla en pathegenskap istället för att bygga hela webbadressen. Allt vi behöver tillhandahålla är namnutrymmet och slutpunkten, och apiFetchkommer att lägga till detta till WordPress REST API rot-URL. Inuti .then()funktionen har vi tillgång till data som redan är konverterad till JSON. Det är här du skulle göra något med datan. Vanligtvis lagrar du returnerad data i t.ex. komponentens tillstånd.

Nedan är ett exempel på ett anpassat Gutenberg-blocks editkomponent. Den är klassbaserad för att kunna användas stateför att lagra returnerad data från REST API-begäran. Detta gör att vi också kan köra förfrågan componentDidMount()när den först monteras (se Reacts dokumentation om livscykelmetoder ). Allt detta ger ett enkelt exempel för att du ska förstå det grundläggande konceptet; inte som ett recept för att göra det exakt så här. Du kan överväga att använda React-krokar och funktionella komponenter eller konstruera en komponent av högre ordning istället.

Exemplet ovan är en klassbaserad komponent som levereras till blockets editfunktion i registerBlockType(). Den ställer in ett tillståndsobjekt för en array för att hålla data (detta beror så klart på vilken data du returnerar) och en status boolean för att veta när asynkbegäran har returnerats. När komponenten är monterad (renderad för första gången) kör den funktionen för att utföra apiFetchbegäran. Vi anger sökvägen till slutpunkten vi registrerade i PHP ovan. Metoden är som standard GET så vi behöver inte specificera detta i apiFetch. Och innefunktion .then()när förfrågan är klar uppdaterar vi komponentens tillstånd med returnerad data.

Uppenbarligen skulle ditt blocks renderingsfunktion göra mer med den returnerade datan i sig. Du kanske vill tillhandahålla data till användaren som på något sätt presenterar en lista att kanske välja mellan. Allt beror på vilken typ av data det är och vad du vill använda den till.

Överför argument till slutpunkten

I vissa fall måste vi föra några argument till slutpunkten. Vanliga användningsområden är att skicka ett ID efter endpoint; skulle till exempel http://localhost/wordpress/wp-json/wp/v2/posts/14returnera post-ID 14.

Detta är ganska enkelt och görs genom att lägga till ett regex-sökmönster till slutpunkten när du registrerar det. Det kräver viss kunskap om regexes för att bygga komplexa mönster, men nedan är ett exempel som matchar ett nummer och tilldelar det namnet ‘id’. Att namnge matchningarna ger oss möjlighet att komma åt variabeln i vår callback-funktion. Låt mig visa dig vad jag menar.

Låt oss registrera en ny slutpunktsrutt. Vi använder samma slutpunkt som vi gjorde tidigare (‘ awhitepixel/v1/mydata‘) men för denna rutt lägger vi till en regexmatchning för ett nummer i slutet.

Regex-mönstret (?P<id>[d]+)verkar kryptiskt, men kommer att vara ganska tydligt med en viss grundläggande förståelse för regex. Delen [d]+matchar valfritt nummer (0-9) 1 eller flera gånger. Delarna (?P<id>och )är för att matcha en namngiven grupp. Gruppnamnet är i det här fallet id, men du kan namnge dina grupper vad du vill.

Du kan välja att styra denna slutpunkt till en separat återuppringningsfunktion, men jag har valt att använda samma funktion för att hantera både /mydataoch /mydata/<ID>förfrågningar. Det betyder att jag i min återuppringningsfunktion kan göra:

function awhitepixel_rest_route_mydata($data) {
    if ($data['id']) {
        $response = 'Create return for ID: '. $data['id'];
    } else {
        $response = 'Create general return (no ID provided)';
    }
    return rest_ensure_response($response);
}

Kom ihåg att parametern till callback-funktionen innehåller de returnerade argumenten. Eftersom jag döpte min matchade grupp till ‘ id‘ kommer det matchade värdet att vara tillgängligt i $data['id']. Och slutligen eftersom jag använder samma funktion för att hantera förfrågningar med och utan ID kan jag enkelt växla mellan de två olika returerna.

Med detta (och uppdaterade permalänkar) kommer jag att få dessa svar för mina anpassade slutpunkter: