Skapa ett inställningsgränssnitt för ett anpassat WordPress-block

Hittills har vi täckt hur man arbetar med data från ett externt API i ett anpassat WordPress-block. Vi gick igenom processen hämtar den datan för användning på gränssnittet av en WordPress-webbplats och hur man gör det rendera det direkt i WordPress Block Editor när du placerar blocket i innehållet. Den här gången ska vi överbrygga dessa två artiklar genom att ansluta till blockredigerarens kontrollpanel för att skapa ett inställningsgränssnitt för blocket vi skapade.

Du känner till kontrollpanelen jag syftar på, eller hur? Det är den panelen till höger som innehåller post- och blockinställningar i blockredigeraren.

Ser du det rödmarkerade området? Det är kontrollpanelen. Ett styckeblock är för närvarande valt och inställningarna för det visas i panelen. Vi kan ändra stilar, färg, typografi... ett antal saker!

Tja, det är precis vad vi gör den här gången. Vi kommer att skapa kontrollerna för inställningarna för fotbollsrankningsblocket som vi arbetade med i de två senaste artiklarna. Förra gången gjorde vi en knapp i vårt block som hämtar extern data till fotbollsrankingen. Vi kände redan till webbadressen och slutpunkterna vi behövde. Men vad händer om vi vill hämta ranking för ett annat land? Eller kanske en annan liga? Vad sägs om data från en annan säsong?

Vi behöver formulärkontroller för att göra det. Vi skulle kunna använda interaktiva React-komponenter — som Reagera-Välj — för att bläddra igenom de olika API-alternativen som är tillgängliga för att analysera dessa data. Men det finns inget behov av det eftersom WordPress levereras med ett gäng kärnkomponenter som vi hakar direkt in i!

Smakämnen dokumentation för dessa komponenter — kallas InspectorControls — blir bättre i Handbok för WordPress Block Editor. Det kommer att bli ännu bättre med tiden, men under tiden har vi också det WordPress Gutenberg sagobok och WordPress Gutenberg-komponenter webbplatser för ytterligare hjälp.

API-arkitekturen

Innan vi hakar på något är det en bra idé att kartlägga vad det är vi behöver i första hand. Jag har kartlagt strukturen för RapidAPI-data vi hämtar så att vi vet vad som är tillgängligt för oss:

Säsonger och länder är två slutpunkter på toppnivå som mappas till en ligans slutpunkt. Därifrån har vi resten av data som vi redan använder för att fylla i rankningstabellen. Så vad vi vill göra är att skapa inställningar i WordPress Block Editor som filtrerar data efter säsong, land och liga och sedan skickar den filtrerade informationen till rankningstabellen. Det ger oss möjligheten att släppa blocket på valfri WordPress-sida eller inlägg och visa varianter av data i blocket.

För att få ställningen måste vi först få ligorna. Och för att få ligorna måste vi först få länderna och/eller säsongerna. Du kan se de olika slutpunkterna i RapidAPI-instrumentpanelen.

Det finns olika kombinationer av data som vi kan använda för att fylla i rankningarna, och du kanske har en preferens för vilken data du vill ha. För den här artikelns skull kommer vi att skapa följande alternativ i blockinställningspanelen:

• Välj land
• Välj Liga
• Välj Säsong

Sedan har vi en knapp för att skicka in dessa val och hämta relevant information och skicka dem till rankningstabellen.

Ladda och lagra en lista över länder

Vi kan inte välja vilket land vi vill ha data för om vi inte har en lista över länder att välja mellan. Så vår första uppgift är att ta en lista över länder från RapidAPI.

Det ideala är att hämta listan över länder när blocket faktiskt används i sidan eller inläggets innehåll. Det finns ingen anledning att hämta något om blocket inte används. Tillvägagångssättet är väldigt likt det vi gjorde i den första artikeln, skillnaden är att vi använder en annan API-slutpunkt och olika attribut för att lagra listan över returnerade länder. Det finns andra WordPress-sätt att hämta data, som api-hämta, men det är utanför ramarna för vad vi gör här.

Vi kan antingen inkludera landslistan manuellt efter att ha kopierat den från API-data, eller så kan vi använda ett separat API eller bibliotek för att fylla i länderna. Men API:et vi använder har redan en lista över länder, så jag skulle bara använda en av dess slutpunkter. Låt oss se till att den första landslistan laddas när blocket infogas på sidan eller postar innehåll i blockredigeraren:

// edit.js
const [countriesList, setCountriesList] = useState(null);

