# Własne bloki w 3 plikach

Bez JavaScript, etapu budowania i zbędnego kodu.

## Definiuj pola w JSON

Dodaj klucz `blockstudio` do block.json. Zdefiniuj atrybuty z typami, takimi jak `text`, `toggle` i `color`. Blockstudio automatycznie generuje edytor UI z 27 typami pól — od pól tekstowych po repeatery i edytory kodu — a także typami pól rejestrowanymi samodzielnie.

Pełna obsługa schematu JSON zapewnia uzupełnianie kodu i walidację w VS Code, PhpStorm oraz każdym zgodnym edytorze.

Każde pole może określać `default` dla nowych bloków oraz `fallback`, który szablon otrzymuje, gdy pole jest puste.

[Opis typów pól](https://blockstudio.dev/pl/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" }
    ]
  }
}
```

## Praca z 3 plikami

block.json do pól, szablon dla znaczników i opcjonalny arkusz stylów.

## React w PHP

RichText, InnerBlocks i useBlockProps działają bezpośrednio w PHP, Twig lub Blade.

## SCSS i Tailwind

Użyj CSS, SCSS lub Tailwind. SCSS obsługuje ścieżki importu i wspólny preambułę, a edycja zagnieżdżonego fragmentu powoduje ponowną kompilację każdego pliku, który go importuje.

## 27 typów pól

Tekst, kolor, obraz, powtarzalne pole, wybór, edytor kodu i więcej — konfigurujesz w JSON.

## JSON Schema

Uzupełnianie kodu i walidacja w VS Code, PhpStorm oraz zgodnych edytorach.

## Trzy języki szablonów

PHP, Twig i Blade korzystają z tych samych zmiennych i komponentów.

## Importy npm

Importuj pakiety w script.js; w środowisku produkcyjnym lokalnie, a w edytorze z obsługą CDN.

## Interactivity API

Włącz Interactivity API WordPress za pomocą jednej flagi.

## Komponenty React w szablonach PHP

Użyj `<RichText />` do edycji w tekście i statycznego interfejsu HTML, `<InnerBlocks />` dla bloków podrzędnych oraz `useBlockProps` dla kontenera — wszystko w jednym szablonie.

W edytorze stają się one prawdziwymi komponentami React. Interfejs renderuje je po stronie serwera jako HTML, bez wysyłania do odwiedzających JavaScript.

[Poznaj komponenty](https://blockstudio.dev/pl/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>
```

## Pisz w PHP, Twig lub Blade

Używaj znanego Ci języka szablonów. PHP działa od razu po instalacji, Twig uruchamia się po zainstalowaniu Timber, a Blade działa na `illuminate/view` od 8 do 12 za pośrednictwem `Blockstudio\Blade_Renderer`. Zmienne, komponenty i działanie pozostają takie same.

`$a` (atrybuty), `$b` (blok), `$c` (kontekst) i `$innerBlocks` są dostępne w każdym języku.

Twig szablony również otrzymują pełny kontekst Timber. Blade renderuje także strony, wzorce i szablony Edytora witryny. Starszy wrapper `jenssegers/blade` nie działa z `illuminate/view` 10 i nowszymi wersjami, dlatego używaj `Blade_Renderer`.

[Języki szablonów](https://blockstudio.dev/pl/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>
```

## Logika warunkowa i opcje dynamiczne

Pokazuj i ukrywaj pola za pomocą operatorów takich jak `==`, `!=`, `includes`, `empty` oraz porównań. Łącz warunki za pomocą logiki OR.

Opcje mogą zależeć od innego pola. Dodaj `{attributes.post_type.value}` do argumentów wypełniania, a lista zostanie ponownie wczytana po zmianie tego pola. Dodaj `fetch: true`, aby wyszukiwać wpisy podczas pisania przez edytora.

Udostępniaj jedną listę opcji między blokami za pomocą `type: custom` i filtra `blockstudio/blocks/attributes/populate`, a własne warunki globalne, takie jak sprawdzanie zakupu, rejestruj przez `blockstudio/blocks/conditions`.

[Logika warunkowa](https://blockstudio.dev/pl/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" }
        ]]
      }
    ]
  }
}
```

## Repeatery, nad którymi łatwo zapanować

Ustaw `min` i `max`, rozpoczynaj nowe bloki z `default` wierszami i zwijaj istniejące wiersze za pomocą `minimized`. `textMinimized` oznacza zwinięty wiersz wartością jednego z jego pól, na przykład nazwą.

Wiersze obsługują wszystkie typy pól poza kartami, w tym zagnieżdżone repeatery. Warunek wewnątrz wiersza sprawdza pole spoza niego za pomocą `"context": "main"`, a `<RichText />` i `<MediaPlaceholder />` edytują pojedynczy wiersz, gdy ich `attribute` wskazuje na `repeaterId[index].fieldId`.

[Wzorce repeaterów](https://blockstudio.dev/pl/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" }
        ]
      }
    ]
  }
}
```

## Zestawy pól wielokrotnego użytku

Zdefiniuj grupę pól raz w `field.json` i odwołuj się do niej z dowolnego bloku za pomocą `"type": "custom/cta"`. Pola są wstawiane bezpośrednio, więc szablony odczytują je jak każdy inny atrybut.

Użyj tego samego zestawu dwa razy za pomocą `idStructure`, na przykład `hero_{id}`, a etykiety, wartości domyślne lub warunki zmieniaj dla każdego bloku przez `overrides`. Typ pola `block` robi to samo z całym blokiem: rozwija jego pola bezpośrednio i zwraca wyrenderowane HTML tego bloku.

[Pola niestandardowe](https://blockstudio.dev/pl/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" }
  ]
}
```

