Ga naar de inhoud

Extensies

Met extensies kunt u elk geregistreerd blok in uw WordPress-installatie uitbreiden met een eenvoudige, op .json gebaseerde API, vergelijkbaar met de configuratie van block.json. Dit geldt voor coreblokken, blokken van derden en blokken die met Blockstudio zijn gemaakt.

Alle veldtypen kunnen aan elk blok worden toegevoegd; de gegevens worden opgeslagen in de attributen van het blok. De volledige functieset is beschikbaar voor extensies, waaronder filteren, uitschakelen, voorwaardelijke logica en opties vullen.

Extensietypen

Uitgebreide waarden kunnen op verschillende manieren worden gebruikt:

  • class: Voeg met de attribuutwaarde een class toe aan het blok
  • style: Voeg met de attribuutwaarde inline-stijlen toe aan het blok
  • attributes: Stel rechtstreeks een attribuutwaarde in op het blok
  • data attributes: Gebruik extensiewaarden om specifieke data-attributen in te stellen

Instellen

Stel je het volgende scenario voor: je wilt een aangepast veld select toevoegen aan elk core-blok. Je hoeft alleen dit bestand .json ergens in je blokmap te plaatsen; het wordt automatisch als extensie geregistreerd.

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}"
          }
        ]
      }
    ]
  }
}

Hiermee wordt een veld customColor toegevoegd aan elk core-blok, zodat je de tekstkleur van het blok kunt instellen.

Bestandsnaam

Omdat er geen renderingsjabloon is, heeft een extensie geen bijbehorend bestand index nodig en hoeft deze dus niet block.json te heten. Zo kun je alle extensies handig in één map opslaan. Meerdere bestanden kunnen dezelfde blokken uitbreiden, bijvoorbeeld twee bestanden met "name": "core/*"; elk bestand registreert zijn eigen velden.

Schema

Blockstudio biedt een aangepast JSON-schema voor extensieconfiguraties:

Schema van de extensieweergave

Naam

De eigenschap name van het configuratieobject bepaalt welke blokken worden uitgebreid. Afhankelijk van je behoeften zijn er drie mogelijkheden:

  • blockName: Eén bloknaam, e.g. core/paragraph
  • [blockNameA, blockNameB]: Een array met bloknamen, e.g. ["core/paragraph", "core/heading"]
  • core/*: Een jokerteken om alle blokken van een bepaald type uit te breiden

Elke naam die eindigt op een sterretje is een prefixjokerteken, niet alleen core/*. De volgende extensie geldt voor elk blok waarvan de naam begint met my-plugin/, inclusief blokken die zijn gemaakt met Blockstudio:

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

Blokken uitsluiten

Gebruik een exclude-array op het hoogste niveau om blokken over te slaan die anders zouden overeenkomen met name:

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

Uitsluitingen gebruiken dezelfde overeenkomst op exacte namen en prefixen met een afsluitende * als name. Ze hebben voorrang op afzonderlijke namen, namenlijsten en jokertekens. Een uitgesloten blok krijgt noch de editorvelden van de extensie, noch de frontendattributen of -assets. Andere overeenkomende extensies worden niet beïnvloed. Laat exclude weg of gebruik een lege array om het bestaande gedrag te behouden.

Sleutel Blockstudio

Net als bij het gebruik van block.json voor aangepaste blokken, moet de eigenschap blockstudio aanwezig zijn in het configuratieobject, met extend ingesteld op true.

Positie

Standaard worden extensies in een eigen tabblad in de blokinspecteur weergegeven. Als je de extensies op een andere plek wilt weergeven, kun je de eigenschap group gebruiken:

  • settings: De standaardpositie
  • styles: Het tabblad Stijlen
  • advanced: Het tabblad Geavanceerd
JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "group": "styles",
    "attributes": []
  }
}

Prioriteit

Met de eigenschap priority bepaal je de volgorde waarin extensies worden weergegeven. Extensies met een hogere prioriteit worden later weergegeven. Stel deze in op het hoogste niveau van het bestand, zoals in het installatievoorbeeld, of binnen extend:

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

Als beide zijn ingesteld, heeft blockstudio.extend.priority voorrang.

Attributen

Raadpleeg het gedeelte over attributen voor meer informatie over de werking van attributen.

Het enige dat je moet weten over attributen in extensies, is de eigenschap set. Hiermee wordt de waarde van het attribuut toegepast op een van de extensietypen.

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}"
          }
        ]
      }
    ]
  }
}

Waarden ophalen

Met puntnotatie tussen accolades haal je de waarde van een attribuut op.

Het is ook mogelijk om geneste waarden op te halen wanneer attributen niet één enkele waarde teruggeven, bijvoorbeeld wanneer je het retourformaat instelt op both voor veldtypen met opties.

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}"
        }
      ]
    }
  ]
}

Afhankelijk van de waarde stelt het bovenstaande voorbeeld het attribuut style in op color: #f00 of color: #00f en het attribuut data-color op Red of Blue.

Voorlopig kunnen in set-definities alleen waarden van het huidige attribuut worden gebruikt. Mogelijk wordt het in de toekomst ook mogelijk om waarden van andere attributen te gebruiken.

Arrays

Bij gebruik van arrays wordt de eigenschap set toegepast op elk item in de array.

Elk item voegt zijn eigen class of stijldeclaratie toe. Elk ander attribuut bevat één waarde, dus elk item overschrijft die en het laatste item wint. Stel join in op true om in plaats daarvan de resultaten van alle items weg te schrijven, gescheiden door spaties en zonder lege of herhaalde waarden, zodat een selector zoals [data-langs~="en"] overeenkomt met elk gekozen item. join heeft geen effect op class en style, of op velden die één waarde retourneren.

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
    }
  ]
}

Als u beide opties kiest, wordt data-langs="en de" weergegeven. Zonder join wordt data-langs="de" weergegeven.

Attributenveld

Bij gebruik van het veld attributes is de eigenschap set niet nodig, omdat het veld de waarden automatisch aan de attribuutnaam en -waarde koppelt.

Extensievelden inspecteren

bs_block_extension_fields('core/paragraph') retourneert de velddefinities van elke extensie die overeenkomt met een blok. Zie Blokken inspecteren voor de retourwaarde en hoe die samenhangt met bs_block_fields().