Pular para o conteúdo

Registro de recursos

Blockstudio enfileirará automaticamente todos os arquivos com final .css, .scss e .js quando o bloco for usado em uma página. É possível definir como os recursos serão enfileirados usando um dos seguintes nomes de arquivo. * é um curinga que pode ser substituído por qualquer texto de sua escolha.

Nos arquivos CSS e SCSS dos blocos, %selector% se expande para a classe envoltória específica do bloco. Isso permite selecionar o mesmo elemento que recebe bs_get_scoped_class(), mesmo quando o arquivo não é um recurso com escopo específico.

Padrão Comportamento
*.(s)css Enfileira como uma tag <link> no editor e no frontend
*.inline.(s)css Enfileira o conteúdo em uma tag <style> em linha no editor e no frontend
*.editor.(s)css Enfileira como uma tag <link> somente no editor
*.scoped.(s)css Enfileira o conteúdo com escopo em uma tag <style> em linha no editor e no frontend
*.js Enfileira como uma tag <script> no editor e no frontend
*.inline.js Enfileira o conteúdo em uma tag <script> em linha no editor e no frontend
*.editor.js Enfileira como uma tag <script> somente no editor
*.view.js Enfileira como uma tag <script> somente no frontend

Observação

A notação com hífen (*-inline.css, *-editor.css etc.) ainda é compatível com versões anteriores, mas está obsoleta. Use a notação com ponto em blocos novos.

Em linha

Estilos e scripts em linha têm a grande vantagem de serem renderizados diretamente como tags de estilo ou script na página. Isso pode acelerar o carregamento, pois evita solicitações adicionais que seriam necessárias de outra forma.

  • Arquivos .js são inseridos em linha no fim do corpo
  • Arquivos .(s)css são inseridos em linha no fim do cabeçalho
  • Cada arquivo é inserido em linha uma única vez

Folhas de estilo pequenas inline

Por padrão, um arquivo *.(s)css é vinculado, o que custa uma solicitação por arquivo. A configuração assets.inlineLimit imprime folhas de estilo pequenas inline, seguindo a regra que o núcleo de WordPress aplica aos próprios estilos: as folhas de estilo externas dos blocos de uma página são ordenadas da menor para a maior e impressas como <style> enquanto o total acumulado permanecer dentro do limite. Todos os outros arquivos mantêm sua tag <link>.

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

O limite é em bytes e 0, o valor padrão, desativa esse comportamento. Ele mede o arquivo compilado que <link> carregaria, minificado quando assets.minify.css está ativado. Somente a escolha entre <link> e <style> depende do tamanho. Cada tag permanece no lugar onde <link> estaria, portanto a ordem de carregamento e a cascata não mudam. O elemento mantém seu id.

A configuração não se aplica a arquivos *.inline.(s)css e *.scoped.(s)css, que são sempre inline, nem a recursos do editor e do admin ou a folhas de estilo extraídas de módulos JavaScript importados. Folhas de estilo globais contam como folhas de estilo de blocos. Um arquivo continua vinculado sempre que colocá-lo inline causaria alguma alteração:

  • Contém um URL relativo em url() ou @import, que é resolvido em relação à folha de estilo quando vinculado e à página quando inline. Caminhos absolutos, URLs completas, URIs data: e fragmentos # são aceitos.
  • Usa image-set() ou contém uma sequência de fechamento </style.
  • Contém escapes CSS, um abridor de comentário HTML ou uma declaração @charset. Por precaução, esses arquivos continuam vinculados para evitar alterações em URL ou na análise do documento.

Use o filtro da configuração para alterar o limite a partir de PHP:

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

O CSS colocado inline passa a fazer parte do HTML da página. É preciso limpar o cache da página após uma alteração na folha de estilo, e o navegador não pode armazenar esses bytes em cache entre páginas, por isso o limite é um total por página.

Com escopo

Os estilos com escopo também são inseridos em linha, mas recebem como prefixo um ID exclusivo para cada bloco. Use a função bs_get_scoped_class para adicionar a classe ao seu modelo.

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

O resultado acima será o seguinte estilo com escopo:

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>

Seletores comuns dentro de um arquivo com escopo ainda selecionam descendentes do elemento envoltório com escopo. Use %selector% quando quiser estilizar o próprio elemento envoltório.

Global

Além dos recursos específicos dos blocos, também é possível enfileirar recursos globais, que ficam disponíveis em todas as páginas, independentemente da presença de um bloco. Para enfileirar um recurso global, adicione o prefixo global- ao nome do arquivo. Qualquer um dos sufixos (e.g. -inline) pode ser usado em combinação.

As combinações possíveis são:

  • 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

Administração

Os recursos de administração são enfileirados somente na área de administração do WordPress. O prefixo admin- é usado para definir recursos de administração.

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

Editor de blocos

Os recursos do editor de blocos são enfileirados somente no editor de blocos. O prefixo block-editor- é usado para definir esses recursos.

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

Observação

Se WordPress desativar o iframe do editor porque um bloco do lado do cliente foi registrado com apiVersion inferior a 3, a tela do editor e a interface administrativa WordPress compartilham o mesmo documento. Scripts globais ou do editor que se associem a window, document, body, eventos de roda do mouse ou à rolagem do documento devem se proteger contra body.block-editor-page ou excluir regiões do editor WordPress, como .interface-complementary-area e .interface-navigable-region.

Ordem de carregamento

No frontend, com o enfileiramento automático de recursos e o buffer de saída ativados, Blockstudio adiciona as tags de bloco CSS <link> e <style> à página armazenada no buffer, logo antes da tag de fechamento </head>, em vez de registrá-las com wp_enqueue_style(). Assim, CSS do bloco vem depois das folhas de estilo que WordPress já imprimiu no cabeçalho, incluindo os estilos de temas e plugins enfileirados com wp_enqueue_style(), independentemente da prioridade de enfileiramento ou das dependências. Os recursos de administração e block-editor- usam, em vez disso, o sistema de enfileiramento de WordPress.

Para regras com a mesma importância, camada de cascata e especificidade, a folha de estilo do bloco prevalece sobre a folha de estilo do tema. Para mudar isso, aumente a especificidade da regra do tema ou acrescente a folha de estilo do tema ao cabeçalho Blockstudio gerado com o filtro blockstudio/render/head. O conteúdo adicionado pelo filtro é colocado após os recursos do bloco. Remova também a folha de estilo da fila de WordPress para que ela não seja carregada duas vezes.

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

O filtro head só é executado quando Blockstudio armazena a página em buffer. O armazenamento em buffer fica desativado na pré-visualização do Personalizador e quando blockstudio/buffer/enabled retorna false. bs_is_buffering() informa em qual caso você está, para que um tema possa adicionar sua folha de estilo pelo filtro quando a página estiver em buffer e enfileirá-la com WordPress nos demais casos. A resposta fica disponível a partir de wp_enqueue_scripts e é 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 se precisar reorganizar o documento final de outra maneira.

Desativar enfileiramento

O enfileiramento automático de recursos pode ser desativado usando a configuração assets/enqueue. Isso é útil se você quiser cuidar pessoalmente do enfileiramento de todos os recursos.

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

Por bloco

Quando o modelo de um bloco não retorna nada, Blockstudio não enfileira recursos para esse bloco. Esse método é útil para desativar o enfileiramento quando determinada condição é atendida.

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