Guida introduttiva
Questa guida vi aiuterà a configurare Blockstudio e a creare il vostro primo blocco personalizzato.
Installazione
Tramite Composer (consigliato)
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:
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
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:
my-theme/
blockstudio/
my-first-block/
block.json
index.php
2. Definire lo schema del blocco
Create block.json con la configurazione del blocco:
{
"$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:
<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:
<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:
.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:
- Tipi di campo – Tutti i tipi di campo disponibili
- Componenti – InnerBlocks, RichText e altro
- Tailwind Integrazione – Come usare Tailwind CSS
- Hook – Estendere le funzionalità con filtri e azioni
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.