Vai al contenuto

Registrazione delle risorse

Blockstudio accoda automaticamente tutti i file che terminano con .css, .scss e .js quando il vostro blocco viene usato in una pagina. Potete definire come accodare le risorse usando uno dei seguenti nomi di file. * è un carattere jolly che potete sostituire con qualsiasi stringa.

Nei file CSS e SCSS del blocco, %selector% si espande nella classe wrapper specifica del blocco. Questo consente di selezionare lo stesso elemento a cui viene applicato bs_get_scoped_class(), anche quando il file non è una risorsa con ambito specifico.

Schema Comportamento
*.(s)css Accodato come tag <link> nell’editor e nel frontend
*.inline.(s)css Il contenuto viene accodato in un tag <style> in linea nell’editor e nel frontend
*.editor.(s)css Accodato come tag <link> solo nell’editor
*.scoped.(s)css Il contenuto specifico viene accodato in un tag <style> in linea nell’editor e nel frontend
*.js Accodato come tag <script> nell’editor e nel frontend
*.inline.js Il contenuto viene accodato in un tag <script> in linea nell’editor e nel frontend
*.editor.js Accodato come tag <script> solo nell’editor
*.view.js Accodato come tag <script> solo nel frontend

Nota

La notazione con trattino (*-inline.css, *-editor.css ecc.) è ancora supportata per garantire la retrocompatibilità, ma è deprecata. Usate la notazione con punto per i nuovi blocchi.

In linea

Gli stili e gli script in linea hanno il grande vantaggio di essere renderizzati direttamente nella pagina come tag style o script. Questo può migliorare i tempi di caricamento, perché evita richieste aggiuntive.

  • I file .js vengono inseriti in linea alla fine del body
  • I file .(s)css vengono inseriti in linea alla fine dell’head
  • Ogni file viene inserito in linea una sola volta

Fogli di stile inline di piccole dimensioni

Per impostazione predefinita, un file *.(s)css viene collegato, con una richiesta per ogni file. L’impostazione assets.inlineLimit inserisce invece inline i fogli di stile più piccoli, seguendo la regola applicata da WordPress core ai propri stili: i fogli di stile esterni dei blocchi di una pagina vengono ordinati dal più piccolo al più grande e inseriti come <style> finché il totale progressivo resta entro il limite. Ogni altro file mantiene il proprio tag <link>.

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

Il limite è espresso in byte e 0, il valore predefinito, disattiva questa funzionalità. Misura il file compilato che verrebbe caricato da <link>, minificato quando assets.minify.css è attivo. Solo la scelta tra <link> e <style> dipende dalle dimensioni. Ogni tag resta nel punto in cui si sarebbe trovato <link>, quindi l’ordine di caricamento e la cascata non cambiano. L’elemento mantiene il proprio id.

L’impostazione non si applica ai file *.inline.(s)css e *.scoped.(s)css, che sono sempre inline, agli asset dell’editor e dell’admin né ai fogli di stile estratti dai moduli JavaScript importati. I fogli di stile globali vengono conteggiati come quelli dei blocchi. Un file resta collegato ogni volta che inserirlo inline ne cambierebbe il comportamento:

  • Contiene un URL relativo in url() o @import, che viene risolto rispetto al foglio di stile quando è collegato e rispetto alla pagina quando è inline. I percorsi assoluti, gli URL completi, gli URI data: e i frammenti # sono compatibili.
  • Usa image-set() o contiene una sequenza di chiusura </style.
  • Contiene escape CSS, un’apertura di commento HTML o una dichiarazione @charset. Per prudenza, questi file restano collegati per evitare di alterare URL o l’analisi del documento.

Usate il filtro dell’impostazione per modificare il limite a partire da PHP:

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

Gli CSS inseriti inline diventano parte dell’HTML della pagina. Dopo una modifica al foglio di stile, è necessario svuotare la cache della pagina; inoltre, il browser non può memorizzare quei byte tra una pagina e l’altra. Per questo il limite si applica al totale per pagina.

