Aller au contenu

Enregistrement des ressources

Blockstudio met automatiquement en file d’attente tous les fichiers se terminant par .css, .scss et .js lorsque votre bloc est utilisé sur une page. Vous pouvez définir la manière dont les ressources sont mises en file d’attente à l’aide de l’un des noms de fichiers suivants. * est un caractère générique qui peut être remplacé par la chaîne de votre choix.

Dans les fichiers CSS et SCSS d’un bloc, %selector% se développe en la classe d’encapsulation propre au bloc. Vous pouvez ainsi cibler le même élément que celui qui reçoit bs_get_scoped_class(), même si le fichier n’est pas une ressource propre au bloc.

Motif Comportement
*.(s)css Mis en file d’attente sous forme de balise <link> dans l’éditeur et sur le site
*.inline.(s)css Contenu mis en file d’attente dans une balise <style> en ligne dans l’éditeur et sur le site
*.editor.(s)css Mis en file d’attente sous forme de balise <link> dans l’éditeur uniquement
*.scoped.(s)css Contenu propre au bloc mis en file d’attente dans une balise <style> en ligne dans l’éditeur et sur le site
*.js Mis en file d’attente sous forme de balise <script> dans l’éditeur et sur le site
*.inline.js Contenu mis en file d’attente dans une balise <script> en ligne dans l’éditeur et sur le site
*.editor.js Mis en file d’attente sous forme de balise <script> dans l’éditeur uniquement
*.view.js Mis en file d’attente sous forme de balise <script> sur le site uniquement

Remarque

La notation avec tirets (*-inline.css, *-editor.css, etc.) est toujours prise en charge pour assurer la compatibilité ascendante, mais elle est obsolète. Utilisez la notation avec points pour les nouveaux blocs.

En ligne

Les styles et scripts en ligne ont l’avantage d’être générés directement dans la page sous forme de balises de style ou de script. Cela peut accélérer le chargement en évitant des requêtes supplémentaires.

  • Les fichiers .js sont intégrés à la fin du corps
  • Les fichiers .(s)css sont intégrés à la fin de l’en-tête
  • Chaque fichier n’est intégré qu’une seule fois

Feuilles de style intégrées de petite taille

Par défaut, un fichier *.(s)css est lié, ce qui coûte une requête par fichier. Le réglage assets.inlineLimit intègre plutôt les petites feuilles de style, selon la règle appliquée par le cœur de WordPress à ses propres styles : les feuilles de style externes des blocs d’une page sont prises de la plus petite à la plus grande et imprimées sous forme de <style> tant que leur taille cumulée reste sous la limite. Chaque autre fichier conserve sa balise <link>.

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

La limite est exprimée en octets et 0, la valeur par défaut, désactive ce comportement. Elle mesure le fichier compilé que <link> chargerait, minifié lorsque assets.minify.css est activé. Seul le choix entre <link> et <style> dépend de la taille. Chaque balise reste à l’emplacement où <link> aurait été inséré, de sorte que l’ordre de chargement et la cascade ne changent pas. L’élément conserve son id.

Ce réglage ne s’applique pas aux fichiers *.inline.(s)css et *.scoped.(s)css, qui sont toujours intégrés, ni aux ressources de l’éditeur et de l’administration, ni aux feuilles de style extraites des modules JavaScript importés. Les feuilles de style globales sont comptabilisées comme celles des blocs. Un fichier reste lié dès que son intégration entraînerait un changement :

  • Il contient une URL relative dans url() ou @import, qui se résout par rapport à la feuille de style lorsqu’elle est liée et par rapport à la page lorsqu’elle est intégrée. Les chemins absolus, les URL complètes, les URI data: et les fragments # conviennent.
  • Il utilise image-set() ou contient une séquence fermante </style.
  • Il contient des échappements CSS, un marqueur d’ouverture de commentaire HTML ou une déclaration @charset. Par précaution, ces fichiers restent liés pour éviter de modifier URL ou l’analyse du document.

Utilisez le filtre de réglage pour modifier la limite à partir de PHP :

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

Les CSS intégrés font partie du HTML de la page. Il faut purger le cache de la page après toute modification d’une feuille de style, et le navigateur ne peut pas mettre ces octets en cache d’une page à l’autre ; c’est pourquoi la limite est un total par page.

