Membuat UI Pengaturan untuk Blok WordPress Kustom

Sejauh ini, kami telah membahas cara bekerja dengan data dari API eksternal di blok WordPress kustom. Kami berjalan melalui proses mengambil data itu untuk digunakan di ujung depan dari situs WordPress, dan bagaimana caranya merendernya langsung di Editor Blok WordPress saat menempatkan blok di konten. Kali ini, kita akan menjembatani kedua artikel tersebut dengan menghubungkan ke panel kontrol editor blok untuk membuat UI pengaturan untuk blok yang kita buat.

Anda tahu panel kontrol yang saya maksud, bukan? Panel di sebelah kanan yang berisi pengaturan posting dan blokir di editor blok.

Lihat area yang disorot merah itu? Itu panel kontrolnya. Blok Paragraf saat ini dipilih dan pengaturannya ditampilkan di panel. Kita dapat mengubah gaya, warna, tipografi… beberapa hal!

Nah, itulah yang kami lakukan kali ini. Kami akan membuat kontrol untuk pengaturan blok Football Rankings yang kami kerjakan di dua artikel terakhir. Terakhir kali, kami membuat tombol di blok kami yang mengambil data eksternal untuk peringkat sepakbola. Kami sudah mengetahui URL dan titik akhir yang kami butuhkan. Tetapi bagaimana jika kita ingin mengambil peringkat untuk negara lain? Atau mungkin liga yang berbeda? Bagaimana dengan data dari musim yang berbeda?

Kami membutuhkan kontrol formulir untuk melakukan itu. Kita dapat menggunakan komponen React yang interaktif — seperti Bereaksi-Pilih — untuk menelusuri berbagai opsi API yang tersedia untuk mengurai data tersebut. Tapi tidak perlu untuk itu karena WordPress dilengkapi dengan banyak komponen inti yang langsung kami kaitkan!

Grafik dokumentasi untuk komponen ini — disebut InspectorControls - semakin baik di Buku Pegangan Editor Blok WordPress. Itu akan menjadi lebih baik dari waktu ke waktu, tetapi sementara itu, kami juga memilikinya Buku Cerita WordPress Gutenberg dan Komponen WordPress Gutenberg situs untuk bantuan tambahan.

Arsitektur API

Sebelum kita terhubung ke apa pun, ada baiknya memetakan apa yang kita butuhkan terlebih dahulu. Saya telah memetakan struktur data RapidAPI yang kami ambil sehingga kami tahu apa yang tersedia untuk kami:

Musim dan negara adalah dua titik akhir tingkat atas yang dipetakan ke titik akhir liga. Dari sana, kami memiliki sisa data yang sudah kami gunakan untuk mengisi tabel peringkat. Jadi, yang ingin kami lakukan adalah membuat pengaturan di Editor Blok WordPress yang memfilter data berdasarkan Musim, Negara, dan Liga, lalu meneruskan data yang difilter tersebut ke tabel peringkat. Itu memberi kami kemampuan untuk melepaskan blok di halaman atau posting WordPress mana pun dan menampilkan variasi data di blok tersebut.

Untuk mendapatkan klasemen, kita harus terlebih dahulu mendapatkan liga. Dan untuk mendapatkan liga, pertama-tama kita harus mendapatkan negara dan/atau musim. Anda dapat melihat berbagai titik akhir di dasbor RapidAPI.

Ada berbagai kombinasi data yang dapat kami gunakan untuk mengisi peringkat, dan Anda mungkin memiliki preferensi untuk data mana yang Anda inginkan. Demi artikel ini, kita akan membuat opsi berikut di panel pengaturan blok:

• Pilih Negara
• Pilih Liga
• Pilih Musim

Kemudian kami akan memiliki tombol untuk mengirimkan pilihan tersebut dan mengambil data yang relevan dan meneruskannya ke tabel peringkat.

Muat dan simpan daftar negara

Kami tidak dapat memilih negara mana yang kami inginkan datanya jika kami tidak memiliki daftar negara untuk dipilih. Jadi, tugas pertama kita adalah mengambil daftar negara dari RapidAPI.

Hal yang ideal adalah mengambil daftar negara saat blok tersebut benar-benar digunakan di halaman atau memposting konten. Tidak perlu mengambil apa pun jika blok tidak digunakan. Pendekatannya sangat mirip dengan apa yang kami lakukan di artikel pertama, perbedaannya adalah kami menggunakan titik akhir API yang berbeda dan atribut yang berbeda untuk menyimpan daftar negara yang dikembalikan. Ada cara WordPress lain untuk mengambil data, seperti pengambilan api, tapi itu di luar cakupan yang kami lakukan di sini.

Kami dapat menyertakan daftar negara secara manual setelah menyalinnya dari data API, atau kami dapat menggunakan API atau pustaka terpisah untuk mengisi negara. Tapi API yang kami gunakan sudah memiliki daftar negara, jadi saya hanya akan menggunakan salah satu endpointnya. Mari pastikan daftar negara awal dimuat saat blok dimasukkan ke halaman atau posting konten di editor blok:

// 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));
}, []);

Kami memiliki variabel negara untuk menyimpan daftar negara. Selanjutnya, kita akan mengimpor komponen dari @wordpress/editor blok paket disebut InspectorControls di mana semua komponen yang kita perlukan untuk membuat kontrol pengaturan kita berada.

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

Paketnya GitHub repo melakukan pekerjaan yang baik menjelaskan InspectorControls. Dalam contoh kami, kami dapat menggunakannya untuk mengontrol pengaturan data API seperti Negara, Liga, dan Musim. Berikut pratinjau agar Anda mendapatkan gambaran tentang UI yang kami buat:

