Gutenberg-lohkon vanhentaminen: Päivitä rikkomatta sisältöä

Yhteenveto

Gutenberg-lohkon päivittäminen rikkoo usein olemassa olevia viestejä, jotka käyttävät vanhaa versiota. Tämä artikkeli näyttää, miten käytät deprecated-ominaisuutta block.json-tiedostossa säilyttääksesi taaksepäin yhteensopivuuden. Opit tarkat vaiheet nykyisen lohkon merkinnän tallentamiseen, yhden tai useamman vanhentuneen version määrittelyyn ja attribuuttien oikeaan kartoitukseen. Käsittelemme sekä staattisia että dynaamisia lohkoja käytännön esimerkein. Artikkeli myös kyseenalaistaa oletuksen, että vanhentaminen on aina paras lähestymistapa, ja keskustelee tilanteista, joissa täysi katkaisu voi olla parempi. Lopuksi pystyt päivittämään lohkojasi luottavaisesti rikkomatta käyttäjiesi sisältöä.

Muutoksen aiheuttama ongelma

Loit puoli vuotta sitten mukautetun suosituslohkon. Se tuottaa yksinkertaisen <div>-elementin, jossa on lainaus ja kirjoittajan nimi. Nyt asiakas haluaa uuden ulkoasun: kirjoittajan pitäisi näkyä lainauksen yläpuolella eri CSS-luokalla. Päivität lohkon save-funktion ja render_callback-funktion. Testaat uudella viestillä – se näyttää hyvältä. Sitten navigoit vanhaan viestiin, joka käyttää lohkoa. Katastrofi: lainausteksti on kadonnut, kirjoittaja on väärässä paikassa ja tyyli on pielessä. Olet juuri rikkonut jokaisen sivun, joka käyttää lohkoa.

Tämä on klassinen "muutoksen aiheuttama ongelma" Gutenberg-lohkojen kehityksessä. Lohkot ovat pohjimmiltaan tietorakenteita yhdistettynä merkintään. Kun muutat merkintää, editori ei voi automaattisesti kartoittaa vanhaa sisältöä uuteen rakenteeseen. Tuloksena on joko validointivirhe (lohko muuttuu virheelliseksi) tai – pahempaa – hiljainen korruptio, jossa lohko renderöityy väärin.

Mikä on lohkon vanhentaminen?

Lohkon vanhentaminen on Gutenbergin sisäänrakennettu mekanismi versiomuutosten käsittelyyn. Määrittelemällä deprecated-taulukon lohkosi block.json-tiedostossa kerrot editorille: "Jos kohtaat lohkon, joka vastaa jotakin näistä vanhemmista versioista, muunna se nykyiseksi versioksi." Jokainen vanhentunut merkintä määrittelee aiemmat attributes, supports ja save-funktion (tai render_callback). Kun editori lataa vanhan lohkon, se käy vanhentuneet merkinnät järjestyksessä ja soveltaa ensimmäistä vastaavaa muunnosta.

Tätä ominaisuutta käytetään usein liian vähän, koska kehittäjät olettavat, etteivät he koskaan tarvitse muuttaa lohkon merkintää. Mutta todellisissa projekteissa vaatimukset muuttuvat. Jos ohitat vanhentamisen, pakotat käyttäjät joko poistamaan ja lisäämään lohkot uudelleen (huono kokemus) tai ylläpitämään kahta erillistä lohkoversiota (sotkuinen). Virallinen WordPress-kehittäjän käsikirja käsittelee tätä Lohkoeditorin käsikirjassa, mutta käytännön oppaat puuttuvat.

Vaihe 1: Tallenna nykyinen tila

Ennen kuin teet muutoksia, tallenna tarkka save-tuloste (tai render_callback dynaamisille lohkoille) ja attributes, joita lohkosi tällä hetkellä käyttää. Ajattele sitä tilannekuvan ottamisena. Staattisille lohkoille tallenna JSX, jonka save-funktio palauttaa. Dynaamisille lohkoille tallenna PHP-merkintä, jonka render_callback tuottaa.

Luo uusi tiedosto nimeltä deprecated.js (tai vastaava) ja tallenna vanha save-funktio sinne. Vaihtoehtoisesti pidä vanhentuneet versiot suoraan lohkon pää-JavaScript-tiedostossa. Tärkeintä on säilyttää tämä koodi täsmälleen sellaisena kuin se oli lohkon julkaisuhetkellä.

Vaihe 2: Määrittele vanhentuneet versiot

Lisää block.json-tiedostoon deprecated-taulukko. Jokainen merkintä on objekti, joka voi sisältää:

• attributes (objekti): Aiemmat attribuuttimääritykset.
• supports (objekti): Aiemmat tukiasetukset, jotka muuttuivat.
• save (funktio tai merkkijono): Aiempi save-funktio. JavaScript-pohjaisissa lohkoissa tuot vanhan funktion. PHP-renderöidyissä dynaamisissa lohkoissa voit käyttää migrate- ja render_callback-funktioita sen sijaan.
• migrate (funktio): Funktio, joka kartoittaa vanhat attribuutit uusiin (valinnainen).

Esimerkki:

"deprecated": [
  {
    "attributes": {
      "quote": { "type": "string", "source": "html", "selector": ".quote" },
      "author": { "type": "string", "source": "html", "selector": ".author" }
    },
    "supports": {},
    "save": "() => <div className=\"testimonial-legacy\"><p className=\"quote\">{attributes.quote}</p><p className=\"author\">{attributes.author}</p></div>"
  }
]

Huomautus: save-funktio block.json-tiedostossa määritellään tyypillisesti JavaScriptissä. Jos käytät ulkoista skriptiä, sinun täytyy enqueue-se se ja viitata funktion nimeen. Vaihtoehtoisesti voit kirjoittaa funktion merkkijonona (vaikka tätä ei suositella monimutkaisille lohkoille).

