
Blockstudio 7.1 on ensimmäinen ominaisuusjulkaisu v7-uudelleenkirjoituksen jälkeen. Siinä missä v7 rakensi perustan, 7.1 lisää osat, jotka tekevät lohkoista enemmän: tietokantakerroksen, palvelinfunktiot, ajastetut tehtävät ja CLI. Lohkokansio voi nyt olla kokonainen sovellus.

Tässä kaikki uudet ominaisuudet.

## Komponentit

Lohkoissa, joita editorit käyttävät lisäysvalikossa, ja lohkoissa, joita kehittäjät käyttävät rakennuspalikoina muille asioille, on aina ollut jännite. Kortti, tunniste, tilastowidget, lomakekenttä. Ne tarvitsevat koko Blockstudio-putken (attribuutit, mallit, resurssit, Tailwind), mutta niiden ei kuulu näkyä lisäysvalikossa.

Versiossa 7.1 tämä ratkaistaan komponenteilla. Määritä `"component": true` tiedostossa block.json, niin lohko käy läpi koko koontiputken, mutta sitä ei rekisteröidä WordPressn lohkotyyppirekisteriin. Se ei näy lisäysvalikossa eikä editorille JavaScriptlle lähetettävissä tiedoissa, mutta se on täysin käytettävissä ohjelmalliseen renderöintiin.

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

Renderöi ne funktiosta PHP:

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

Tai käyttämällä uutta HTML-tagisyntaksia:

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

## Lohkotagit

Lohkoja voi nyt upottaa HTML-tageina kahdella keskenään vaihdettavalla syntaksilla:

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

Molemmat tuottavat saman tuloksen. Molemmat toimivat Blockstudio-lohkojen ja ydinosan WordPress-lohkojen kanssa. Lohkomallien sisällä ne renderöityvät automaattisesti ilman erillistä käyttöönottoa. Näin voit koostaa kokonaisia asetteluja muista lohkoista suoraan mallissasi:

```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>
```

