Hoppa till innehåll

Tillägg

Med tillägg kan du utöka valfritt registrerat block i din WordPress-installation med hjälp av en enkel .json-baserad API, som liknar konfigurationen för block.json. Detta omfattar kärnblock, block från tredje part och block som skapats med Blockstudio.

Alla fältstyper kan läggas till i valfritt block, och data sparas i blockets attribut. Hela funktionsuppsättningen för attribut, till exempel filtrering, inaktivering, villkorslogik och ifyllning av alternativ, är tillgänglig för tillägg.

Tilläggstyper

Utökade värden kan användas på många olika sätt:

  • class: Lägg till en klass i blocket med attributvärdet
  • style: Lägg till inline-format i blocket med attributvärdet
  • attributes: Ange valfritt attributvärde direkt på blocket
  • data attributes: Använd tilläggsvärden för att ange specifika dataattribut

Konfiguration

Föreställ dig följande scenario: du vill lägga till ett anpassat fält select för klass i varje kärnblock. Allt du behöver göra är att lägga till den här filen .json var som helst i blockmappen, så registreras den automatiskt som ett tillägg.

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

Detta lägger till ett fält customColor i varje kärnblock, så att du kan ange blockets textfärg.

Filnamn

Eftersom det inte finns någon renderingsmall behöver ett tillägg ingen motsvarande fil index och behöver därför inte heta block.json. Det gör att alla tillägg enkelt kan förvaras i en enda mapp. Flera filer kan utöka samma block, till exempel två filer med "name": "core/*"; var och en registrerar sina egna fält.

Schema

Blockstudio tillhandahåller ett anpassat JSON-schema för tilläggskonfigurationer:

Schema för View-tillägg

Namn

Egenskapen name i konfigurationsobjektet anger vilka block som ska utökas. Det finns tre alternativ beroende på dina behov:

  • blockName: Ett enskilt blocknamn, e.g. core/paragraph
  • [blockNameA, blockNameB]: En array med blocknamn, e.g. ["core/paragraph", "core/heading"]
  • core/*: Ett jokertecken för att utöka alla block av en viss typ

Alla namn som slutar med en asterisk är ett prefixjokertecken, inte bara core/*. Följande tillägg gäller för varje block vars namn börjar med my-plugin/, inklusive block som skapats med Blockstudio:

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

Utesluta block

Använd en array på toppnivå i exclude för att hoppa över block som annars skulle matcha name:

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

Undantag använder samma matchning på exakta namn och prefix som slutar med * som name. De har företräde framför enstaka namn, namnlistor och jokertecken. Ett uteslutet block får varken tilläggets redigerarfält eller dess frontendattribut eller resurser. Andra matchande tillägg påverkas inte. Utelämna exclude eller använd en tom array för att behålla det befintliga beteendet.

Blockstudio-nyckel

Precis som när du använder block.json för anpassade block måste egenskapen blockstudio finnas i konfigurationsobjektet med extend inställt på true.

Position

Som standard visas tillägg på en egen flik i blockinspektören. Om du vill flytta tilläggen till en annan position kan du använda egenskapen group:

  • settings: Standardpositionen
  • styles: Fliken för stilar
  • advanced: Fliken för avancerat
JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "group": "styles",
    "attributes": []
  }
}

Prioritet

Egenskapen priority låter dig ange i vilken ordning tilläggen renderas. Tillägg med högre prioritet renderas senare. Ange den på filens toppnivå, som i konfigurationsexemplet, eller inuti extend:

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

Om båda anges vinner blockstudio.extend.priority.

Attribut

Mer information om hur attribut fungerar finns i avsnittet om attribut.

Det enda du behöver känna till om attribut i tillägg är egenskapen set. Den används för att tillämpa attributets värde på en av tilläggstyperna.

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

Hämta värden

Punktnotation inom klammerparenteser används för att hämta värdet för ett attribut.

Det går också att hämta nästlade värden när attribut inte returnerar ett enskilt värde, till exempel när returformatet ställs in på both för fälttyper med alternativ.

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

Exemplet ovan ställer in attributet style på color: #f00 eller color: #00f och attributet data-color på Red eller Blue, beroende på värdet.

För närvarande kan endast värden från det aktuella attributet användas i definitioner av set. Möjligheten att använda värden från andra attribut kan läggas till i framtiden.

Arrayer

När du använder arrayer tillämpas egenskapen set på varje objekt i arrayen.

Varje objekt lägger till sin egen klass eller stilregel. Alla andra attribut innehåller ett enda värde, så varje objekt skriver över det föregående och det sista vinner. Sätt join till true för att i stället skriva resultaten från alla objekt, åtskilda av blanksteg och utan tomma eller upprepade värden, så att en väljare som [data-langs~="en"] matchar alla valda objekt. join påverkar inte class och style eller fält som returnerar ett enda värde.

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

Om du väljer båda alternativen återges data-langs="en de". Utan join återges data-langs="de".

Attributfält

När du använder fältet attributes behövs ingen egenskap set, eftersom fältet automatiskt mappar värdena till attributets namn och värde.

Granska tilläggsfält

bs_block_extension_fields('core/paragraph') returnerar fältdefinitionerna för t varje tillägg som matchar ett block. Se Granska block för returvärdet och hur det förhåller sig till bs_block_fields().