Dan setelah pilihan itu dibuat dalam pengaturan blok, kami menggunakannya blok itu Edit fungsi:

  { countriesList && (
    
  )}

Di sini, saya memastikan bahwa kita menggunakan rendering bersyarat sehingga fungsinya hanya memuat komponen setelah daftar negara dimuat. Jika Anda bertanya-tanya tentang itu LeagueSettings komponen, itu adalah komponen khusus yang saya buat secara terpisah components subfolder di blok sehingga kita dapat memiliki lebih bersih dan lebih terorganisir Edit berfungsi alih-alih ratusan baris data negara untuk ditangani dalam satu file.

Kita dapat mengimpornya ke dalam edit.js file seperti ini:

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

Selanjutnya, kami meneruskan alat peraga yang diperlukan ke LeagueSettings komponen dari induknya Edit komponen sehingga kita dapat mengakses variabel status dan atribut dari LeagueSettings komponen anak. Kita juga dapat melakukannya dengan metode lain seperti API Konteks untuk menghindari pengeboran penyangga, tetapi apa yang kita miliki saat ini sangat cocok untuk apa yang kita lakukan.

Bagian lain dari Edit fungsi juga dapat diubah menjadi komponen. Misalnya, kode klasemen liga dapat dimasukkan ke dalam komponen terpisah — seperti mungkin LeagueTable.js - dan kemudian diimpor seperti yang kita impor LeagueSettings ke dalam Edit fungsi.

Di dalam LeagueSettings.js fillet

LeagueSettings adalah seperti yang lain Komponen React dari mana kita dapat merusak properti dari komponen induk. Saya akan menggunakan tiga variabel status dan tambahan leagueID negara karena kita akan mengekstrak ID dari league obyek:

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

Hal pertama yang akan kita lakukan adalah mengimpor file PanelBody komponen dari paket @wordpress/block-editor:

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

... dan memasukkannya ke dalam return fungsi:

Ada tag dan atribut panel lainnya - itu hanya preferensi pribadi saya untuk menggunakan yang ini. Tidak ada yang lain yang diperlukan… tapi melihat semua komponen kami telah tersedia untuk membuat panel pengaturan! Saya suka kesederhanaan dari PanelBody untuk kasus penggunaan kami. Itu mengembang dan menciut untuk mengungkapkan pengaturan dropdown untuk blok dan hanya itu.

Ngomong-ngomong, kita punya pilihan untuk membuat pilihan itu. Kita bisa menggunakan SelectControl komponen atau a ComboBoxControl, yang dijelaskan oleh dokumen sebagai “versi yang disempurnakan dari a SelectControl, dengan tambahan kemampuan untuk mencari opsi menggunakan input pencarian.” Itu bagus bagi kami karena daftar negara bisa sangat panjang dan pengguna akan dapat melakukan kueri penelusuran atau memilih dari daftar.

Berikut adalah contoh bagaimana a ComboboxControl dapat bekerja untuk daftar negara kita:

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

Grafik ComboboxControl dapat dikonfigurasi dalam arti bahwa kita dapat menerapkan ukuran yang berbeda untuk label dan nilai kontrol:

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

Tetapi data API kami tidak ada dalam sintaks ini, jadi kami dapat mengonversi countriesList array yang berasal dari komponen induk saat blok disertakan:

let setupCountrySelect;

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

Ketika sebuah negara dipilih dari ComboboxControl, nilai negara berubah dan kami memfilter data sesuai:

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));
}

Perhatikan bahwa saya menggunakan tiga variabel status lainnya untuk menangani perubahan saat pemilihan negara berubah:

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

Bagaimana dengan opsi pengaturan lainnya?

Saya akan menunjukkan kode yang saya gunakan untuk pengaturan lain tetapi yang dilakukannya hanyalah memperhitungkan kasus normal saat menentukan kesalahan untuk kasus khusus. Misalnya, akan ada kesalahan di beberapa negara dan liga karena:

• tidak ada klasemen untuk beberapa liga, dan
• beberapa liga memiliki klasemen tetapi mereka tidak berada dalam satu meja.

Ini bukan tutorial JavaScript atau React, jadi saya akan membiarkan Anda menangani kasus khusus untuk API yang akan Anda gunakan:

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);
}

Mengirimkan pilihan pengaturan

Dalam majalah artikel terakhir, kami membuat tombol di editor blok yang mengambil data baru dari API. Tidak perlu lagi sekarang karena kami memiliki pengaturan. Ya, kami memang membutuhkannya - tidak seperti saat ini. Alih-alih menempatkannya langsung di blok yang dirender di editor blok, kita akan memindahkannya ke milik kita PanelBody komponen untuk mengirimkan pilihan pengaturan.

Jadi, kembali 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
      )
    }
    
  
)}

Inilah hasilnya!

Kami berada di tempat yang sangat baik dengan blok kami. Kami dapat merendernya di editor blok dan ujung depan situs. Kami dapat mengambil data dari API eksternal berdasarkan pilihan setelan yang kami buat yang memfilter data. Ini sangat fungsional!

Tapi ada hal lain yang harus kita tangani. Saat ini, ketika kami menyimpan halaman atau posting yang berisi blok, pengaturan yang kami pilih untuk blok diatur ulang. Dengan kata lain, pilihan tersebut tidak disimpan di mana pun. Ada sedikit lebih banyak pekerjaan untuk membuat pilihan itu tetap ada. Di situlah kami berencana untuk pergi di artikel berikutnya, jadi pantau terus.