Siirry sisältöön

Laajennukset

Laajennusten avulla voit laajentaa mitä tahansa WordPress-asennukseesi rekisteröityä lohkoa yksinkertaisella .json-pohjaisella API:lla, joka muistuttaa block.json-määritystä. Tämä koskee ydintoimintoja, kolmansien osapuolten lohkoja ja Blockstudio-työkaluilla luotuja lohkoja.

Kaikkia kenttätyyppejä voi lisätä mihin tahansa lohkoon, ja niiden tiedot tallennetaan lohkon attribuutteihin. Attribuuttien kaikki ominaisuudet, kuten suodatus, käytöstä poistaminen, ehdollinen logiikka ja vaihtoehtojen täyttäminen, ovat käytettävissä laajennuksissa.

Laajennustyypit

Laajennettuja arvoja voi hyödyntää monin eri tavoin:

  • class: Lisää lohkoon luokka attribuutin arvolla
  • style: Lisää lohkoon sisäisiä tyylejä attribuutin arvolla
  • attributes: Aseta lohkoon suoraan mikä tahansa attribuutin arvo
  • data attributes: Aseta laajennusarvoilla tiettyjä data-attribuutteja

Määritys

Kuvitellaan seuraava tilanne: haluat lisätä mukautetun luokan select-kentän jokaiseen ydinlohkoon. Sinun tarvitsee vain lisätä tämä .json-tiedosto minne tahansa lohkokansioon, niin se rekisteröidään automaattisesti laajennukseksi.

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "priority": 10,
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "customColor",
        "type": "select",
        "label": "Custom color",
        "options": [
          {
            "value": "#f00",
            "label": "Red"
          },
          {
            "value": "#00f",
            "label": "Blue"
          }
        ],
        "set": [
          {
            "attribute": "style",
            "value": "color: {attributes.customColor}"
          }
        ]
      }
    ]
  }
}

Tämä lisää customColor-kentän jokaiseen ydinlohkoon, jolloin voit määrittää lohkon tekstin värin.

Tiedostonimi

Koska renderöintimallia ei ole, laajennus ei tarvitse vastaavaa index-tiedostoa eikä sitä siksi tarvitse nimetä block.json. Näin kaikki laajennukset voi tallentaa kätevästi yhteen kansioon. Useat tiedostot voivat laajentaa samoja lohkoja, esimerkiksi kaksi tiedostoa, joissa on "name": "core/*"; kumpikin rekisteröi omat kenttänsä.

Skeema

Blockstudio tarjoaa mukautetun JSON-skeeman laajennusmäärityksille:

Näytä laajennuksen skeema

Nimi