useEffect(() => {
  let countryOptions = {
    method: "GET",
    headers: {
      "X-RapidAPI-Key": "Your Rapid API key",
      "X-RapidAPI-Host": "api-football-v1.p.rapidapi.com",
    },
  };
  fetch("https://api-football-v1.p.rapidapi.com/v3/countries", countryOptions)
    .then( (response) => response.json() )
    .then( (response) => {
      let countriesArray = { ...response };
      console.log("Countries list", countriesArray.response);
      setCountriesList(countriesArray.response);
    })
  .catch((err) => console.error(err));
}, []);

Vi har en tillståndsvariabel för att lagra listan över länder. Därefter ska vi importera en komponent från @wordpress/block-editor paket kallas InspectorControls det är där alla komponenter vi behöver för att skapa våra inställningskontroller finns.

import { InspectorControls } from "@wordpress/block-editor";

Paketets GitHub repo gör ett bra jobb med att förklara InspectorControls. I vårt exempel kan vi använda det för att styra API-datainställningar som Country, League och Season. Här är en förhandsvisning så att du får en uppfattning om användargränssnittet vi gör:

Och när dessa val är gjorda i blockinställningarna använder vi dem i blockets Edit fungera:

  { countriesList && (
    
  )}

Här ser jag till att vi använder villkorlig rendering så att funktionen bara laddar komponenten efter listan över länder är laddad. Om du undrar över det LeagueSettings komponent, det är en anpassad komponent som jag skapade i en separat components undermapp i blocket så att vi kan ha en renare och mer organiserad Edit funktion istället för hundratals rader med landsdata att hantera i en enda fil.

Vi kan importera det till edit.js fil så här:

import { LeagueSettings } from "./components/LeagueSettings";

Därefter skickar vi de nödvändiga rekvisita till LeagueSettings komponent från föräldern Edit komponent så att vi kan komma åt tillståndsvariablerna och attributen från LeagueSettings barnkomponent. Vi kan också göra det med andra metoder som Kontext-API för att undvika propellborrning, men det vi har just nu är perfekt för det vi håller på med.

De andra delarna av Edit funktion kan också omvandlas till komponenter. Till exempel kan ligaställningskoden läggas in i en separat komponent - som kanske LeagueTable.js — och sedan importerade precis som vi importerade LeagueSettings i Edit funktion.

Inuti LeagueSettings.js fil

LeagueSettings är precis som en annan Reaktionskomponent från vilken vi kan destrukturera rekvisitan från den överordnade komponenten. Jag kommer att använda tre tillståndsvariabler och ytterligare en leagueID stat eftersom vi ska extrahera ID:t från league objekt:

const [country, setCountry] = useState(null);
const [league, setLeague] = useState(null);
const [season, setSeason] = useState(null);
const [leagueID, setLeagueID] = useState(null);

Det första vi ska göra är att importera PanelBody komponent från @wordpress/block-editor-paketet:

import { PanelBody } from "@wordpress/block-editor";

...och inkludera det i vår return fungera:

Det finns andra paneltaggar och attribut — Det är bara min personliga preferens att använda dessa. Ingen av de andra krävs... men titta på alla komponenter vi har tillgängliga för att göra en inställningspanel! Jag gillar enkelheten i PanelBody för vårt användningsfall. Den expanderar och kollapsar för att avslöja rullgardinsinställningarna för blocket och det är allt.

På tal om det, vi har ett val att göra för dessa val. Vi skulle kunna använda SelectControl komponent eller a ComboBoxControl, som dokumenten beskriver som "en förbättrad version av en SelectControl, med tillägget att man kan söka efter alternativ med hjälp av en sökingång." Det är trevligt för oss eftersom listan över länder kan bli ganska lång och användare kommer att kunna antingen göra en sökfråga eller välja från en lista.

Här är ett exempel på hur en ComboboxControl skulle kunna fungera för vår landlista:

 handleCountryChange(value) }
  onInputChange={ (inputValue) => {
    setFilteredCountryOptions(
      setupCountrySelect.filter((option) =>
        option.label
          .toLowerCase()
          .startsWith(inputValue.toLowerCase())
      )
    );
  }}
/>

Smakämnen ComboboxControl är konfigurerbar i den meningen att vi kan tillämpa olika storlekar för kontrollens etikett och värden:

{
  value: 'small',
  label: 'Small',
},

Men vår API-data finns inte i den här syntaxen, så vi kan konvertera countriesList array som kommer från den överordnade komponenten när blocket ingår:

let setupCountrySelect;

setupCountrySelect = countriesList.map((country) => {
  return {
    label: country.name,
    value: country.name,
  };
});

När ett land väljs från ComboboxControl, ändras landsvärdet och vi filtrerar uppgifterna därefter:

