
Blockstudio 7.1 on esimene funktsiooniväljalase pärast v7 ümberkirjutamist. Kui v7 ehitas vundamendi uuesti üles, lisab 7.1 osad, mis muudavad plokid millekski enamaks: andmebaasikihi, serverifunktsioonid, ajastatud ülesanded ja CLI. Plokikaust võib nüüd olla terviklik rakendus.

Siin on kõik, mis on uut.

## Komponendid

Alati on olnud pinge sisestajas kasutatavate plokkide ja nende plokkide vahel, mida arendajad kasutavad teiste asjade ehituskividena. Kaart, märk, statistika vidin, vormiväli. Need vajavad täielikku Blockstudio töövoogu (atribuudid, mallid, varad, Tailwind), kuid neil pole põhjust sisestajas nähtaval olla.

7.1 toob selle lahendamiseks sisse komponendid. Määra oma block.json-is `"component": true` ja plokk läbib kogu ehitustöövoo, kuid seda ei registreerita WordPress plokitüüpide registris. See ei ilmu sisestajas ega toimetajaandmetes, mida JavaScript-ile saadetakse, kuid on programmiliseks renderdamiseks täielikult saadaval.

```json title="block.json"
{
  "name": "my-theme/card",
  "title": "Card",
  "blockstudio": {
    "component": true,
    "attributes": [
      { "id": "title", "type": "text" },
      { "id": "description", "type": "textarea" }
    ]
  }
}
```

Renderda neid PHP-ist:

```php
bs_render_block([
  'name' => 'my-theme/card',
  'data' => ['title' => 'My Card', 'description' => 'Card content.'],
]);
```

Või kasutades uut HTML märgendi süntaksit:

```html
<bs:my-theme-card title="My Card" description="Card content." />
```

## Plokimärgendid

Plokke saab nüüd manustada HTML märgenditena, kasutades kahte vaheldumisi kasutatavat süntaksit:

```html
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
```

Mõlemad annavad sama väljundi. Mõlemad töötavad Blockstudio plokkide ja tuuma WordPress plokkidega. Plokimallides renderdatakse need automaatselt, ilma et peaksid selleks midagi eraldi lubama. See tähendab, et saad koostada terveid paigutusi otse oma mallis teistest plokkidest:

```twig title="index.twig"
<div class="my-page">
  <bs:mytheme-card title="Featured" />
  <block name="core/separator" />
  <bs:core-heading level="2">Section Title</bs:core-heading>
  <block name="core/group">
    <block name="core/paragraph">Inside a core group block.</block>
    <bs:mytheme-cta variant="primary" />
  </block>
</div>
```

