# Власні блоки у 3 файлах

Без JavaScript, кроку збирання й шаблонного коду.

## Визначайте поля в JSON

Додайте ключ `blockstudio` до block.json. Визначте атрибути з типами, як-от `text`, `toggle` і `color`. Blockstudio автоматично генерує UI редактора з 27 типами полів: від текстових полів введення до повторювачів і редакторів коду, а також типами полів, які ви зареєструєте самостійно.

Повна підтримка схеми JSON забезпечує автодоповнення й перевірку в VS Code, PhpStorm та всіх сумісних редакторах.

Для кожного поля можна задати `default` для нових блоків і `fallback`, яке шаблон отримує, поки поле порожнє.

[Довідник типів полів](https://blockstudio.dev/uk/docs/blocks/attributes/field-types/)

block.json

```
{
  "name": "starter/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      { "id": "showCta", "type": "toggle", "label": "Show CTA" },
      { "id": "background", "type": "color", "label": "Background" }
    ]
  }
}
```

## Робочий процес із трьома файлами

block.json для полів, шаблон для розмітки та необов’язкова таблиця стилів.

## React у PHP

RichText, InnerBlocks і useBlockProps безпосередньо працюють у PHP, Twig або Blade.

## SCSS та Tailwind

Використовуйте CSS, SCSS або Tailwind. SCSS підтримує шляхи імпорту та спільний прелюд, а редагування вкладеної часткової заготовки перекомпілює кожен файл, що її імпортує.

## 27 типів полів

Текст, колір, зображення, повторювач, список вибору, редактор коду та інше — налаштовуються в JSON.

## JSON Schema

Автодоповнення й перевірка в VS Code, PhpStorm та сумісних редакторах.

## Три мови шаблонів

PHP, Twig і Blade використовують ті самі змінні та компоненти.

## Імпорт npm

Імпортуйте пакети в script.js; у виробничому середовищі вони локальні, а в редакторі підтримуються через CDN.

## Interactivity API

Увімкніть інтерактивність WordPress одним прапорцем API.

## Компоненти React у шаблонах PHP

Використовуйте `<RichText />` для вбудованого редагування та статичних елементів HTML фронтенду, `<InnerBlocks />` для дочірніх блоків і `useBlockProps` для обгортки — усе в одному шаблоні.

У редакторі вони стають повноцінними компонентами React. На фронтенді вони відображаються як серверний HTML без JavaScript, що надсилається відвідувачам.

[Переглянути компоненти](https://blockstudio.dev/uk/docs/blocks/react-components/)

index.php

```
<div useBlockProps class="container">
  <RichText
    class="text-xl font-semibold"
    tag="h1"
    attribute="headline"
    placeholder="Enter headline"
  />

  <?php if ($a['showCta']): ?>
    <a href="<?= esc_url($a['ctaUrl']) ?>">
      <?= esc_html($a['ctaLabel']) ?>
    </a>
  <?php endif; ?>

  <InnerBlocks class="mt-4 p-4 border" />
</div>
```

## Пишіть на PHP, Twig або Blade

Використовуйте знайому вам мову шаблонів. PHP працює одразу після встановлення, Twig запускається після встановлення Timber, а Blade — на `illuminate/view` версій 8–12 через `Blockstudio\Blade_Renderer`. Змінні, компоненти й поведінка залишаються однаковими.

`$a` (атрибути), `$b` (блок), `$c` (контекст) і `$innerBlocks` доступні в кожній мові.

Twig шаблони також отримують повний контекст Timber. Blade також відображає сторінки, патерни та шаблони редактора сайту. Старіша обгортка `jenssegers/blade` не працює з `illuminate/view` 10 і новішими версіями, тому використовуйте натомість `Blade_Renderer`.

[Мови шаблонів](https://blockstudio.dev/uk/docs/blocks/templating/blade/)

index.twig

```
<div useBlockProps class="card">
  <RichText tag="h2" attribute="title" placeholder="Card title" />
  {% if a.image %}
    <img src="{{ a.image.url|esc_url }}"
      alt="{{ a.image.alt|esc_attr }}" />
  {% endif %}
  <div class="card__body">{{ a.description|esc_html }}</div>
  <InnerBlocks allowedBlocks='["core/button"]' />
</div>
```

## Умовна логіка та динамічні параметри

Показуйте й приховуйте поля за допомогою операторів, зокрема `==`, `!=`, `includes`, `empty` та порівнянь. Поєднуйте умови за допомогою логіки OR.

Параметри можуть залежати від іншого поля. Додайте `{attributes.post_type.value}` до аргументів заповнення, і список перезавантажуватиметься, коли це поле зміниться. Додайте `fetch: true`, щоб шукати записи, поки редактор вводить текст.

Використовуйте `type: custom` і фільтр `blockstudio/blocks/attributes/populate`, щоб спільно використовувати список параметрів у блоках, а власні глобальні умови, наприклад перевірку покупки, реєструйте через `blockstudio/blocks/conditions`.

[Умовна логіка](https://blockstudio.dev/uk/docs/blocks/attributes/conditional-logic/)

block.json

```
{
  "name": "starter/posts",
  "title": "Posts",
  "blockstudio": {
    "attributes": [
      {
        "id": "post_type",
        "type": "select",
        "label": "Post type",
        "options": [
          { "value": "page", "label": "Pages" },
          { "value": "post", "label": "Posts" }
        ]
      },
      {
        "id": "selected_post",
        "type": "select",
        "label": "Post",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": { "post_type": "{attributes.post_type.value}" }
        }
      },
      {
        "id": "style",
        "type": "select",
        "label": "Style",
        "populate": { "type": "custom", "custom": "cardStyles" },
        "conditions": [[
          { "type": "purchasedProduct", "operator": "==", "value": "yes" }
        ]]
      }
    ]
  }
}
```

## Зручні в керуванні повторювачі

Задайте `min` та `max`, створюйте нові блоки з `default` рядками та згортайте наявні рядки за допомогою `minimized`. `textMinimized` задає для згорнутого рядка мітку з одного з його власних полів, наприклад імені.

Рядки підтримують усі типи полів, крім вкладок, зокрема вкладені повторювачі. Умова всередині рядка перевіряє поле поза ним за допомогою `"context": "main"`, а `<RichText />` і `<MediaPlaceholder />` редагують один рядок, якщо їхній `attribute` вказує на `repeaterId[index].fieldId`.

[Шаблони повторювачів](https://blockstudio.dev/uk/guides/field-patterns/#repeater-patterns)

block.json

```
{
  "name": "starter/team",
  "title": "Team",
  "blockstudio": {
    "attributes": [
      {
        "id": "members",
        "type": "repeater",
        "label": "Team members",
        "min": 1,
        "max": 12,
        "minimized": true,
        "textMinimized": { "id": "name", "fallback": "Team member" },
        "attributes": [
          { "id": "name", "type": "text", "label": "Name" },
          { "id": "bio", "type": "richtext", "label": "Bio" }
        ]
      }
    ]
  }
}
```

## Повторно використовувані набори полів

Один раз визначте групу полів у `field.json` і використовуйте її в будь-якому блоці за допомогою `"type": "custom/cta"`. Поля вставляються безпосередньо, тож шаблони читають їх як будь-який інший атрибут.

Використовуйте той самий набір двічі за допомогою `idStructure`, наприклад `hero_{id}`, а мітки, значення за замовчуванням чи умови для кожного блоку змінюйте через `overrides`. Тип поля `block` робить те саме з цілим блоком: розгортає його поля безпосередньо та повертає його відрендерений HTML.

[Власні поля](https://blockstudio.dev/uk/docs/blocks/attributes/custom-fields/)

fields/cta/field.json

```
{
  "name": "cta",
  "title": "Call to action",
  "attributes": [
    { "id": "label", "type": "text", "label": "Button label", "default": "Learn more" },
    { "id": "url", "type": "link", "label": "Button URL" }
  ]
}
```

## ES-модулі без кроку збирання

Додайте `script.js`, і він завантажуватиметься як ES-модуль. Імпортуйте пакети npm із префіксом `npm:`, а Blockstudio завантажить їх локально для виробничого середовища.

Редактор одразу показує попередній перегляд, а фронтенд використовує локальні модулі без зовнішніх залежностей, додаючи їх у чергу лише один раз.

Таблиці стилів імпортуються так само. `import "npm:swiper@11.0.0/swiper.min.css"` завантажує файл і додає його до черги один раз для кожної версії, навіть якщо його використовують кілька блоків.

[Обробка ресурсів](https://blockstudio.dev/uk/docs/blocks/assets/)

script.js

```
import Swiper from "npm:swiper@11.0.0";
import "npm:swiper@11.0.0/swiper.min.css";

for (const el of document.querySelectorAll(".swiper")) {
  new Swiper(el, {
    slidesPerView: 3,
    spaceBetween: 20,
    loop: true,
  });
}
```

## Теги блоків поза шаблонами

Зіставте короткий префікс із простором імен у `blockstudio.json` або прив’яжіть один тег до одного блоку за допомогою фільтра псевдонімів, і `<acme-card>` відобразить `acme/card`. Увімкніть `blockTags.enabled`, щоб відображати теги у вмісті записів і віджетах; їх обмежують шаблони `allow` і `deny`.

Атрибути `data-*` потрапляють до кореневого елемента блоку, а атрибути `html-*` надходять туди без префікса. Додавайте власні генератори тегів за допомогою `blockstudio/block_tags/builders`, а скорочення перетворюйте на переносний запис `<bs:acme-card>` за допомогою команди `migrate-block-tags`.

[Читати посібник](https://blockstudio.dev/uk/guides/block-tags/)

blockstudio.json

```
{
  "blockTags": {
    "enabled": true,
    "prefixes": {
      "acme": ["acme"],
      "ui": ["acme-ui"]
    },
    "deny": ["acme-ui/admin-*"]
  }
}
```

## Власні типи полів

Зареєструйте власний елемент керування полем і використовуйте його як вбудоване поле.

## Острівці блоків

Кешуйте всю сторінку й відображайте один блок під час запиту відвідувача.

## Умовна реєстрація

Реєструйте блок лише для певного типу запису, ролі користувача чи іншої глобальної умови або пропускайте його, якщо потрібний плагін чи його версія відсутні.

## Метадані дописів і параметри

Зберігайте значення в метаданих дописів або параметрах разом з атрибутами блоку.

## Умовна логіка

Показуйте поля відповідно до значень, використовуючи перевірки на рівність, входження, порожнечу й порівняння.

## Динамічне заповнення

Заповнюйте варіанти даними з дописів, користувачів, термінів, функцій або API.

## Перевизначення

Задайте override: true для назви спільного блоку, щоб об’єднати атрибути за ідентифікатором, замінити ресурси з відповідними назвами файлів і змінити шаблон. Шаблони Twig можуть перевизначати окремі блоки за допомогою extends.

## Варіанти

Оголошуйте варіації в block.json, щоб задавати початкові значення полів, а поле, яке ними керує, приховуйте за допомогою hidden.

## Компоненти

Задайте component: true для блоку, який відображається лише з PHP або тегів блоків. Він зберігає поля, шаблони, ресурси та Tailwind, але ніколи не з’являється у вставці.

## Правила InnerBlocks

Дозвольте блоки з токенами namespace/*, category: і @theme, перемикайте внутрішній шаблон за допомогою параметра select і прибирайте обгортку на зовнішній частині сайту через фільтр.

## Ресурси поля коду

Поле коду з asset: true перетворює введений у редакторі код на CSS, SCSS або JavaScript для цього блоку; область дії обмежується екземпляром через %selector%.

## Ресурси за іменем файлу

*.view.js завантажується лише на зовнішній частині сайту, а файли з префіксами global-, admin- і block-editor- завантажуються на кожній сторінці, у wp-admin або в редакторі блоків відповідно.

## Піктограми та папки блоків

Призначте блоку власну піктограму SVG або HTML, змініть шлях пошуку за допомогою фільтра blockstudio/path і додавайте папки через Blockstudio\Build::init().

## Значення ACF та Meta Box

Шаблони отримують $post_id, тож get_field() і rwmb_get_value() читають відредагований запис, а refreshOn оновлює попередній перегляд після збереження.

## Контекст циклу запитів

У циклі запитів $block[‘context’][‘postId’] відповідає поточному елементу, тоді як $block[‘postId’] залишається ідентифікатором запису, який переглядають.

## WPML

wp bs wpml config записує wpml-config.xml, який позначає текстові поля як такі, що перекладаються, а зображення, збережені в полях, долучаються до завдань перекладу WPML разом із альтернативними текстами та підписами.

Plus

## Офіційний набір розширень

Преміумшаблони сайтів, системні інструкції для ШІ та приватна спільнота Discord. Одноразова покупка, довічні оновлення.

- Понад 500 шаблонів сайтів
- Системні інструкції для ШІ
- Оновлення назавжди
- Приватна спільнота Discord

[Отримати Plus](https://blockstudio.dev/uk/plus/)
