Перейти к содержимому

Начало работы

Это руководство поможет вам настроить Blockstudio и создать свой первый пользовательский блок.

Установка

Командная оболочка
composer require blockstudio/blockstudio

Blockstudio можно установить как плагин через composer/installers или включить непосредственно в тему. Все способы установки описаны в документации Composer.

Установки Composer получают обновления через Composer. Встроенный механизм обновления GitHub автоматически отключается.

Установка вручную

Скачайте последнюю версию с сайта GitHub

Загрузите zip-архив в каталог плагинов WordPress и активируйте плагин. При ручной установке уведомления об обновлениях автоматически появляются в панели управления WordPress через встроенный механизм обновления GitHub.

Оба способа установки включают собственные копии библиотек Markdown, YAML и обновления вместе с их зависимостями. Они не используют и не заменяют версии, предоставленные другими плагинами или темами. Установите собственную зависимость Composer, если ваше приложение напрямую использует одну из этих библиотек; включенные в Blockstudio копии являются внутренними и не представляют собой общедоступный PHP API.

Проверка обновлений с аутентификацией

При ручной установке проверка GitHub по умолчанию выполняется анонимно. Несколько сайтов, использующих один исходящий IP, могут исчерпать лимит анонимных запросов API для GitHub и получать ответы 403 HTTP при проверке обновлений. В 7.7.4 настройте персональный токен доступа GitHub в wp-config.php до загрузки WordPress:

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

Токену нужен доступ только к сведениям о публичных репозиториях. Не предоставляйте разрешения на запись. Храните его в серверной конфигурации, вне системы контроля версий, а также вне blockstudio.json, атрибутов блоков и кода фронтенда. Обновляющая система передает его встроенному клиенту GitHub для аутентифицированной проверки и загрузки выпусков. Токен не передается запросам к сторонним репозиториям и другим хостам загрузки.

Для секретов, управляемых через окружение, MU-плагин может передать или переопределить токен:

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

Фильтр выполняется при инициализации обновляющей системы Blockstudio, до загрузки темы. Зарегистрируйте его в MU-плагине, а не в functions.php. Пустая строка отключает аутентификацию, даже если константа определена. Пустые значения и значения не в виде строк оставляют проверку анонимной. Токены необязательны: без токена поведение обновлений остается прежним. Установки Composer по-прежнему используют Composer для обновлений и не инициализируют эту систему.

Создание первого блока

1. Создайте каталог блока

Создайте новый каталог в своей теме:

Код
my-theme/
  blockstudio/
    my-first-block/
      block.json
      index.php

2. Опишите схему блока

Создайте block.json с конфигурацией блока:

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. Создайте шаблон

Создайте index.php для рендеринга:

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

Использование шаблонов Twig

Blockstudio поддерживает шаблоны Twig из коробки. Просто используйте index.twig:

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

Добавление стилей

Создайте файл style.css в той же папке:

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

Blockstudio автоматически подключит эту таблицу стилей при использовании блока.

Переводы

В редакторе Blockstudio и в обзоре панели администратора загружаются переводы JavaScript для текстового домена blockstudio через WordPress. Установите соответствующий языковой пакет или создайте файлы переводов скриптов JSON с помощью инструмента перевода в wp-content/languages/plugins/. Строки без доступного перевода остаются на английском. Это переводит собственный интерфейс Blockstudio, но не содержимое блоков и не заданные вами названия полей.

Следующие шаги

Теперь ваш блок готов к использованию в редакторе WordPress. Изучите другие разделы документации, чтобы узнать о следующем:

Создание библиотеки блоков

Перейдите от одного блока к полноценной библиотеке: токены дизайна, шаблон секции, повторяющиеся элементы, изображения и компоновка страниц.