Need kaks süntaksit võivad vabalt üksteise sees olla. Blockstudio plokid renderdatakse kogu töövoo kaudu (mallid, Tailwind, varad). Tuuma plokid renderdatakse WordPress kaudu, kasutades samu renderdajaid nagu [Lehed ja mustrid](https://blockstudio.dev/et/docs/pages-and-patterns/).

Lehe tasemel renderdamise (postituse sisu, vidinate alad) lubamiseks tee see sisse `blockstudio.json`:

```json
{ "blockTags": { "enabled": true } }
```

Lubatud ja keelatud loendid määravad metamustrite abil, milliseid plokke saab märgendite kaudu renderdada. `data-*` ja `html-*` atribuudid edastatakse renderdatud ploki juur-HTML-elemendile. Kohandatud renderdajaid saab registreerida `blockstudio/block_tags/renderers` filtri kaudu.

Kapoti all asendab DOMDocumenti uus kerge stringiskanner, mis parsib märgendeid. See tuvastab pesastatud märgendid sügavuse jälgimise abil, rekursiivsed konteinerplokid ja segasüntaksi ühe läbimisega. Võrdlustestides parsib see 1,000 tasast märgendit 2.4ms ja 100 pesastustaset 3.7ms-ga, olles pidevalt kiirem nii DOMDocumentist kui ka WordPress `WP_HTML_Tag_Processor`-ist. Sama parser käsitleb ka [Lehtede ja mustrite](https://blockstudio.dev/et/docs/pages-and-patterns/) toor-HTML-elementide parsimist, asendades DOMDocumentil põhineva parseri, mis varem käsitles `<p>`, `<div>` ja muid HTML elemente.

## Uued väljatüübid

### Plokk

Uus `block` väljatüüp, mis võimaldab viidata teisele Blockstudio plokile atribuudina. Viidatud ploki väljad laienevad tekstisiseselt, kasutades `idStructure` ja `overrides`, täpselt nagu kohandatud väljad. Erinevus seisneb selles, et mallis tagastab väärtusele juurdepääs renderdatud ploki väljundi.

```json title="block.json"
{
  "blockstudio": {
    "attributes": [
      {
        "id": "card",
        "type": "block",
        "block": "mytheme/card",
        "idStructure": "card_{id}"
      }
    ]
  }
}
```

Kui `mytheme/card`-il on väljad `heading` ja `content`, saab hostplokk külgpaneelile väljad `card_heading` ja `card_content`. Mallis väljastab `{{ a.card }}` renderdatud kaardi. Töötab nii tavaliste plokkide kui ka komponentidega.

### HTML-märgend

Igas teemas on plokke, mille pealkirja tasand peaks kontekstist sõltuvalt muutuma. Avalehel H1, sisulehtedel H2. Selle asemel et luua iga kord kõvakodeeritud valikutega valikväli, on nüüd olemas spetsiaalne `html-tag` väljatüüp koos sisseehitatud eelseadistustega.

```json
{
  "id": "tag",
  "type": "html-tag",
  "default": "h2",
  "tags": "heading",
  "exclude": ["h5", "h6"]
}
```

Eelseadistused: `heading` (h1-h6), `text` (pealkirjad + p, span, div), `structural` (div, section, article, aside, main, header, footer, nav), `all`. Või anna ette kohandatud massiiv. `exclude` eemaldab mis tahes eelseadistusest kindlad märgendid.

```twig
<{{ a.tag }}>{{ a.title }}</{{ a.tag }}>
```

## Andmebaas

See on väljalaske keskne osa. Lisa mis tahes plokikausta `db.php`-fail ja Blockstudio loob viis REST CRUD-lõpp-punkti, valideerib iga kirjutuse skeemi alusel, haldab salvestuskihti automaatselt ning pakub nii JavaScript klienti (`bs.db()`) kui ka PHP API-i (`Db::get()`). Migratsioonifaile, kontrolleriklasse ega marsruutide registreerimist pole vaja.

```php title="db.php"
return [
    'subscribers' => [
        'storage'    => 'table',
        'capability' => [
            'create' => true,
            'read'   => true,
            'update' => 'edit_posts',
            'delete' => 'manage_options',
        ],
        'fields' => [
            'email' => [
                'type'     => 'string',
                'format'   => 'email',
                'required' => true,
                'validate' => function ($value) {
                    if (str_ends_with($value, '@spam.com')) {
                        return 'This domain is blocked.';
                    }
                    return true;
                },
            ],
            'name' => ['type' => 'string', 'maxLength' => 100],
            'plan' => ['type' => 'string', 'enum' => ['free', 'pro']],
        ],
    ],
];
```

Ainuüksi see skeem loob täielikult toimiva API-i, millel on loomise, loendi, hankimise, uuendamise ja kustutamise lõpp-punktid ning kõigil on sisendi valideerimine.

### Salvestus

Viis salvestuslahendust, millest igaüks sobib eri kasutusjuhtudeks:

- **`table`**: Kohandatud MySQL tabel, mida haldab `dbDelta()`. Skeemi väljade lisamisel lisatakse järgmise lehe laadimise ajal veerud. Vaikimisi valik tootmiskeskkonnas.
- **`sqlite`**: Üks SQLite-fail ploki kaustas `db/`. Päris SQL-päringud, WAL-režiim samaaegseks lugemiseks ja täielik kaasaskantavus. Kopeeri kaust, kopeeri andmebaas.
- **`jsonc`**: Üks JSON-objekt rea kohta lihttekstifailis. Inimloetav, versioonihalduses hoitav ja git-sõbralik.
- **`meta`**: JSON-massiiv WordPress post meta väljal, seotud kindla postitusega.
- **`post_type`**: Igast kirjest saab kohandatud postitüübiga WordPress postitus. Väljad salvestatakse eraldi post meta kirjetena, mida saab täielikult `WP_Query`-iga pärida.

### Kliendid

JavaScript poolel annab `bs.db()` sulle täieliku CRUD-kliendi:

```js
const db = bs.db('my-theme/block', 'subscribers');
const record = await db.create({ email: 'a@b.com', plan: 'pro' });
const pros = await db.list({ plan: 'pro' });
await db.update(record.id, { plan: 'free' });
await db.delete(record.id);
```

Sellega kaasnevad veel kolm abivahendit:

- **`bs.cache`**: Mälusisene päringute vahemälu, millel on `get`, `set`, `invalidate` ja `clear`. Jagatud kõigi päringu- ja muutmiskutsete vahel.
- **`bs.query(key, fn, options)`**: Ümbritseb mis tahes asünkroonset funktsiooni vahemälu, päringute deduplikeerimise ja seadistatava `staleTime`-iga. Mitu sama võtmega kutset poolelioleva päringu ajal tagastavad sama lubaduse.
- **`bs.mutate(options)`**: Haldab optimistlikke muudatusi automaatse tagasipööramisega. Anna ette reaktiivne olekuobjekt, toiming (`create`, `update`, `delete`) ja optimistlikud andmed. UI uueneb kohe. Kui serverikutse nurjub, taastatakse muutmiseelne olekuhetktõmmis.

Koos katavad need kogu lugemis- ja kirjutamistsükli: `bs.query` vahemällu salvestatud lugemisteks, `bs.mutate` optimistlikeks kirjutusteks, `bs.cache` käsitsi juhtimiseks.

PHP poolel pakub `Db` klass samu toiminguid:

```php
use Blockstudio\Db;

$db = Db::get('my-theme/block', 'subscribers');
$db->create(['email' => 'a@b.com', 'plan' => 'pro']);
$db->list(['plan' => 'pro']);
```

### Valideerimine

Valideerimisvead tagastatakse väljade kaupa veamassiividena, eeskujuks Zod `fieldErrors` vorming. Sama välja puhul võib ebaõnnestuda mitu reeglit ning struktuuri abil on lihtne siduda vead kasutajaliidese vormiväljadega:

```json
{
  "data": {
    "status": 400,
    "errors": {
      "email": ["Must be a valid email address.", "This domain is blocked."],
      "plan": ["Must be one of: free, pro."]
    }
  }
}
```

Kohandatud `validate` tagasikutsed töötavad serveris kõige jaoks, mida sisseehitatud reeglid ei kata: domeenide blokeerimine, väljadevaheline valideerimine ja välised päringud.

### Kasutajaga seotud andmed

Kasutajapõhiste andmete, näiteks ülesannete, lemmikute või mustandite jaoks määra `userScoped` väärtuseks `true` ja Blockstudio hoolitseb ülejäänu eest. See lisab veeru `user_id`, määrab selle loomisel automaatselt ning piirab iga päringu praeguse kasutajaga. Uuendamisel ja kustutamisel kontrollitakse omandiõigust. Käsitsi pole vaja välja `user_id`, konksu `before_create` ega filtreerimist RPC-is. Üks konfiguratsioonirida. Kui kasutad salvestuseks `post_type`-i, vastendatakse `userScoped` eraldi veeru asemel väärtusele `post_author`.

```php
return [
    'storage'    => 'sqlite',
    'userScoped' => true,
    'fields'     => [ /* ... */ ],
];
```

### Reaalajas küsitlemine

Määra skeemis `'realtime' => true` ja klient küsitleb muudatuste leidmiseks automaatselt. Kui serveris midagi muutub, uueneb Interactivity API-i olek ja UI renderdatakse uuesti, ilma et peaksid ise JavaScript muutma. Seadista `'realtime' => ['key' => 'todos', 'interval' => 5000]` abil kohandatud olekuvõtmed ja intervallid. Küsitlemisel kasutatakse päringute vähendamiseks räside võrdlust ning see peatub, kui brauseri vahekaart on peidetud.

### Turve, konksud ja kaasaskantavus

Avalikke lõpp-punkte kaitseb automaatselt lisatav `X-BS-Token` CSRF-päis. Kasuta `'open'`, kui vajad täiesti autentimata juurdepääsu, näiteks sissetulevate veebikonksude jaoks.

Elutsükli konksud käivituvad enne ja pärast iga kirjutustoimingut. Määra need otse `db.php`-is või globaalselt toimingute WordPress kaudu.

Väljadele saab määrata võtme `component`, et renderdada skeemi põhjal vorme `bs_db_form()` abil.

Salvestusega SQLite või JSONC asub kogu rakendus ühes kaustas: kood, loogika, juurdepääsukontroll ja andmed. Juurutamiseks kopeeri kaust.

## RPC

Mõnikord CRUD-ist ei piisa. Vaja on kohandatud serveriloogikat: ülesande oleku muutmist, teavituse saatmist, statistika koondamist. Selleks on `rpc.php`. Määra PHP funktsioon, kutsu seda kasutajaliidesest `bs.fn()` abil ning Blockstudio haldab REST lõpp-punkti, autentimist, CSRF-kaitset ja JSON serialiseerimist. Muster lähtub [tRPC](https://trpc.io)-ist: protseduurid määratletakse serveris ja neid kutsutakse kliendist nime järgi.

```php title="rpc.php"
return [
    'subscribe' => function (array $params): array {
        $email = sanitize_email($params['email']);
        return ['success' => true];
    },
];
```

```js
const result = await bs.fn('subscribe', { email: 'user@example.com' });
```

Tekstisisesed skriptid (`script-inline.js`) tuvastavad ploki nime automaatselt oma skriptimärgendi atribuudist `data-block`, seega ei pea sa seda käsitsi edastama. Moodulskriptid annavad selle kolmanda argumendina.

Juurdepääsukontrolli valikute hulka kuuluvad `public` (koos CSRF-kaitsega), `'open'` (kaitseta), võimekusstringid või massiivid. Toetatud on funktsioonipõhine HTTP meetodite juhtimine, elutsükli konksud ning plokkidevahelised kutsed nii JS-ist kui ka PHP-ist.

## Cron

Taustaülesanded määratletakse `cron.php`-failis. Määra ajakava ja tagasikutse ning Blockstudio registreerib need lähtestamisel WordPress Cron-iga. Plugina deaktiveerimisel tühistatakse kõik ajastused korrektselt.

```php title="cron.php"
return [
    'cleanup' => [
        'schedule' => 'daily',
        'callback' => function () {
            $db = Db::get('my-theme/app', 'logs');
            // delete old entries
        },
    ],
    'sync' => [
        'schedule' => 'hourly',
        'callback' => function () {
            // pull from external API
        },
    ],
];
```

Toetatud on kõik sisseehitatud WordPress ajakavad ning filtriga `cron_schedules` saab lisada kohandatud intervalle.

## CLI

Uus käsk `wp bs` katab kogu Blockstudio funktsioonide komplekti: plokid, andmebaas, RPC, cron, seaded, Tailwind kompileerimine, SCSS kompileerimine, kohandatud väljad ja varade haldus.

```bash
wp bs blocks list --components
wp bs db schemas
wp bs db create my-theme/app subs --email=a@b.com
wp bs db list my-theme/app subs --plan=pro --format=json
wp bs rpc call my-theme/app subscribe --email=a@b.com
wp bs cron run my-theme/app cleanup
wp bs tailwind compile --file=template.html
wp bs scss compile --file=style.scss
wp bs fields list
wp bs assets list --type=global
wp bs settings get tailwind/enabled
```

Kõik käsud toetavad skriptimise jaoks valikut `--format=json`.

## Kordaja täiustused

### Objekti väljade textMinimized

Nüüd käsitletakse kokkupandud kordaja ridu objektväljade väärtustega õigesti. Varem näitas `textMinimized`-i lingiväljale suunamine väärtust `[object Object]`. Nüüd loeb Blockstudio välja tüübi põhjal automaatselt õige alamatribuudi: linkide puhul `title`, värvide ja gradientide puhul `value` ning ikoonide puhul `icon`. Soovi korral saad määrata ka selgesõnalise atribuudi `key`, et lugeda mis tahes soovitud alamatribuuti.

```json
{
  "type": "repeater",
  "textMinimized": { "id": "href", "fallback": "Add a link" },
  "attributes": [{ "id": "href", "type": "link" }]
}
```

### RichText ja MediaPlaceholder

Mõlemad mallikomponendid töötavad nüüd kordajaväljades, kasutades nurksulgudega tähistust õige rea valimiseks. Iga kordaja rea pealkirju ja lõike saab tekstisiseselt muuta ning meedia üleslaadimisalasid kasutada.

```twig
{% for item in a.items %}
  <div class="card">
    <MediaPlaceholder attribute="items[{{ loop.index0 }}].image" />
    <RichText tag="h2" attribute="items[{{ loop.index0 }}].heading" />
    <RichText tag="p" attribute="items[{{ loop.index0 }}].content" />
  </div>
{% endfor %}
```

## Kohandatud väljade tingimused atribuudiga idStructure

Kui kasutad kohandatud välja koos atribuudiga `idStructure`, kirjutatakse väljadefinitsioonis olevate tingimuste ID-d nüüd automaatselt ümber, et need vastaksid laiendatud nimedele. Kui sinu fondisuuruse väljarühmal on tingimus `enable` alusel ja laiendad seda `idStructure: "title_font_{id}"` abil, viitab tingimus nüüd õigesti väljale `title_font_enable`, mitte algsele väljale `enable`.

Toetatud on ka viitetaseme tingimused. Lisa kohandatud välja viitele `conditions`, et rakendada neid korraga igale laiendatud väljale.

## Dünaamilised täitmisargumendid

Täitmisargumendid saavad nüüd viidata teistele ploki atribuutidele süntaksi `{attributes.*}` abil. Kui viidatud atribuut muutub, hangib valikväli oma valikud automaatselt uuesti. Seo valikväljad omavahel: üks postitüübi valimiseks, teine selle tüübi postituste laadimiseks.

```json
{
  "id": "selected_post",
  "type": "select",
  "populate": {
    "type": "query",
    "query": "posts",
    "arguments": {
      "post_type": "{attributes.post_type}"
    }
  }
}
```

Muuda `post_type` väärtuseks „page“ ja teine valikväli laadib lehed. Muuda see väärtuseks „post“ ja väli laadib postitused. Töötab mis tahes täitmistüübi ja atribuudiga.

## Composer

Blockstudio töötab nüüd, kui see laaditakse mistahes asukohast `wp-content/` all, mitte ainult pluginate kataloogist. Varade URL-id lahendatakse nüüd konstandi `BLOCKSTUDIO_URL`, mitte `plugins_url()` kaudu, nii et teemasse komplekteeritud paigaldused töötavad kohe:

```php title="functions.php"
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/vendor/blockstudio/blockstudio/blockstudio.php';
```

`composer.json` käitusaja sõltuvused on korrastatud. Ulatuspakette (TailwindPHP, ScssPhp, Minify), mis on juba `lib/`-i komplekteeritud, ei loetleta enam käitusaja sõltuvustena. Alles jäävad ainult `php >= 8.2` ja `plugin-update-checker`.

Kõik kolm paigaldusviisi (plugina ZIP, plugin Composer kaudu, teemasse komplekteerituna Composer kaudu) käivituvad samal viisil: täielik WordPress aktiveerimine, plokkide registreerimine ja renderdamine kasutajaliideses.

Vaadake seadistusjuhiseid [Composer dokumentatsioonist](https://blockstudio.dev/et/docs/dev/composer/).

## Jõudluse profileerija

Lisa suvalise lehe URL-i `?blockstudio-perf` ja alla ilmub silumispaneel, kus näidatakse plokkide renderdusaegu, etappide jaotust ja vahemälu tabamuste määra. Ajastusandmed saadetakse ka Server-Timing päistena, mis on nähtavad brauseri DevToolsi võrgupäringute vahekaardil.

```json title="blockstudio.json"
{ "dev": { "perf": true } }
```

Lülita see seadetes jäädavalt sisse, et profileerida iga lehe laadimist. Nähtav ainult sisseloginud kasutajatele, kellel on võimekus `edit_posts`.

Nüüd salvestatakse mällu ka isesulguvad plokimärgendid. Kui sama identsete atribuutidega plokk esineb lehel mitu korda, jäetakse järgmistel renderdustel kogu mallide töövoog vahele.

## Veaparandused

- **PHP 8.4 aegumise hoiatused**: Parandatud `strpos()` ja `str_replace()` aegumise hoiatused, mille põhjustas `null` edastamine `add_submenu_page()`-ile.

## Veel

- **SCSS koodiväljad**: Koodiväljad toetavad `language: "scss"`-i. Väärtused kompileeritakse ScssPhp kaudu nii redaktoris kui ka kasutajaliideses.
- **Standardsed WordPress plokid**: Blockstudio kataloogid võivad sisaldada `@wordpress/create-block` väljundit koos Blockstudio plokkidega. Need registreeritakse automaatselt, eraldi plugina koodi pole vaja.

---

Kui soovid näha täisvirna mustrit töös, tutvustab [Täisvirna plokkide juhend](https://blockstudio.dev/et/guides/full-stack-blocks/) nullist kasutajapõhise ülesanderakenduse ja avaliku uudiskirjaga liitumise vormi loomist.
