Saltar al contenido

Registro de recursos

Blockstudio añadirá automáticamente todos los archivos que terminen en .css, .scss y .js cuando se use su bloque en una página. Puede definir cómo se añaden los recursos usando uno de los siguientes nombres de archivo. * es un comodín que puede sustituir por cualquier texto que elija.

Dentro de los archivos CSS y SCSS del bloque, %selector% se expande a la clase contenedora del bloque con ámbito propio. Esto permite seleccionar el mismo elemento que recibe bs_get_scoped_class(), aunque el archivo no sea un recurso con ámbito propio.

Patrón Comportamiento
*.(s)css Se añade como etiqueta <link> en el editor y en la interfaz
*.inline.(s)css Añade el contenido en una etiqueta <style> en línea en el editor y en la interfaz
*.editor.(s)css Se añade como etiqueta <link> solo en el editor
*.scoped.(s)css Añade el contenido con ámbito propio en una etiqueta <style> en línea en el editor y en la interfaz
*.js Se añade como etiqueta <script> en el editor y en la interfaz
*.inline.js Añade el contenido en una etiqueta <script> en línea en el editor y en la interfaz
*.editor.js Se añade como etiqueta <script> solo en el editor
*.view.js Se añade como etiqueta <script> solo en la interfaz

Nota

La notación con guiones (*-inline.css, *-editor.css, etc.) sigue siendo compatible con versiones anteriores, pero está obsoleta. Use la notación con puntos para los bloques nuevos.

En línea

Los estilos y scripts en línea tienen la gran ventaja de renderizarse directamente como etiquetas de estilo o script dentro de la página. Esto puede mejorar los tiempos de carga, ya que evita solicitudes adicionales que de otro modo habría que realizar.

  • Los archivos .js se insertan al final del cuerpo
  • Los archivos .(s)css se insertan al final del encabezado
  • Cada archivo se inserta una sola vez

Hojas de estilo pequeñas en línea

Por defecto, se enlaza un archivo *.(s)css, lo que supone una solicitud por archivo. La opción assets.inlineLimit imprime en línea las hojas de estilo pequeñas, siguiendo la regla que WordPress core aplica a sus propios estilos: las hojas de estilo externas de los bloques de una página se ordenan de menor a mayor y se imprimen como <style> mientras el total acumulado no supere el límite. Todos los demás archivos conservan su etiqueta <link>.

JSON
{
  "assets": {
    "inlineLimit": 40000
  }
}

El límite se expresa en bytes y 0, el valor predeterminado, desactiva este comportamiento. Mide el archivo compilado que cargaría <link>, minificado si assets.minify.css está activado. Solo la elección entre <link> y <style> depende del tamaño. Cada etiqueta permanece donde habría estado <link>, por lo que el orden de carga y la cascada no cambian. El elemento conserva su id.

La opción no se aplica a los archivos *.inline.(s)css y *.scoped.(s)css, que siempre se insertan en línea; tampoco se aplica a los recursos del editor y de administración ni a las hojas de estilo extraídas de los módulos JavaScript importados. Las hojas de estilo globales cuentan como hojas de estilo de bloques. Un archivo sigue enlazado siempre que insertarlo en línea pudiera cambiarlo:

  • Contiene un URL relativo en url() o @import, que se resuelve respecto a la hoja de estilo cuando está enlazada y respecto a la página cuando está en línea. Las rutas absolutas, las URL completas, los URI data: y los fragmentos # son válidos.
  • Usa image-set() o contiene una secuencia de cierre </style.
  • Contiene escapes CSS, un inicio de comentario HTML o una declaración @charset. Estos archivos siguen enlazados por precaución, para evitar alterar URL o el análisis del documento.

Use el filtro de opciones para cambiar el límite de PHP:

PHP
add_filter('blockstudio/settings/assets/inline_limit', fn() => 40000);

El CSS insertado en línea pasa a formar parte del HTML de la página. Hay que purgar la caché de la página después de modificar una hoja de estilo, y el navegador no puede almacenar esos bytes en caché entre páginas; por eso el límite se aplica al total por página.

Con ámbito propio

Los estilos con ámbito propio también se insertan en línea, pero llevan como prefijo un ID único para cada bloque. Use la función bs_get_scoped_class para añadir la clase a su plantilla.

PHP
<section class="hero <?php echo bs_get_scoped_class($b['name']); ?>">
  <h1 class="hero__title">Scope me!</h1>
</section>
CSS
%selector% {
  --hero-gap: var(--wp--preset--spacing--space-10);
}

%selector%.hero {
  border-bottom: 1px solid currentColor;
}

.hero__title {
  color: red;
}

Lo anterior generará el siguiente estilo con ámbito propio:

HTML
<style>
  .bs-62df71e6cc9a {
    --hero-gap: var(--wp--preset--spacing--space-10);
  }

  .bs-62df71e6cc9a.hero {
    border-bottom: 1px solid currentColor;
  }

  .bs-62df71e6cc9a .hero__title {
    color: red;
  }
