# Персонализирани блокове в 3 файла

Без JavaScript, без стъпка за изграждане, без шаблонен код.

## Дефинирайте полета в JSON

Добавете ключ `blockstudio` към block.json. Дефинирайте атрибути с типове като `text`, `toggle` и `color`. Blockstudio генерира автоматично редактора UI с типове полета 27 — от текстови полета за въвеждане до повторители и редактори на код — както и типове полета, които регистрирате сами.

Пълната поддръжка на схемата JSON осигурява автоматично довършване и проверка в VS Code, PhpStorm и всеки съвместим редактор.

За всяко поле може да зададете `default` за нови блокове и `fallback`, който шаблонът получава, докато полето е празно.

[Справочник за типовете полета](https://blockstudio.dev/bg/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" }
    ]
  }
}
```

## Работа с 3 файла

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

Включете Interactivity API на WordPress с един флаг.

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

Използвайте `<RichText />` за вградено редактиране и статичен фронтенд HTML, `<InnerBlocks />` за вложени блокове и `useBlockProps` за обвивката — всичко в един шаблон.

В редактора те стават истински компоненти React. Във фронтенда се визуализират като сървърни HTML, без JavaScript да се изпраща на посетителите.

[Разгледайте компонентите](https://blockstudio.dev/bg/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 визуализира също страници, шаблони и шаблони на Редактора на сайта. По-старият wrapper `jenssegers/blade` не работи с `illuminate/view` 10 и по-нови версии, затова използвайте `Blade_Renderer` вместо него.

[Езици за шаблони](https://blockstudio.dev/bg/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/bg/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/bg/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/bg/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/bg/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/bg/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, сменяйте вътрешния шаблон от опция за избор и премахнете обвивката във фронтенда чрез филтър.

## Ресурси за полета с код

Поле с код и 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 обновява визуализацията след запазване.

## Контекст на Query Loop

В Query Loop $block[‘context’][‘postId’] следва текущия елемент, докато $block[‘postId’] остава публикацията, която се преглежда.

## WPML

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

Plus

## Официалният комплект за разширения

Премиум шаблони за сайтове, системни инструкции за AI и частна общност в Discord. Еднократна покупка, актуализации за цял живот.

- 500+ шаблона за сайтове
- Системни инструкции за AI
- Актуализации за целия период
- Частна общност на Discord

[Вземете Plus](https://blockstudio.dev/bg/plus/)