Con ambito

Anche gli stili con ambito vengono inseriti in linea, ma preceduti da un ID univoco per ogni blocco. Usate la funzione bs_get_scoped_class per aggiungere la classe al vostro template.

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

Quanto sopra produrrà il seguente stile con ambito:

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>

I selettori normali all’interno di un file con ambito continuano a selezionare i discendenti del wrapper con ambito. Usate %selector% per applicare uno stile al wrapper stesso.

Globale

Oltre alle risorse specifiche dei blocchi, è possibile accodare risorse globali, disponibili in tutte le pagine anche quando non è presente alcun blocco. Per accodare una risorsa globale, aggiungete il prefisso global- al nome del file. Potete usare insieme qualsiasi suffisso (e.g. -inline).

Le combinazioni possibili sono:

  • 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

Amministrazione

Le risorse di amministrazione vengono accodate solo nell’area di amministrazione WordPress. Il prefisso admin- serve a definire le risorse di amministrazione.

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

Editor dei blocchi

Le risorse dell’editor dei blocchi vengono accodate solo nell’editor dei blocchi. Il prefisso block-editor- serve a definirle.

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

Nota

Se WordPress disabilita l’iframe dell’editor perché un blocco lato client è registrato con apiVersion inferiore a 3, la canvas dell’editor e l’interfaccia WordPress di amministrazione condividono lo stesso documento. Gli script globali o dell’editor che si collegano a window, document, body, agli eventi wheel o allo scorrimento del documento dovrebbero proteggersi da body.block-editor-page o escludere le aree dell’editor WordPress, come .interface-complementary-area e .interface-navigable-region.

Ordine di caricamento

Nel frontend, con l’accodamento automatico delle risorse e il buffering dell’output abilitati, Blockstudio aggiunge i tag CSS, <link> e <style> dei blocchi alla pagina in buffer, subito prima del tag </head> di chiusura, invece di registrarli con wp_enqueue_style(). Gli CSS dei blocchi vengono quindi dopo i fogli di stile che WordPress ha già inserito nell’head, inclusi gli stili del tema e dei plugin accodati con wp_enqueue_style(), indipendentemente dalla priorità o dalle dipendenze di accodamento. Le risorse di amministrazione e di block-editor- usano invece il sistema di accodamento di WordPress.

A parità di importanza, livello della cascade e specificità, il foglio di stile del blocco prevale su quello del tema. Per modificare questo comportamento, aumentate la specificità della regola del tema oppure aggiungete il foglio di stile del tema all’head Blockstudio generato con il filtro blockstudio/render/head. I contenuti aggiunti dal filtro vengono inseriti dopo le risorse del blocco. Rimuovete il foglio di stile anche da WordPress per evitare che venga caricato due volte.

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

Il filtro head viene eseguito solo quando Blockstudio memorizza la pagina in un buffer. Il buffering è disattivato nell’anteprima del Customizer e quando blockstudio/buffer/enabled restituisce false. bs_is_buffering() indica in quale caso vi trovate, così un tema può aggiungere il proprio foglio di stile tramite il filtro quando la pagina viene memorizzata in un buffer e accodarlo con WordPress negli altri casi. La risposta è disponibile da wp_enqueue_scripts in poi ed è false prima di 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);
});

Usate blockstudio/buffer/output se dovete riorganizzare il documento finale in un altro modo.

Disattivare l’accodamento

L’accodamento automatico delle risorse può essere disabilitato con l’impostazione assets/enqueue. È utile se preferite gestire autonomamente l’accodamento di tutte le risorse.

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

Per blocco

Se il template di un blocco non restituisce nulla, Blockstudio non accoderà alcuna risorsa per quel blocco. Questo metodo è utile per disattivare l’accodamento al verificarsi di una determinata condizione.

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