Vai al contenuto

Guida introduttiva

Questa guida vi aiuterà a configurare Blockstudio e a creare il vostro primo blocco personalizzato.

Installazione

Shell
composer require blockstudio/blockstudio

Blockstudio può essere installato come plugin tramite composer/installers oppure incluso direttamente in un tema. Consultate la documentazione Composer per tutti i metodi di installazione.

Le installazioni di Composer ricevono gli aggiornamenti tramite Composer. L’aggiornatore integrato di GitHub viene disattivato automaticamente.

Installazione manuale

Scaricate l’ultima versione da GitHub

Caricate il file zip nella directory dei plugin di WordPress e attivate il plugin. Le installazioni manuali ricevono notifiche automatiche degli aggiornamenti nella bacheca di WordPress tramite l’aggiornatore integrato di GitHub.

Entrambi i metodi di installazione includono copie private delle librerie Markdown, YAML e di aggiornamento, insieme alle relative dipendenze. Non usano né sostituiscono le versioni fornite da altri plugin o temi. Installate la vostra dipendenza Composer se la vostra applicazione usa direttamente una di queste librerie; le copie incluse da Blockstudio sono interne, non una PHP API pubblica.

Controlli degli aggiornamenti autenticati

Per impostazione predefinita, le installazioni manuali verificano GitHub in forma anonima. Più siti che condividono un unico IP in uscita possono esaurire la quota anonima di GitHub per API e ricevere risposte HTTP 403 durante la verifica degli aggiornamenti. Da 7.7.4, configurate un token di accesso personale GitHub in wp-config.php, prima che venga caricato WordPress:

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

Il token deve solo consentire l’accesso alle informazioni sui repository pubblici. Non concedete permessi di scrittura. Conservatelo nella configurazione lato server, fuori dal controllo di versione e fuori da blockstudio.json, dagli attributi dei blocchi e dal codice frontend. L’aggiornatore lo passa al client GitHub incluso per le verifiche autenticate e il download delle versioni. Il token non viene inviato alle richieste verso repository non correlati o altri host di download.

Per i segreti gestiti tramite ambiente, un plugin MU può fornire o sovrascrivere il token:

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

Il filtro viene eseguito quando Blockstudio inizializza il proprio sistema di aggiornamento, prima che venga caricato il tema. Registratelo in un plugin MU, anziché in functions.php. Restituire una stringa vuota disabilita l’autenticazione anche se la costante è definita. I valori vuoti o non stringa mantengono anonime le verifiche. I token sono facoltativi; senza, il comportamento esistente degli aggiornamenti resta invariato. Le installazioni Composer continuano a usare Composer per gli aggiornamenti e non inizializzano questo sistema.

Creare il primo blocco

1. Creare una directory per il blocco

Create una nuova directory nel vostro tema:

Codice
my-theme/
  blockstudio/
    my-first-block/
      block.json
      index.php

2. Definire lo schema del blocco

Create block.json con la configurazione del blocco:

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. Creare il template

Create index.php per il rendering:

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

Usare i template Twig

Blockstudio supporta i template Twig fin da subito. Vi basta usare index.twig:

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

Aggiungere gli stili

Create un file style.css nella stessa cartella:

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

Blockstudio accoderà automaticamente questo foglio di stile quando viene usato il blocco.

Traduzioni

I controlli dell’editor e la panoramica di amministrazione di Blockstudio caricano le traduzioni JavaScript per il dominio di testo blockstudio tramite WordPress. Installate il pacchetto linguistico corrispondente oppure generate i file JSON delle traduzioni degli script con il vostro strumento di traduzione in wp-content/languages/plugins/. Le stringhe senza una traduzione disponibile restano in inglese. Questa procedura traduce l’interfaccia di Blockstudio, non i contenuti o le etichette dei campi che definite nei vostri blocchi.

Passaggi successivi

Il vostro blocco è pronto per essere usato nell’editor WordPress. Continuate a esplorare la documentazione per scoprire:

Creare una libreria di blocchi

Passate da un singolo blocco a una libreria completa: token di design, pattern di sezione, repeater, immagini e composizione delle pagine.