function handleCountryChange(value) {
  // Set state of the country 
  setCountry(value); 

  // League code from RapidAPI
  const options = {
    method: "GET",
    headers: {
      "X-RapidAPI-Key": "Your RapidAPI key",
      "X-RapidAPI-Host": "api-football-v1.p.rapidapi.com",
    },
  };

  fetch(`https://api-football-v1.p.rapidapi.com/v3/leagues?country=${value}`, options)
    .then((response) => response.json())
    .then((response) => {
      return response.response;
    })
    .then((leagueOptions) => {
      // Set state of the league variable
      setLeague(leagueOptions);

      // Convert it as we did for Country options
      setupLeagueSelect = leagueOptions.map((league) => {
        return {
          label: league.league.name,
          value: league.league.name,
        };
      });
      setFilteredLeagueOptions(setupLeagueSelect);
    })
  .catch((err) => console.error(err));
}

Observera att jag använder ytterligare tre tillståndsvariabler för att hantera ändringar när landsvalet ändras:

const [filteredCountryOptions, setFilteredCountryOptions] = useState(setupCountrySelect);
const [filteredLeagueOptions, setFilteredLeagueOptions] = useState(null);
const [filteredSeasonOptions, setFilteredSeasonOptions] = useState(null);

Hur är det med de andra inställningsalternativen?

Jag kommer att visa koden som jag använde för de andra inställningarna, men allt det gör är att ta hänsyn till normala fall medan jag definierar fel för specialfall. Till exempel kommer det att finnas fel i vissa länder och ligor eftersom:

• det finns ingen tabell för vissa ligor, och
• vissa ligor har ställning men de är inte i en enda tabell.

Det här är inte en JavaScript- eller React-handledning, så jag låter dig hantera specialfallen för API:et som du planerar att använda:

function handleLeagueChange(value) {
  setLeague(value);
  if (league) {
    const selectedLeague = league.filter((el) => {
      if (el.league.name === value) {
        return el;
      }
    });

    if (selectedLeague) {
      setLeague(selectedLeague[0].league.name);
      setLeagueID(selectedLeague[0].league.id);
      setupSeasonSelect = selectedLeague[0].seasons.map((season) => {
        return {
          label: season.year,
          value: season.year,
        };
      });
      setFilteredSeasonOptions(setupSeasonSelect);
    }
  } else {
    return;
  }
}

function handleSeasonChange(value) {
  setSeason(value);
}

Skickar inställningsvalen

I sista artikel, gjorde vi en knapp i blockredigeraren som hämtar färsk data från API:et. Det finns inget mer behov av det nu när vi har inställningar. Tja, vi behöver det - bara inte där det är för närvarande. Istället för att ha det direkt i blocket som renderas i blockredigeraren, kommer vi att flytta det till vårt PanelBody komponent för att skicka in inställningsvalen.

Så in igen LeagueSettings.js:

// When countriesList is loaded, show the country combo box
{ countriesList && (
   handleCountryChange(value)}
    onInputChange={(inputValue) => {
      setFilteredCountryOptions(
        setupCountrySelect.filter((option) =>
          option.label
            .toLowerCase()
            .startsWith(inputValue.toLowerCase())
        )
      );
    }}
  />
)}

// When filteredLeagueOptions is set through handleCountryChange, show league combobox
{ filteredLeagueOptions && (
   handleLeagueChange(value)}
    onInputChange={(inputValue) => {
      setFilteredLeagueOptions(
        setupLeagueSelect.filter((option) =>
          option.label
            .toLowerCase()
            .startsWith(inputValue.toLowerCase())
        )
      );
    }}
  />
)}

// When filteredSeasonOptions is set through handleLeagueChange, show season combobox
{ filteredSeasonOptions && (
  
     handleSeasonChange(value)}
      onInputChange={
          (inputValue) => {
            setFilteredSeasonOptions(
              setupSeasonSelect.filter((option) =>
              option.label
              .toLowerCase()
              .startsWith(inputValue.toLowerCase()
            )
          );
        }
      }
    />

    // When season is set through handleSeasonChange, show the "Fetch data" button
    {
      season && (
         getData()}>Fetch data
      )
    }
    
  
)}

Här är resultatet!

Vi har det väldigt bra med vårt block. Vi kan rendera det i blockredigeraren och i framsidan av webbplatsen. Vi kan hämta data från ett externt API baserat på ett urval av inställningar vi skapat som filtrerar datan. Den är jävligt funktionell!

Men det finns en annan sak vi måste ta itu med. Just nu, när vi sparar sidan eller inlägget som innehåller blocket, återställs inställningarna vi valde för blockeringen. Med andra ord, dessa val sparas inte någonstans. Det finns lite mer arbete för att göra dessa val beständiga. Det är dit vi planerar att gå i nästa artikel, så håll utkik.