## Moduły ES bez etapu budowania

Dodaj `script.js`, a zostanie załadowany jako moduł ES. Importuj pakiety npm z prefiksem `npm:`, a Blockstudio pobierze je lokalnie na potrzeby środowiska produkcyjnego.

Edytor natychmiast wyświetla podgląd, a interfejs korzysta z lokalnych modułów bez zależności zewnętrznych; są one dołączane tylko raz.

Arkusze stylów importuje się tak samo. `import "npm:swiper@11.0.0/swiper.min.css"` pobiera plik i dodaje go do kolejki raz dla każdej wersji, nawet jeśli korzysta z niego kilka bloków.

[Przetwarzanie zasobów](https://blockstudio.dev/pl/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,
  });
}
```

## Tagi bloków poza szablonami

Przypisz krótki prefiks do przestrzeni nazw w `blockstudio.json` albo jeden tag do jednego bloku za pomocą filtra aliasów, a `<acme-card>` wyrenderuje `acme/card`. Włącz `blockTags.enabled`, aby renderować tagi w treści wpisów i widżetach, z ograniczeniem do wzorców `allow` i `deny`.

Atrybuty `data-*` trafiają do elementu głównego bloku, a atrybuty `html-*` docierają tam bez prefiksu. Dodawaj własne konstruktory tagów za pomocą `blockstudio/block_tags/builders` i przepisuj skrócone zapisy na przenośną postać `<bs:acme-card>` poleceniem `migrate-block-tags`.

[Przeczytaj poradnik](https://blockstudio.dev/pl/guides/block-tags/)

blockstudio.json

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

## Niestandardowe typy pól

Zarejestruj własne pole sterujące i używaj go jak wbudowanego pola.

## Wyspy bloków

Zapisz całą stronę w pamięci podręcznej i renderuj jeden blok w ramach żądania odwiedzającego.

## Warunkowa rejestracja

Rejestruj blok tylko dla danego typu wpisu, roli użytkownika lub innego warunku globalnego albo pomiń go, gdy brakuje wymaganej wtyczki lub jej wersji.

## Metadane wpisów i opcje

Przechowuj wartości w metadanych wpisu lub opcjach obok atrybutów bloku.

## Logika warunkowa

Wyświetlaj pola na podstawie wartości, korzystając z równości, zawierania, pustych wartości i porównań.

## Dynamiczne źródła danych

Wypełniaj opcje danymi z wpisów, użytkowników, taksonomii, funkcji lub API.

## Nadpisywanie

Ustaw override: true wraz z nazwą wspólnego bloku, aby scalać atrybuty według identyfikatora, zastępować zasoby o pasujących nazwach plików i podmieniać szablon. Szablony Twig mogą nadpisywać pojedyncze bloki za pomocą extends.

## Warianty

Zadeklaruj warianty w block.json, aby ustawiały wstępnie wartości pól, i ukryj pole, które nimi steruje, za pomocą hidden.

## Komponenty

Ustaw component: true dla bloku renderowanego wyłącznie z PHP lub tagów bloków. Zachowuje pola, szablony, zasoby i Tailwind, ale nigdy nie pojawia się w inserterze.

## Zasady InnerBlocks

Zezwalaj na bloki z tokenami namespace/*, category: i @theme, zmieniaj szablon wewnętrzny za pomocą opcji select i usuwaj wrapper na stronie przez filtr.

## Zasoby pola kodu

Pole kodu z asset: true zamienia dane wejściowe edytora na CSS, SCSS lub JavaScript dla danego bloku, ograniczone do instancji przez %selector%.

## Zasoby według nazwy pliku

*.view.js ładuje plik tylko na stronie, a prefiksy global-, admin- i block-editor- ładują plik na każdej stronie, w wp-admin lub w edytorze bloków.

## Ikony i foldery bloków

Nadaj blokowi własną ikonę SVG lub HTML, zmień miejsce wyszukiwania za pomocą filtra blockstudio/path i dodawaj foldery przez Blockstudio\Build::init().

## Wartości ACF i Meta Box

Szablony otrzymują $post_id, więc get_field() i rwmb_get_value() odczytują edytowany wpis, a refreshOn odświeża podgląd po zapisaniu.

## Kontekst pętli zapytań

W pętli zapytań $block[‘context’][‘postId’] podąża za bieżącym elementem, a $block[‘postId’] pozostaje wpisem, który jest wyświetlany.

## WPML

wp bs wpml config zapisuje wpml-config.xml, które oznacza pola tekstowe jako tłumaczalne, a obrazy zapisane w polach trafiają do zadań tłumaczeniowych WPML wraz z tekstami alternatywnymi i podpisami.

Plus

## Oficjalny zestaw rozszerzeń

Wysokiej jakości szablony witryn, systemowe instrukcje AI i prywatna społeczność Discord. Jednorazowy zakup, dożywotnie aktualizacje.

- 500+ szablonów stron
- Instrukcje systemowe AI
- Dożywotnie aktualizacje
- Prywatna społeczność Discord

[Uzyskaj Plus](https://blockstudio.dev/pl/plus/)