Vaihe 3: Kartoita attribuutit

Usein muutat paitsi merkintää myös attribuuttien nimiä tai lähteitä. Esimerkiksi saatat vaihtaa kirjoittajan tallentamisen tavallisesta merkkijonosta rich text -kenttään. Tällaisissa tapauksissa käytä migrate-ominaisuutta muuntaaksesi vanhat attribuutit uusiksi.

migrate: (attributes) => {
  return {
    quote: attributes.quote,
    author: { content: attributes.author, level: 2 }
  };
}

Jos et toimita migrate-funktiota, editori yksinkertaisesti välittää vanhat attribuutit suoraan uudelle lohkolle. Tämä saattaa aiheuttaa virheitä, jos attribuuttien nimet ovat muuttuneet.

Vaihe 4: Testaa oikealla sisällöllä

Kun olet määritellyt vanhentuneen version, testaa perusteellisesti. Luo uusi viesti, lisää vanha lohko (voit simuloida liittämällä serialisoidun lohkokoodin olemassa olevasta viestistä) ja varmista, että se muuntuu uudeksi versioksi ilman validointivirheitä. Testaa myös muunnetun lohkon muokkaamista ja tallentamista. Toista useille vanhentuneille versioille, jos niitä on.

Dynaamisille lohkoille prosessi on samanlainen, mutta siinä on ero: save-funktio dynaamiselle lohkolle palauttaa yleensä null (lohko renderöidään PHP:llä). Vanhentuneessa merkinnässä voit joko asettaa save-funktion aiempaan staattiseen merkintään, jota käytettiin ennen dynaamiseen renderöintiin siirtymistä, tai käyttää render_callback-funktiota PHP:ssä, joka käsittelee sekä vanhat että uudet attribuuttirakenteet. Tämä on monimutkaisempaa mutta mahdollista.

Varoitukset ja kompromissit

Vanhentaminen on tehokasta, mutta siinä on haittapuolia. Jokainen vanhentunut versio lisää koodia laajennukseesi. Ajan myötä saatat päätyä viiden tai kuuden peräkkäisen vanhan version ketjuun, joita käytetään harvoin mutta joita on ylläpidettävä. WordPressin ydintiimi suosittelee pitämään vähintään kaksi taaksepäin yhteensopivaa versiota, mutta tämän jälkeen voit harkita täyttä katkaisua, jos vaikuttavien viestien määrä on pieni.

Toinen vivahde: vanhentuneiden merkintöjen järjestyksellä on merkitystä. Editori käy läpi taulukon indeksistä 0 alkaen ja käyttää ensimmäistä vastaavaa. Jos kaksi vanhentunutta versiota ovat samankaltaisia, väärä saattaa tulla sovelletuksi. Listaa aina viimeisin vanhentunut versio ensin (se, joka edeltää nykyistä versiota).

Lopuksi, vanhentaminen ei käsittele sisältöä, jota on muokattu sivustolaajuisella tyylimuutoksella (esim. theme.json-tiedoston kautta). Jos lohkosi ulkonäkö perustui maailmanlaajuisiin tyyleihin, jotka ovat sittemmin muuttuneet, vanhentaminen ei ota sitä huomioon. Saatat joutua lisäämään migraatioskriptin, joka suoritetaan tallennuksen yhteydessä tai laajennuksen päivityskoukun avulla.

Kun vanhentaminen ei ole vastaus

Useimmat oppaat esittävät vanhentamisen pakollisena. Todellisuudessa on tilanteita, joissa täysi katkaisu on parempi. Jos lohkosi on uusi ja sitä käytetään vain kourallisessa viestejä, näiden muutamien tapausten manuaalinen päivittäminen saattaa olla nopeampaa kuin vanhentamiskoodin kirjoittaminen ja testaaminen. Samoin, jos lohkon taustalla oleva tietomalli on olennaisesti erilainen (esim. yhdistät kaksi lohkoa yhdeksi), vanhentaminen ei välttämättä ole tarpeeksi joustavaa. Tässä tapauksessa kirjoita kertaluonteinen migraatioskripti, joka suoritetaan laajennuksen päivityksen yhteydessä ja muuntaa vanhat lohkot uuteen muotoon.

Toinen vastakkaisuus: vanhentamista ei pidä käyttää hyvän suunnittelun korvikkeena. Jos ennakoit toistuvia muutoksia, suunnittele lohkosi versiointi mielessä alusta alkaen – esim. tallentamalla version-attribuutti ja käyttämällä ehdollista renderöintiä. Tätä lähestymistapaa käsitellään artikkelissa Beyond Basic Blocks, ja se on kevyempi kuin vanhentaminen, mutta vaatii ennakointia.

Yhteenveto

Lohkon vanhentaminen on olennainen työkalu jokaiselle vakavasti otettavalle Gutenberg-kehittäjälle. Sen avulla voit kehittää lohkojasi rikkomatta käyttäjien sisältöä. Keskeiset vaiheet ovat: tallenna nykyinen tila, määrittele vanhentunut versio block.json-tiedostossa, kartoita attribuutit tarvittaessa ja testaa oikealla sisällöllä. Mutta muista, että vanhentamiseen liittyy ylläpitokustannuksia. Joskus täysi katkaisu tai versioitu lohkosuunnittelu on käytännöllisempää. Käytä vanhentamista strategisesti, ei automaattisesti, ja lohkosi pysyvät vankoina monien päivitysten läpi.

Laajempaa näkökulmaa ylläpidettävien laajennusten rakentamiseen saat artikkelista Building Robust WordPress Plugins. Ja jos olet uusi lohkokehityksessä, Beyond Basic Blocks auttaa sinua alkuun.