</style>

<section class="hero bs-62df71e6cc9a">
  <h1 class="hero__title">Scope me!</h1>
</section>

Los selectores normales dentro de un archivo con ámbito propio siguen seleccionando los elementos descendientes del contenedor. Use %selector% si quiere aplicar estilos al propio contenedor.

Global

Además de los recursos específicos de cada bloque, también es posible añadir recursos globales, disponibles en todas las páginas, haya bloques presentes o no. Para añadir un recurso global, incluya el prefijo global- en el nombre del archivo. Puede combinarlo con cualquiera de los sufijos (e.g. -inline).

Estas son las combinaciones posibles:

  • global-styles.(s)css
  • global-styles.inline.(s)css
  • global-styles.editor.(s)css
  • global-styles.scoped.(s)css
  • global-scripts.js
  • global-scripts.inline.js
  • global-scripts.editor.js
  • global-scripts.view.js

Administración

Los recursos de administración solo se añaden en el área de administración de WordPress. El prefijo admin- sirve para definirlos.

  • admin-styles.(s)css
  • admin-scripts.js

Editor de bloques

Los recursos del editor de bloques solo se añaden en el editor de bloques. El prefijo block-editor- sirve para definirlos.

  • block-editor-styles.(s)css
  • block-editor-scripts.js

Nota

Si WordPress desactiva el iframe del editor porque se registra un bloque del lado del cliente con apiVersion menor que 3, el lienzo del editor y la interfaz de administración de WordPress comparten el mismo documento. Los scripts globales o del editor que se vinculen a window, document, body, eventos de rueda o el desplazamiento del documento deben protegerse frente a body.block-editor-page o excluir regiones del editor WordPress, como .interface-complementary-area y .interface-navigable-region.

Orden de carga

En la interfaz, con la inclusión automática de recursos y el almacenamiento temporal de salida activados, Blockstudio añade las etiquetas CSS <link> y <style> de sus bloques a la página almacenada en búfer justo antes de la etiqueta de cierre </head>, en lugar de registrarlas con wp_enqueue_style(). Por ello, CSS del bloque aparece después de las hojas de estilo que WordPress ya ha imprimido en el encabezado, incluidas las hojas de estilo del tema y de los plugins añadidas con wp_enqueue_style(), independientemente de su prioridad o dependencias de inclusión. Los recursos de administración y de block-editor- usan en su lugar el sistema de inclusión de WordPress.

Para reglas con la misma importancia, capa de cascada y especificidad, la hoja de estilo del bloque prevalece sobre la del tema. Para cambiar esto, aumente la especificidad de la regla del tema o agregue la hoja de estilo del tema al encabezado Blockstudio generado mediante el filtro blockstudio/render/head. El contenido añadido por el filtro se coloca después de los recursos del bloque. Desactive también la inclusión de la hoja de estilo desde WordPress para evitar que se cargue dos veces.

PHP
add_action('wp_enqueue_scripts', function() {
  wp_dequeue_style('theme-overrides');
}, 100);

add_filter('blockstudio/render/head', function($head) {
  return $head . '<link rel="stylesheet" href="' . esc_url(get_theme_file_uri('overrides.css')) . '">';
});

El filtro head solo se ejecuta cuando Blockstudio almacena en búfer la página. El almacenamiento en búfer está desactivado en la vista previa del Personalizador y cuando blockstudio/buffer/enabled devuelve false. bs_is_buffering() indica en qué caso se encuentra, para que un tema pueda añadir su hoja de estilos mediante el filtro cuando la página está en búfer y ponerla en cola con WordPress en caso contrario. La respuesta está disponible a partir de wp_enqueue_scripts y es false antes de template_redirect.

PHP
add_action('wp_enqueue_scripts', function() {
  $url = get_theme_file_uri('overrides.css');

  if (bs_is_buffering()) {
    add_filter('blockstudio/render/head', function($head) use ($url) {
      return $head . '<link rel="stylesheet" href="' . esc_url($url) . '">';
    });
    return;
  }

  wp_enqueue_style('theme-overrides', $url);
});

Use blockstudio/buffer/output si necesita reorganizar el documento final de otra manera.

Desactivar la inclusión

La inclusión automática de recursos se puede desactivar con el ajuste assets/enqueue. Esto resulta útil si prefiere encargarse de incluir todos los recursos por su cuenta.

PHP
add_filter('blockstudio/settings', function($settings) {
  $settings['assets']['enqueue'] = false;
  return $settings;
});

Por bloque

Si la plantilla de un bloque no devuelve nada, Blockstudio no añadirá recursos para ese bloque. Esto resulta práctico para desactivar la inclusión cuando se cumple una condición determinada.

PHP

PHP
<?php
  if ( !$a['slides'] ) {
    // or return '';
    return false;
  }
?>

<div>my slider</div>

Twig

Twig
{% if not a.slides %}
  <div>my slider</div>
{% endif %}