Pular para o conteúdo

Primeiros passos

Este guia ajudará você a configurar Blockstudio e criar seu primeiro bloco personalizado.

Instalação

Shell
composer require blockstudio/blockstudio

Blockstudio pode ser instalado como um plugin via composer/installers ou incluído diretamente em um tema. Consulte a documentação Composer para conhecer todos os métodos de instalação.

Instalações de Composer recebem atualizações por meio de Composer. O atualizador GitHub integrado é desativado automaticamente.

Instalação manual

Baixe a versão mais recente em GitHub

Envie o arquivo zip para o diretório de plugins do WordPress e ative o plugin. Instalações manuais recebem notificações automáticas de atualização no painel do WordPress por meio do atualizador GitHub integrado.

Ambos os métodos de instalação incluem cópias privadas das bibliotecas Markdown, YAML e de atualização, além de suas dependências. Eles não usam nem substituem versões fornecidas por outro plugin ou tema. Instale sua própria dependência Composer se a sua aplicação usar diretamente uma dessas bibliotecas; as cópias incluídas em Blockstudio são internas, não uma PHP API pública.

Verificações de atualização autenticadas

Por padrão, instalações manuais verificam GitHub anonimamente. Vários sites que compartilham um mesmo IP de saída podem esgotar a cota API anônima de GitHub e receber respostas 403 HTTP ao verificar atualizações. Em 7.7.4, configure um token de acesso pessoal GitHub em wp-config.php, antes de WordPress carregar:

PHP
define('BLOCKSTUDIO_GITHUB_TOKEN', 'your-github-token');

O token só precisa de acesso a informações de repositórios públicos. Não conceda permissões de escrita. Mantenha-o na configuração do lado do servidor, fora do controle de versão e de blockstudio.json, dos atributos de bloco e do código do frontend. O atualizador o repassa ao cliente GitHub incluído para verificações autenticadas e downloads de versões. As solicitações a repositórios não relacionados e a outros hosts de download não recebem o token.

Para segredos gerenciados pelo ambiente, um plugin MU pode fornecer ou substituir o token:

PHP
<?php
add_filter('blockstudio/updater/token', function ($token) {
  return getenv('BLOCKSTUDIO_GITHUB_TOKEN') ?: $token;
});

O filtro é executado quando Blockstudio inicializa seu atualizador, antes de o tema carregar. Registre-o em um plugin MU, em vez de em functions.php. Retornar uma string vazia desativa a autenticação mesmo quando a constante está definida. Valores vazios ou que não sejam strings mantêm as verificações anônimas. Os tokens são opcionais; sem um, o comportamento atual das atualizações não muda. Instalações Composer ainda usam Composer para atualizações e não inicializam este atualizador.

Criando seu primeiro bloco

1. Crie um diretório para o bloco

Crie um novo diretório no seu tema:

Código
my-theme/
  blockstudio/
    my-first-block/
      block.json
      index.php

2. Defina o esquema do bloco

Crie block.json com a configuração do seu bloco:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "my-theme/my-first-block",
  "title": "My First Block",
  "category": "common",
  "icon": "star-filled",
  "blockstudio": {
    "attributes": [
      {
        "id": "heading",
        "type": "text",
        "label": "Heading",
        "default": "Hello World"
      },
      {
        "id": "content",
        "type": "textarea",
        "label": "Content"
      }
    ]
  }
}

3. Crie o modelo

Crie index.php para renderização:

PHP
<div class="my-first-block">
  <h2><?php echo $a['heading']; ?></h2>
  <p><?php echo $a['content']; ?></p>
</div>

Usando modelos Twig

Blockstudio oferece suporte a modelos Twig pronto para uso. Basta usar index.twig:

Twig
<div class="my-first-block">
  <h2>{{ a.heading }}</h2>
  <p>{{ a.content }}</p>
</div>

Adicionando estilos

Crie um arquivo style.css na mesma pasta:

CSS
.my-first-block {
  padding: 2rem;
  background: #f5f5f5;
}

Blockstudio adicionará automaticamente esta folha de estilos quando o bloco for usado.

Traduções

Os controles do editor e a visão geral administrativa de Blockstudio carregam traduções JavaScript para o domínio de texto blockstudio por meio de WordPress. Instale um pacote de idioma correspondente ou gere arquivos JSON de tradução de scripts com sua ferramenta de tradução em wp-content/languages/plugins/. As strings sem tradução disponível permanecem em inglês. Isso traduz a própria interface de Blockstudio, não o conteúdo nem os rótulos de campo que você define nos seus blocos.

Próximas etapas

Seu bloco está pronto para uso no editor WordPress. Continue explorando a documentação para saber mais sobre:

Criando uma biblioteca de blocos

Passe de um único bloco para uma biblioteca completa: tokens de design, o padrão de seção, repetidores, imagens e composição de páginas.