Syntaksit voivat sisäkkäistyä vapaasti. Blockstudio-lohkot renderöidään koko putken läpi (mallit, Tailwind, resurssit). Ydinosan lohkot renderöidään WordPressn kautta samoilla renderöijillä, joita [Sivut ja kuviot](https://blockstudio.dev/fi/docs/pages-and-patterns/) käyttävät.

Ota sivutason renderöintiä (julkaisun sisältö, widget-alueet) varten ominaisuus käyttöön tiedostossa `blockstudio.json`:

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

Salli- ja estolistat määrittävät jokerimerkkikuvioiden avulla, mitkä lohkot voidaan renderöidä tageilla. `data-*`- ja `html-*`-attribuutit siirtyvät renderöidyn lohkon juurielementin HTML-elementtiin. Mukautetut renderöijät voi rekisteröidä suodattimella `blockstudio/block_tags/renderers`.

Taustalla tagien jäsennin on uusi kevyt merkkijonoskanneri, joka korvaa DOMDocumentin kokonaan. Se käsittelee sisäkkäiset tagit syvyysseurannalla, rekursiiviset säilölohkot ja eri syntaksien yhdistelmät yhdellä läpikäynnillä. Vertailutesteissä se jäsentää 1,000 tasaista tagia 2,4 ms:ssa ja 100 sisäkkäisyystasoa 3,7 ms:ssa, eli johdonmukaisesti nopeammin kuin DOMDocument ja WordPressn `WP_HTML_Tag_Processor`. Sama jäsennin käsittelee myös raakojen HTML-elementtien jäsentämisen [Sivuja ja kuvioita](https://blockstudio.dev/fi/docs/pages-and-patterns/) varten ja korvaa DOMDocumentiin perustuneen jäsentimen, joka käsitteli aiemmin `<p>`-, `<div>`- ja muita HTML-elementtejä.

## Uudet kenttätyypit

### Lohko

Uusi `block`-kenttätyyppi, jonka avulla voit viitata toiseen Blockstudio-lohkoon attribuuttina. Viitatun lohkon kentät laajenevat automaattisesti käyttäen `idStructure`a ja `overrides`a, aivan kuten mukautetut kentät. Erona on, että mallissa arvon hakeminen palauttaa renderöidyn lohkon tulosteen.

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

Jos `mytheme/card`ssa on kentät `heading` ja `content`, isäntälohko saa sivupalkkiinsa `card_heading`n ja `card_content`n. Mallissa `{{ a.card }}` tulostaa renderöidyn kortin. Toimii sekä tavallisten lohkojen että komponenttien kanssa.

### HTML-tagi

Jokaisessa teemassa on lohkoja, joiden otsikkotason pitäisi vaihtua kontekstin mukaan: etusivulla H1, alasivuilla H2. Sen sijaan, että rakentaisit tätä varten joka kerta valintakentän kovakoodatuilla vaihtoehdoilla, käytettävissä on nyt oma `html-tag`-kenttätyyppi, jossa on valmiit vaihtoehdot.

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

Valmiit vaihtoehdot: `heading` (h1–h6), `text` (otsikot sekä p, span ja div), `structural` (div, section, article, aside, main, header, footer, nav), `all`. Voit myös antaa oman taulukon. `exclude` poistaa valitut tagit mistä tahansa vaihtoehtoryhmästä.

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

## Tietokanta

Tämä on julkaisun keskeisin ominaisuus. Lisää `db.php`-tiedosto mihin tahansa lohkokansioon, niin Blockstudio luo viisi REST CRUD-päätepistettä, validoi jokaisen kirjoituksen skeemaa vasten, hallinnoi tallennuksen taustajärjestelmää automaattisesti ja tarjoaa sekä JavaScript-asiakasohjelman (`bs.db()`) että PHP APIn (`Db::get()`). Ei migraatiotiedostoja, ohjainluokkia tai reittien rekisteröintiä.

```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']],
        ],
    ],
];
```

Pelkkä skeema tuottaa täysin toimivan APIn, jossa on luonti-, listaus-, haku-, päivitys- ja poistopäätepisteet sekä syötteiden validointi.

### Tallennus

Viisi tallennuksen taustajärjestelmää eri käyttötarkoituksiin:

- **`table`**: Mukautettu MySQL-taulu, jota hallitaan `dbDelta()`-työkalulla. Kenttien lisääminen skeemaan lisää sarakkeet seuraavalla sivun latauskerralla. Tuotannon oletusasetus.
- **`sqlite`**: Yksi SQLite-tiedosto lohkon `db/`-kansiossa. Aidot SQL-kyselyt, WAL-tila samanaikaisille lukutoiminnoille ja täysin siirrettävä. Kopioi kansio, kopioi tietokanta.
- **`jsonc`**: Yksi JSON-objekti riviä kohden tavallisessa tiedostossa. Ihmisen luettavissa, versiohallintaan sopiva ja git-ystävällinen.
- **`meta`**: JSON-taulukko WordPress-artikkelin metatiedoissa, sidottuna tiettyyn artikkeliin.
- **`post_type`**: Jokaisesta tietueesta tulee WordPress-artikkeli mukautettuun artikkelityyppiin. Kentät tallennetaan yksittäisinä artikkelin metatietoina, joista voi tehdä hakuja kokonaan `WP_Query`-työkalulla.

### Asiakasohjelmat

JavaScript-puolella `bs.db()` tarjoaa kattavan CRUD-asiakasohjelman:

```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);
```

Sen mukana toimitetaan kolme kumppanityökalua:

- **`bs.cache`**: Muistissa toimiva kyselyvälimuisti, jossa on `get`, `set`, `invalidate` ja `clear`. Jaettu kaikkien kysely- ja mutaatiokutsujen kesken.
- **`bs.query(key, fn, options)`**: Lisää asynkroniseen funktioon välimuistin, pyyntöjen yhdistelyn ja määritettävän `staleTime`n. Saman avaimen useat kutsut keskeneräisen pyynnön aikana palauttavat saman promisen.
- **`bs.mutate(options)`**: Käsittelee optimistiset mutaatiot ja palauttaa tilan automaattisesti ennalleen. Anna sille reaktiivinen tilaolio, toiminto (`create`, `update`, `delete`) ja optimistiset tiedot. UI päivittyy heti. Jos palvelinkutsu epäonnistuu, tila palautuu mutaatiota edeltävään tilannevedokseen.

Yhdessä nämä kattavat koko luku- ja kirjoitussyklin: `bs.query` välimuistissa oleville lukemisille, `bs.mutate` optimistisille kirjoituksille ja `bs.cache` manuaaliseen hallintaan.

PHP-puolella `Db`-luokka tarjoaa samat toiminnot:

```php
use Blockstudio\Db;

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

### Validointi

Validointivirheet palautetaan kenttäkohtaisina virhetaulukoina, joiden esikuvana on Zodn `fieldErrors`-muoto. Samalle kentälle voi tulla useita sääntövirheitä, ja rakenteen ansiosta virheet on helppo yhdistää käyttöliittymän lomakekenttiin:

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

Mukautetut `validate`-takaisinkutsut suoritetaan palvelimella, ja niillä voi tarkistaa kaiken, mitä sisäänrakennetut säännöt eivät kata: verkkotunnusten eston, kenttien välisen validoinnin ja ulkoiset haut.

### Käyttäjäkohtaiset tiedot

Käyttäjäkohtaisille tiedoille, kuten tehtävälistoille, suosikeille tai luonnoksille, määritä `userScoped` arvoksi `true`, niin Blockstudio hoitaa loput. Se lisää `user_id`-sarakkeen, asettaa sen automaattisesti luonnin yhteydessä ja rajaa jokaisen kyselyn nykyiseen käyttäjään. Päivitykset ja poistot tarkistavat omistajuuden. Ei manuaalista `user_id`-kenttää, `before_create`-koukkua tai suodatusta kohdassa RPC. Yksi asetus. Kun käytössä on `post_type`-tallennus, `userScoped` yhdistyy `post_author`n kanssa erillisen sarakkeen sijaan.

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

### Reaaliaikainen kysely

Aseta skeemaan `'realtime' => true`, niin asiakasohjelma tarkistaa muutokset automaattisesti. Kun palvelimella tapahtuu muutos, Interactivityn API-tila päivittyy ja UI renderöityy uudelleen ilman JavaScript-muutoksia sinun puolellasi. Määritä mukautetut tilan avaimet ja aikavälit asetuksella `'realtime' => ['key' => 'todos', 'interval' => 5000]`. Kysely keventää pyyntöjä hash-vertailulla ja pysähtyy, kun selaimen välilehti on piilotettuna.

### Tietoturva, koukut ja siirrettävyys

Julkiset päätepisteet suojataan automaattisesti lisättävällä `X-BS-Token` CSRF-otsakkeella. Käytä asetusta `'open'`, kun tarvitset täysin tunnistautumatonta käyttöä, esimerkiksi saapuville webhookeille.

Elinkaarikoukut suoritetaan ennen jokaista kirjoitustoimintoa ja sen jälkeen. Määritä ne suoraan kohdassa `db.php` tai yleisesti WordPress-toimintojen kautta.

Kentät voivat määrittää `component`-avaimen skeemavetoista lomakkeiden renderöintiä varten `bs_db_form()`n avulla.

Kun käytössä on SQLite- tai JSONC-tallennus, koko sovellus sijaitsee yhdessä kansiossa: koodi, logiikka, käyttöoikeuksien hallinta ja tiedot. Ota se käyttöön kopioimalla kansio.

## RPC

Joskus CRUD ei riitä. Tarvitset mukautettua palvelinlogiikkaa: tehtävän tilan vaihtamista, ilmoituksen lähettämistä tai tilastojen koostamista. Tätä varten ovat `rpc.php`. Määritä PHP-funktio, kutsu sitä käyttöliittymästä `bs.fn()`lla, niin Blockstudio hoitaa REST-päätepisteen, tunnistautumisen, CSRF-suojauksen ja JSON-sarjallistamisen. Malli on saanut inspiraationsa [tRPC](https://trpc.io)sta: proseduurit määritetään palvelimella ja niitä kutsutaan asiakasohjelmasta nimellä.

```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' });
```

Skripteihin sijoitetut skriptit (`script-inline.js`) tunnistavat lohkon nimen automaattisesti skriptitagin `data-block`-attribuutista, joten sitä ei tarvitse välittää erikseen. Moduuliskriptit välittävät sen kolmantena argumenttina.

Käyttöoikeusvaihtoehtoihin kuuluvat `public` (CSRF-suojauksella), `'open'` (ei suojausta), käyttöoikeusmerkkijonot tai taulukot. Myös funktiokohtainen HTTP-metodin hallinta, elinkaarikoukut ja lohkojen välinen kutsuminen sekä JSsta että PHPsta ovat tuettuja.

## Cron

Taustatehtävät määritetään `cron.php`-tiedostossa. Aseta aikataulu ja takaisinkutsu, niin Blockstudio rekisteröi ne WordPressn Cronn kanssa alustuksen yhteydessä. Kun lisäosa poistetaan käytöstä, kaikki ajastukset perutaan siististi.

```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
        },
    ],
];
```

Kaikki sisäänrakennetut WordPress-aikataulut ovat tuettuja. Voit myös lisätä mukautettuja aikavälejä suodattimella `cron_schedules`.

## CLI

Uusi `wp bs`-komento kattaa koko Blockstudio-ominaisuusjoukon: lohkot, tietokannan, RPCn, cronn, asetukset, Tailwind-käännöksen, SCSS-käännöksen, mukautetut kentät ja resurssien hallinnan.

```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
```

Kaikki komennot tukevat `--format=json`-asetusta komentosarjoja varten.

## Toistinparannukset

### textMinimized objektikentille

Luhistettujen toistinrivien objektikenttien arvot käsitellään nyt oikein. Aiemmin `textMinimized`n osoittaminen linkkikenttään näytti `[object Object]`n. Nyt Blockstudio lukee automaattisesti oikean alakentän tyypin perusteella: `title` linkeille, `value` väreille ja liukuväreille sekä `icon` kuvakkeille. Voit myös asettaa erillisen `key`-ominaisuuden minkä tahansa haluamasi alakentän lukemiseen.

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

### RichText ja MediaPlaceholder

Molemmat mallikomponentit toimivat nyt toistinkenttien sisällä hakasuljesyntaksilla, jolla kohdistetaan oikeaan riviin. Toistimen jokaisella rivillä voi muokata suoraan otsikoita ja kappaleita sekä ladata mediatiedostoja.

```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 %}
```

## Mukautettujen kenttien ehdot ja idStructure

Kun mukautetussa kentässä käytetään asetusta `idStructure`, kenttämäärittelyn sisäisten ehtojen tunnisteet kirjoitetaan nyt automaattisesti uudelleen vastaamaan laajennettuja nimiä. Jos font-size-kenttäryhmälläsi on ehto kentälle `enable` ja laajennat sen asetuksella `idStructure: "title_font_{id}"`, ehto viittaa nyt oikein tunnisteeseen `title_font_enable` alkuperäisen tunnisteen `enable` sijaan.

Myös viitetason ehdot ovat tuettuja. Lisää mukautettuun kenttäviitteeseen `conditions`, niin ehto koskee kaikkia laajennettuja kenttiä kerralla.

## Dynaamiset populate-argumentit

Populate-argumentit voivat nyt viitata muiden lohkojen attribuutteihin syntaksilla `{attributes.*}`. Kun viitattu attribuutti muuttuu, valintakenttä hakee vaihtoehtonsa automaattisesti uudelleen. Voit ketjuttaa valintakenttiä: ensin valitaan artikkelityyppi, sitten ladataan kyseisen tyypin artikkelit.

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

Vaihda `post_type` arvoksi "page", niin toinen valintakenttä lataa sivut. Vaihda arvoksi "post", niin se lataa artikkelit. Toimii minkä tahansa populate-tyypin ja attribuutin kanssa.

## Composer

Blockstudio toimii nyt, kun se ladataan mistä tahansa kohdan `wp-content/` alikansiosta, eikä vain lisäosahakemistosta. Resurssien URL-osoitteet ratkaistaan `BLOCKSTUDIO_URL`-vakion avulla `plugins_url()`n sijaan, joten teemaan paketoidut asennukset toimivat heti:

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

`composer.json`n ajonaikaiset riippuvuudet on siivottu. Rajatut paketit (TailwindPHP, ScssPhp, Minify), jotka sisältyvät jo pakettiin `lib/`, eivät enää ole ajonaikaisia riippuvuuksia. Jäljelle jäävät vain `php >= 8.2` ja `plugin-update-checker`.

Kaikki kolme asennustapaa (lisäosan zip-paketti, lisäosa Composern kautta ja teemaan paketoitu versio Composern kautta) käynnistyvät samalla tavalla: WordPress aktivoituu kokonaan, lohkot rekisteröidään ja ne renderöidään käyttöliittymässä.

Katso määritysohjeet [Composer-dokumentaatiosta](https://blockstudio.dev/fi/docs/dev/composer/).

## Suorituskykyprofileri

Lisää `?blockstudio-perf` mille tahansa sivun URLlle, niin alareunaan ilmestyy virheenkorjauspaneeli. Se näyttää lohkojen renderöintiajat, vaihekohtaisen erittelyn ja välimuistin osumat. Ajoitustiedot lähetetään myös Server-Timing-otsakkeina, jotka näkyvät selaimen DevToolsin Network-välilehdellä.

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

Ota se asetuksista pysyvästi käyttöön, niin jokainen sivulataus profiloidaan. Se näkyy vain kirjautuneille käyttäjille, joilla on käyttöoikeus `edit_posts`.

Myös itsesulkeutuvat lohkotagit tallennetaan nyt muistiin. Kun sama lohko samoilla attribuuteilla esiintyy sivulla useita kertoja, myöhemmät renderöinnit ohittavat koko malliputken.

## Virheenkorjaukset

- **PHP 8.4:n vanhentumisvaroitukset**: Korjattu `strpos()`n ja `str_replace()`n vanhentumisvaroitukset, jotka johtuivat siitä, että `null` välitettiin kohteelle `add_submenu_page()`.

## Muuta

- **SCSS-koodikentät**: Koodikentät tukevat `language: "scss"`a. Arvot käännetään ScssPhplla sekä editorissa että käyttöliittymässä.
- **Vakiomuotoiset WordPress-lohkot**: Blockstudio-hakemistot voivat sisältää `@wordpress/create-block`-tulostetta Blockstudio-lohkojen rinnalla. Ne rekisteröidään automaattisesti ilman erillistä lisäosakoodia.

---

Jos haluat nähdä täysimittaisen sovellusmallin käytännössä, [Täysimittaisten lohkojen opas](https://blockstudio.dev/fi/guides/full-stack-blocks/) näyttää vaihe vaiheelta, miten rakennetaan alusta asti käyttäjäkohtainen todo-sovellus ja julkinen uutiskirjeen tilauslomake.
