Aller au contenu

Premiers pas

Ce guide vous aidera à configurer Blockstudio et à créer votre premier bloc personnalisé.

Installation

Shell
composer require blockstudio/blockstudio

Blockstudio peut être installé comme extension via composer/installers ou intégré directement à un thème. Consultez la documentation de Composer pour découvrir toutes les méthodes d’installation.

Les installations de Composer reçoivent leurs mises à jour via Composer. Le programme de mise à jour intégré de GitHub est automatiquement désactivé.

Installation manuelle

Téléchargez la dernière version depuis GitHub

Téléversez le fichier zip dans le répertoire des extensions de votre WordPress et activez l’extension. Les installations manuelles reçoivent des notifications automatiques de mise à jour dans le tableau de bord WordPress via le programme de mise à jour intégré de GitHub.

Les deux méthodes d’installation regroupent des copies privées des bibliothèques Markdown, YAML et de mise à jour, ainsi que de leurs dépendances. Elles n’utilisent pas et ne remplacent pas les versions fournies par une autre extension ou un autre thème. Installez votre propre dépendance Composer si votre application utilise directement l’une de ces bibliothèques ; les copies regroupées par Blockstudio sont internes et ne constituent pas une PHP API publique.

Vérifications de mise à jour authentifiées

Par défaut, les installations manuelles vérifient GitHub de façon anonyme. Plusieurs sites partageant une même IP sortante peuvent épuiser le quota GitHub anonyme de API et recevoir des réponses HTTP 403 lors de la recherche de mises à jour. Depuis 7.7.4, configurez un jeton d’accès personnel GitHub dans wp-config.php, avant le chargement de WordPress :

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

Le jeton doit uniquement permettre d’accéder aux informations des dépôts publics. Ne lui accordez pas de permissions d’écriture. Conservez-le dans la configuration côté serveur, hors du contrôle de version, et hors de blockstudio.json, des attributs de bloc et du code frontal. Pour les vérifications authentifiées et le téléchargement des versions, le programme de mise à jour le transmet à son client GitHub intégré. Le jeton n’est pas transmis aux requêtes vers des dépôts sans rapport ni vers d’autres hôtes de téléchargement.

Pour les secrets gérés par l’environnement, une extension MU peut fournir ou remplacer le jeton :

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

Le filtre s’exécute lorsque Blockstudio initialise son programme de mise à jour, avant le chargement du thème. Enregistrez-le dans une extension MU plutôt que dans functions.php. Le renvoi d’une chaîne vide désactive l’authentification, même si la constante est définie. Les valeurs vides ou qui ne sont pas des chaînes laissent les vérifications anonymes. Les jetons sont facultatifs ; sans jeton, le comportement de mise à jour existant reste inchangé. Les installations Composer continuent d’utiliser Composer pour les mises à jour et n’initialisent pas ce programme de mise à jour.

Création de votre premier bloc

1. Créer un répertoire de bloc

Créez un nouveau répertoire dans votre thème :

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

2. Définir le schéma du bloc

Créez block.json avec la configuration de votre bloc :

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. Créer le modèle

Créez index.php pour le rendu :

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

Utilisation des modèles Twig

Blockstudio prend en charge les modèles Twig d’emblée. Utilisez simplement index.twig à la place :

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

Ajout de styles

Créez un fichier style.css dans le même dossier :

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

Blockstudio chargera automatiquement cette feuille de style lorsque le bloc sera utilisé.

Traductions

Les commandes de l’éditeur et la vue d’ensemble de l’administration de Blockstudio chargent les traductions JavaScript pour le domaine de texte blockstudio via WordPress. Installez un pack linguistique correspondant ou générez des fichiers JSON de traduction des scripts avec votre outil de traduction dans wp-content/languages/plugins/. Les chaînes sans traduction disponible restent en anglais. Cela traduit l’interface propre à Blockstudio, et non le contenu ou les libellés de champs que vous définissez dans vos blocs.

Étapes suivantes

Votre bloc est maintenant prêt à être utilisé dans l’éditeur WordPress. Parcourez la documentation pour en savoir plus sur :

Créer une bibliothèque de blocs

Passez d’un seul bloc à une bibliothèque complète : jetons de conception, modèle de section, champs répétables, images et composition de pages.