Portée limitée

Les styles à portée limitée sont également intégrés en ligne, mais précédés d’un identifiant unique à chaque bloc. Utilisez la fonction bs_get_scoped_class pour ajouter la classe à votre modèle.

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

Cela produira le style à portée limitée suivant :

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>

Les sélecteurs classiques d’un fichier à portée limitée ciblent toujours les descendants de l’élément d’encapsulation. Utilisez %selector% pour appliquer un style à l’élément d’encapsulation lui-même.

Global

En plus des ressources propres aux blocs, vous pouvez aussi mettre en file d’attente des ressources globales, disponibles sur toutes les pages, qu’un bloc soit présent ou non. Pour mettre une ressource globale en file d’attente, ajoutez le préfixe global- au nom du fichier. Les suffixes suivants peuvent être utilisés seuls ou combinés : e.g, -inline.

Combinaisons possibles :

  • 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

Administration

Les ressources d’administration sont mises en file d’attente uniquement dans l’espace d’administration WordPress. Le préfixe admin- sert à définir les ressources d’administration.

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

Éditeur de blocs

Les ressources de l’éditeur de blocs sont mises en file d’attente uniquement dans l’éditeur de blocs. Le préfixe block-editor- sert à les définir.

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

Remarque

Si WordPress désactive l’iframe de l’éditeur parce qu’un bloc côté client est enregistré avec apiVersion inférieur à 3, le canevas de l’éditeur et l’interface d’administration WordPress partagent le même document. Les scripts globaux ou de l’éditeur qui s’attachent à window, document, body, aux événements de molette ou au défilement du document doivent vérifier l’absence de body.block-editor-page ou exclure les zones d’édition WordPress telles que .interface-complementary-area et .interface-navigable-region.

Ordre de chargement

Sur le site, lorsque la mise en file d’attente automatique des ressources et la mise en tampon de la sortie sont activées, Blockstudio ajoute les balises CSS <link> et <style> de ses blocs à la page mise en tampon, juste avant la balise fermante </head>, au lieu de les enregistrer avec wp_enqueue_style(). Les CSS des blocs arrivent donc après les feuilles de style que WordPress a déjà imprimées dans l’en-tête, y compris celles du thème et des extensions mises en file d’attente avec wp_enqueue_style(), quels que soient leur priorité de mise en file d’attente ou leurs dépendances. Les ressources d’administration et de block-editor- utilisent plutôt le système de mise en file d’attente de WordPress.

Pour des règles ayant la même importance, la même couche de cascade et la même spécificité, la feuille de style du bloc prévaut sur celle du thème. Pour modifier ce comportement, augmentez la spécificité de la règle du thème ou ajoutez la feuille de style du thème à l’en-tête Blockstudio généré avec le filtre blockstudio/render/head. Le contenu ajouté par ce filtre est placé après les ressources du bloc. Retirez également la feuille de style de la file d’attente de WordPress afin qu’elle ne soit pas chargée deux fois.

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')) . '">';
});

Le filtre head ne s’exécute que lorsque Blockstudio met la page en mémoire tampon. La mise en mémoire tampon est désactivée dans l’aperçu du personnalisateur et lorsque blockstudio/buffer/enabled renvoie false. bs_is_buffering() vous indique dans quel cas vous vous trouvez, afin qu’un thème puisse ajouter sa feuille de style via le filtre lorsque la page est mise en mémoire tampon et la mettre en file d’attente avec WordPress dans le cas contraire. La réponse est disponible à partir de wp_enqueue_scripts et est false avant 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);
});

Utilisez blockstudio/buffer/output si vous devez réorganiser le document final différemment.

Désactiver la mise en file d’attente

La mise en file d’attente automatique des ressources peut être désactivée avec le paramètre assets/enqueue. Cette option est utile si vous souhaitez gérer vous-même toutes les ressources mises en file d’attente.

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

Par bloc

Lorsqu’un modèle de bloc ne renvoie rien, Blockstudio ne met aucune ressource en file d’attente pour ce bloc. Cette méthode est pratique pour désactiver la mise en file d’attente lorsqu’une condition donnée est remplie.

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