Saltar al contenido

Extensiones

Las extensiones permiten ampliar cualquier bloque registrado en tu instalación de WordPress mediante un API basado en .json sencillo, similar a la configuración de block.json. Esto incluye bloques del núcleo, de terceros y creados con Blockstudio.

Todos los tipos de campo pueden añadirse a cualquier bloque y los datos se guardan en los atributos del bloque. Las extensiones disponen de todas las funciones de los atributos, como filtrado, desactivación, lógica condicional y población de opciones.

Tipos de extensión

Los valores extendidos pueden aprovecharse de distintas maneras:

  • class: Añade una clase al bloque mediante el valor del atributo
  • style: Añade estilos en línea al bloque mediante el valor del atributo
  • attributes: Establece directamente cualquier valor de atributo en el bloque
  • data attributes: Usa valores de extensión para establecer atributos de datos específicos

Configuración

Imagina esta situación: quieres añadir un campo select de clase personalizada a cada bloque del núcleo. Solo tienes que añadir este archivo .json en cualquier lugar de la carpeta de bloques y se registrará automáticamente como una extensión.

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

Esto añadirá un campo customColor a cada bloque del núcleo, para que puedas establecer el color del texto del bloque.

Nombre del archivo

Como no hay una plantilla de renderizado, una extensión no necesita un archivo index correspondiente y, por tanto, no tiene que llamarse block.json. Así puedes guardar cómodamente todas las extensiones en una sola carpeta. Varios archivos pueden extender los mismos bloques; por ejemplo, dos archivos con "name": "core/*", cada uno de los cuales registra sus propios campos.

Esquema

Blockstudio proporciona un esquema JSON personalizado para las configuraciones de extensiones:

Ver el esquema de extensiones

Nombre

La propiedad name del objeto de configuración define qué bloques se deben extender. Según tus necesidades, hay tres opciones:

  • blockName: Un solo nombre de bloque, e.g. core/paragraph
  • [blockNameA, blockNameB]: Una lista de nombres de bloques, e.g. ["core/paragraph", "core/heading"]
  • core/*: Un comodín para extender todos los bloques de un tipo determinado

Cualquier nombre que termine en un asterisco es un comodín de prefijo, no solo core/*. La siguiente extensión se aplica a todos los bloques cuyo nombre empieza por my-plugin/, incluidos los bloques creados con Blockstudio:

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

Exclusión de bloques

Use una matriz exclude de nivel superior para omitir los bloques que, de otro modo, coincidirían con name:

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

Las exclusiones usan la misma coincidencia por nombre exacto y por prefijo con * al final que name. Tienen prioridad sobre los nombres individuales, las listas de nombres y los comodines. Un bloque excluido no recibe los campos del editor, los atributos del frontend ni los recursos de la extensión. Las demás extensiones coincidentes no se ven afectadas. Omita exclude o use una matriz vacía para mantener el comportamiento actual.

Clave Blockstudio

Al igual que al usar block.json para bloques personalizados, la propiedad blockstudio debe estar presente en el objeto de configuración y tener extend establecido en true.

Posición

De forma predeterminada, las extensiones se muestran en su propia pestaña del inspector de bloques. Si quieres moverlas a otra posición, puedes usar la propiedad group:

  • settings: La posición predeterminada
  • styles: La pestaña de estilos
  • advanced: La pestaña avanzada
JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "group": "styles",
    "attributes": []
  }
}

Prioridad

La propiedad priority permite definir el orden en que se muestran las extensiones. Las extensiones con mayor prioridad se muestran después. Establécela en el nivel superior del archivo, como en el ejemplo de configuración, o dentro de extend:

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

Si se establecen ambas, prevalece blockstudio.extend.priority.

Atributos

Para obtener más información sobre el funcionamiento de los atributos, consulta la sección de atributos.

Lo único que necesitas saber sobre los atributos dentro de las extensiones es la propiedad set. Se usa para aplicar el valor del atributo a uno de los tipos de extensión.

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

Cómo obtener valores

Se usa la notación de punto entre llaves para obtener el valor de un atributo.

También es posible obtener valores anidados cuando los atributos no devuelven un único valor; por ejemplo, al establecer el formato de retorno en both para tipos de campo con opciones.

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

El ejemplo anterior establecerá el atributo style en color: #f00 o color: #00f y el atributo data-color en Red o Blue, según el valor.

Por ahora, en las definiciones de set solo se pueden usar valores del atributo actual. Es posible que en el futuro se puedan usar valores de otros atributos.

Matrices

Al usar matrices, la propiedad set se aplicará a cada elemento de la matriz.

Cada elemento añade su propia clase o declaración de estilo. Cualquier otro atributo contiene un único valor, por lo que cada elemento lo sobrescribe y prevalece el último. Establezca join en true para escribir los resultados de todos los elementos, separados por espacios y sin valores vacíos ni repetidos, de modo que un selector como [data-langs~="en"] coincida con todos los elementos elegidos. join no tiene efecto en class ni en style, ni en los campos que devuelven un único valor.

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

Al elegir ambas opciones se genera data-langs="en de". Sin join, se genera data-langs="de".

Campo de atributos

Al usar el campo attributes, no se necesita la propiedad set, ya que el campo asigna automáticamente los valores al nombre y al valor del atributo.

Inspección de los campos de las extensiones

bs_block_extension_fields('core/paragraph') devuelve las definiciones de campo de cada extensión que coincide con un bloque. Consulte Inspección de bloques para conocer el valor devuelto y su relación con bs_block_fields().