Määritysobjektin name-ominaisuus määrittää, mitä lohkoja laajennetaan. Tarpeidesi mukaan vaihtoehtoja on kolme:

  • blockName: Yhden lohkon nimi, e.g. core/paragraph
  • [blockNameA, blockNameB]: Taulukko lohkojen nimistä, e.g. ["core/paragraph", "core/heading"]
  • core/*: Jokerimerkki, jolla laajennetaan kaikki tietyn tyypin lohkot

Tähteen päättyvä nimi toimii etuliitteen jokerimerkkinä, ei vain core/*. Seuraava laajennus koskee kaikkia lohkoja, joiden nimi alkaa merkkijonolla my-plugin/, mukaan lukien lohkot, jotka on luotu Blockstudio-toiminnolla:

JSON
{
  "name": "my-plugin/*",
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

Lohkojen poissulkeminen

Ohita muuten name-määritykseen täsmäävät lohkot ylimmän tason exclude-taulukolla:

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "exclude": ["core/button", "core/image"],
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

Poissulkemisissa käytetään samaa tarkkaa nimiosumaa ja lopussa olevan merkin * mukaista etuliiteosumaa kuin name-määrityksissä. Ne ovat etusijalla yksittäisiin nimiin, nimiluetteloihin ja jokerimerkkeihin nähden. Poissuljettu lohko ei saa laajennuksen editorikenttiä, käyttöliittymän attribuutteja eikä resursseja. Muut täsmäävät laajennukset eivät muutu. Jätä exclude pois tai käytä tyhjää taulukkoa, jos haluat säilyttää nykyisen toiminnan.

Blockstudio-avain

Aivan kuten käytettäessä block.json mukautetuissa lohkoissa, blockstudio-ominaisuuden on oltava määritysobjektissa, jossa extend on asetettu arvoon true.

Sijainti

Oletusarvoisesti laajennukset näytetään omalla välilehdellään lohkon tarkastelupaneelissa. Jos haluat siirtää ne toiseen sijaintiin, voit käyttää group-ominaisuutta:

  • settings: Oletussijainti
  • styles: Tyylit-välilehti
  • advanced: Lisäasetukset-välilehti
JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "group": "styles",
    "attributes": []
  }
}

Prioriteetti

priority-ominaisuudella voit määrittää laajennusten renderöintijärjestyksen. Korkeamman prioriteetin laajennukset renderöidään myöhemmin. Aseta se tiedoston ylimmälle tasolle, kuten määritysesimerkissä, tai kohtaan extend:

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": { "priority": 10 },
    "attributes": []
  }
}

Jos molemmat on asetettu, etusija on arvolla blockstudio.extend.priority.

Attribuutit

Lisätietoja attribuuttien toiminnasta on attribuutteja käsittelevässä osiossa.

Ainoa asia, joka sinun tarvitsee tietää laajennusten attribuuteista, on set-ominaisuus. Sitä käytetään attribuutin arvon määrittämiseen jollekin laajennustyypeistä.

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "customColor",
        "type": "select",
        "label": "Heading color",
        "options": [
          {
            "value": "#f00",
            "label": "Red"
          },
          {
            "value": "#00f",
            "label": "Blue"
          }
        ],
        "set": [
          {
            "attribute": "style",
            "value": "color: {attributes.customColor}"
          }
        ]
      }
    ]
  }
}

Arvojen hakeminen

Attribuutin arvo haetaan käyttämällä aaltosulkeiden sisällä pistemerkintää.

Myös sisäkkäisiä arvoja voi hakea, kun attribuutit eivät palauta yhtä arvoa, esimerkiksi kun palautusmuodoksi asetetaan both vaihtoehtoja sisältävissä kenttätyypeissä.

JSON
{
  "attributes": [
    {
      "id": "customColor",
      "type": "select",
      "label": "Heading color",
      "options": [
        {
          "value": "#f00",
          "label": "Red"
        },
        {
          "value": "#00f",
          "label": "Blue"
        }
      ],
      "returnFormat": "both",
      "set": [
        {
          "attribute": "style",
          "value": "color: {attributes.customColor.value}"
        },
        {
          "attribute": "data-color",
          "value": "{attributes.customColor.label}"
        }
      ]
    }
  ]
}

Yllä oleva esimerkki asettaa attribuutin style arvoksi color: #f00 tai color: #00f ja attribuutin data-color arvoksi Red tai Blue arvon mukaan.

Toistaiseksi set-määrityksissä voi käyttää vain nykyisen attribuutin arvoja. Muiden attribuuttien arvojen käyttö saatetaan lisätä myöhemmin.

Taulukot

Taulukoita käytettäessä set-ominaisuutta sovelletaan jokaiseen taulukon kohteeseen.

Jokainen kohde lisää oman luokkansa tai tyylimäärityksensä. Mikä tahansa muu attribuutti sisältää vain yhden arvon, joten jokainen kohde korvaa sen ja viimeinen arvo jää voimaan. Aseta join arvoon true, jos haluat kirjoittaa sen sijaan kaikkien kohteiden tulokset välilyönneillä eroteltuina, ilman tyhjiä tai toistuvia arvoja, jolloin valitsin kuten [data-langs~="en"] vastaa kaikkia valittuja kohteita. join ei vaikuta kohteisiin class ja style eikä kenttiin, jotka palauttavat yhden arvon.

JSON
{
  "id": "langs",
  "type": "checkbox",
  "label": "Languages",
  "options": [
    {
      "value": "en",
      "label": "English"
    },
    {
      "value": "de",
      "label": "German"
    }
  ],
  "set": [
    {
      "attribute": "data-langs",
      "value": "{attributes.langs}",
      "join": true
    }
  ]
}

Molempien vaihtoehtojen valitseminen tulostaa arvon data-langs="en de". Ilman asetusta join tulostetaan arvo data-langs="de".

Attributes-kenttä

attributes-kenttää käytettäessä set-ominaisuutta ei tarvita, sillä kenttä yhdistää arvot automaattisesti attribuutin nimeen ja arvoon.

Laajennuskenttien tarkastelu

bs_block_extension_fields('core/paragraph') palauttaa lohkoon täsmäävien laajennusten kenttämääritykset. Katso osiosta Lohkojen tarkastelu, mitä palautusarvo sisältää ja miten se liittyy arvoon bs_block_fields().