
Blockstudio 7.4 eesmärk on muuta failipõhised projektid hõlpsamini teisaldatavaks. Kui 7.2 tegi suuremate projektide uurimise ja levitamise lihtsamaks ning 7.3 lisas selle peale UI kihi, siis 7.4 keskendub sellele, et viia suurem osa projektist, selle lehtedest ja kureeritud sisust andmebaasist versioonihalduse all olevatesse failidesse.

Peamine uus funktsioon on lehekogud: viis, kuidas suunata Blockstudio leheallikate kaustale ja luua sellest täielik pesastatud WordPress lehestruktuur. Allikas võib olla PHP, Twig, Blade, HTML, Markdown või usaldatud laadija, mis tagastab lehti teisest kohalikust allikast.

Lühidalt:

- **Lehekogud**: `pages.json` saab määratleda täieliku pesastatud lehekogumi, vaikeväärtused, postitustüübi käitumise, paigutused, laadijad ja kogu metaandmed.
- **Markdown lehed**: `index.md` sobib lehe sisuks, kas koos `page.json`-ga või eraldi, koos päiseandmetega.
- **Esikülje lehepaigutused**: `layout.php` saab mähkida sünkroonitud lehe sisu ja kasutada abifunktsioone, näiteks `blockstudio_page_tree()` ja `blockstudio_page_content()`.
- **Välised dokumentatsiooniallikad**: kogu laadijad saavad luua lehti kohalikest failidest või tagastatud Markdown/HTML-ist.
- **Markdown toorväljund**: Markdown leheallikaid saab väljastada kujul `.md` või `Accept: text/markdown` kaudu.
- **Kogu kohandatud postitustüübid**: kogudel võivad olla puhtad URL-id, automaatne ümbersuunamisreeglite värskendamine, toored Markdown marsruudid ja lehtede üleviimine kohandatud postitustüübile ilma teemapoolsete kohandusteta.
- **Content Sync**: `wp bs content pull`, `wp bs content push` ja `wp bs content status` võimaldavad projektis lubatud postitused, terminid, seosed ja deklareeritud metaandmeviited teisaldatavatesse failidesse salvestada.
- **Plokisiltide prefiksid**: projektiprefiksid, näiteks `<theme-card>`, saavad lahenduda järjestatud nimeruumides ilma plokipõhiste aliasteta.
- **Usaldusväärsem sünkroonimine**: muudatusi tuvastatakse manifestides, laadijates, paigutustes, metaandmetes ja lähtefailides.
- **Käitusaeg ja redaktori parandused**: dünaamilised valikud püsivad ajakohased, päringuplokkide klassid säilivad programmilisel renderdamisel, `bsui/select` töötab tiheda paigutusega vormides paremini, RichTexti atribuudid jõuavad redaktorisse ning kordaja rea kustutamine koos RichTextiga säilib pärast salvestamist.

## Failipõhised lehed

Suurem osa versioonist 7.4 põhineb failipõhistel lehtedel.

### Lehekogud

Enne versiooni 7.4 olid failipõhised lehed peamiselt kaustataseme funktsioon: loo `page.json`, lisa `index.php` või `index.twig` ja Blockstudio sünkroonib selle üksiku lehe WordPress-i.

See toimib endiselt. Versioon 7.4 lisab suuremate struktuuride jaoks teise režiimi.

Lisa kausta `pages.json` manifest ja sellest saab kogu:

```txt
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
```

```json title="pages/docs/pages.json"
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "postTypeArgs": {
    "label": "Docs",
    "rewrite": {
      "slug": "docs"
    },
    "supports": ["title", "editor", "page-attributes"]
  },
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}
```

Iga lehekogu leheallikas leitakse, normaliseeritakse, sünkroonitakse ja seotakse tee järgi. Leht asukohas `guide/install` muutub asukoha `guide` alamleheks; kui leht `guide` puudub, loob Blockstudio genereeritud konteinerlehe, et WordPress hierarhia vastaks endiselt failisüsteemi struktuurile.

Kogud saavad kasutada sisseehitatud `page` postitustüüpi või enda postitustüüpi. Kui kogu deklareerib postitustüübi, mida veel pole, registreerib Blockstudio selle `postTypeArgs`-ist. Manifesti `postType` muutub ka kõigi selle kogu lehtede vaikeväärtuseks, nii et projektides ei pea seda `defaults`-is kordama.

Kogu postitustüübid kasutavad avaliku URL baasina kogu tunnust. `docs` kogu juurleht asub aadressil `/docs/`, leht, millel on `path: "getting-started"`, asub aadressil `/docs/getting-started/` ning pesastatud teed jäävad sama baasi alla. Topelt-URL-id, näiteks `/docs/docs/`, suunatakse kanoonilisse asukohta. Suunamisreegleid värskendatakse automaatselt, kui kogu postitustüübi marsruutimine muutub, seega ei pea uue kogu lisamisel püsiviitelinke käsitsi salvestama.

See võimaldab välistel dokumentatsioonidel, tootejuhenditel, teadmistebaasidel ja lehekogudel WordPress-is loomulikult toimida: allikas jääb failidesse, kuid tulemus on endiselt päris redigeeritav WordPress sisu.

### Markdown lehe sisuna

Markdown on nüüd täisväärtuslik leheallikas.

Eraldiseisvad Markdown lehed kasutavad päiseandmeid:

```md title="pages/about/index.md"
---
name: about
title: About
slug: about
postStatus: publish
---

# About

This Markdown content is synced as native WordPress blocks.
```

Kui soovite seadistuse ja sisu eri failides hoida, võite ühendada ka `page.json` ja `index.md`. Faili `index.md` päiseandmed võivad vastavad väljad `page.json`-is üle kirjutada ning tundmatud päiseandmete võtmed säilitatakse metaandmetena.

Markdown teisendatakse kujule HTML ja edastatakse seejärel samale leheparserile nagu PHP, Twig ja Blade mallid, nii et lõplik sisu on plokkide algupärases märgenduses.

### Paigutused ja lehe abifunktsioonid

Kogud võivad sisaldada faili `layout.php`. Esiküljel ümbritseb Blockstudio sünkroonitud lehe sisu selle paigutusega.

```php title="pages/docs/layout.php"
<main class="docs-layout">
  <aside>
    <?php foreach (blockstudio_page_tree('docs') as $item) : ?>
      <a href="<?php echo esc_url($item['permalink'] ?? '#'); ?>">
        <?php echo esc_html($item['title']); ?>
      </a>
    <?php endforeach; ?>
  </aside>

  <article>
    <?php echo blockstudio_page_content(); ?>
  </article>
</main>
```

Uued abifunktsioonid esitavad kogu struktureeritud andmetena:

```php
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
```

Nii saate kokku panna täieliku dokumentatsiooniraamistiku jaoks vajalikud osad: lehepuust saadav navigeerimine, päiseandmetest tulevad lehe metaandmed ja põhisisuna sünkroonitud WordPress plokisisu.

### Laadijad ja töötlemata Markdown

Kogud võivad sisaldada usaldatud kohalikku `loader.php` faili. See võib tagastada lehti otse või määrata Blockstudio-ile lisakohalikud kataloogid, kust lehti leida.

```php title="pages/docs/loader.php"
<?php

return [
  'pages' => [
    [
      'name' => 'docs-api',
      'title' => 'API',
      'path' => 'api',
      'content' => "# API\n\nGenerated markdown content.",
      'contentType' => 'markdown',
    ],
  ],
];
```

See on kasulik siis, kui allikas on juba mujal loodud: paketi dokumentatsioonikaust, Markdown eksport või ehitusetapp, mis tagastab lehtede loendi.

Markdown leheallikad saavad väljastada ka toore Markdown-allika. Pärige lehte lõpuga `.md` või saatke `Accept: text/markdown`. Päiseandmed eemaldatakse vastusest, et tööriistad saaksid loetava dokumendi sisu. See toimib ka kogu postitustüüpide puhul, sealhulgas URL-idel nagu `/docs.md` ja `/docs/getting-started.md`.

[Lugege lehtede dokumentatsiooni](https://blockstudio.dev/et/docs/pages-and-patterns/pages/)

## Content Sync

Versioon 7.4 toob ka Content Synci: WP-CLI töövoo meeskondadele, kes soovivad, et suurem osa nende WordPress projektist oleks failidena esitatud.

```bash
wp bs content pull
wp bs content push --dry-run
wp bs content status
```

Blockstudio hoiab projektis plokke, välju, malle, mustreid ja failipõhiseid lehti. Content Sync lisab sellele failipõhisele töövoole valitud andmebaasisisu: lubatud postitused, terminid, seosed ja deklareeritud metaandmed saab failidesse tuua, need saab git üle vaadata ja teise keskkonda edastada.

See on teadlikult selgesõnaline. Lubage see jaotises `blockstudio.json`, lisage lubatud loendisse postitustüübid ja taksonoomiad, mida soovite hallata, ning deklareerige metaandmeviited, mida tuleb keskkondade vahel ümber kirjutada.

Andmete tõmbamisel kirjutab Blockstudio kaasaskantavad postitused, terminid, seosed ja lubatud metaandmed teie teema failidesse. Edastamisel valideerib see plaani enne kirjutamist ning lahendab deklareeritud viited `post`, `term` ja `attachment` kohalike andmebaasi ID-deni. Suvaliste täisarvude puhul ei eeldata, et need on ID-d.

Versiooni 7.4 ulatus on kavandatult piiratud: postitused, terminid, terminite seosed, lubatud metaandmed, teisaldatavad UID-d, manuste manifestid, proovikäivitused, eemaldamise käsitlemine, lukustatud üksused ja olekuaruandlus. Taksonoomiamääratluste salvestamine, meediumifailide binaarandmete kopeerimine ja plokimärgistuse ID-de ümberkirjutamine jäävad sellest esimesest versioonist teadlikult välja.

Nii saavad meeskonnad versioonihalduses hoida kureeritud sisu, nagu meeskonnaliikmed, juhtumiuuringud, asukohad, dokumentatsiooni sissekanded või muud struktureeritud kirjed, muutmata kogu tootmisandmebaasi migratsiooniks. See on mõeldud sisukogumitele, mida saab failidena üle vaadata: kümned või sajad read ning mõnes projektis ka mõned tuhanded, kui sisu on struktureeritud ja harva muutuv. See ei asenda andmebaasi varukoopiaid, e-kaubanduse ega tellimuste sünkroonimist, analüütikat, logisid, vormide esitamisi ega muid suure andmemahuga andmeid.

[Lugege Content Synci dokumentatsiooni](https://blockstudio.dev/et/docs/content-sync/)

### Usaldusväärsem sünkroonimine

Blockstudio tuvastab nüüd muudatusi leheallikates, kogude manifestides, laadijafailides, paigutusfailides, metaandmetes ja seotud asukohtades. Kui mõni neist muutub, värskendatakse sünkroonitud WordPress lehte.

Lehe töötlemisahel käsitleb ka üksikasju, mis muudavad failipõhise dokumentatsiooni pärisprojektides praktiliseks:

- Markdown leheallikad sünkroonitakse plokkide algupärase sisuna, sealhulgas plokiattribuudid
- päiseandmete metaandmed on esikülje abifunktsioonidele ja paigutustele kättesaadavad
- kogulehed säilitavad sünkroonimiste vahel stabiilse identiteedi
- pesastatud koguvälised lehed lingitakse oma ülemlehega
- pesastatud koguvälised lehed saavad pärida lähima esivanema `layout.php`
- eemaldatud koguallikad kustutavad nende loodud WordPress lehed
- kui kogu muudetakse tüübist `page` kohandatud postitustüübiks, viiakse olemasolevad sünkroonitud postitused üle duplikaatide loomise asemel
- lehtede järjestus püsib `menu_order` kaudu

## Plokisiltide prefiksid

Plokisildid toetavad nüüd seadistatavaid nimeruumi prefikseid. Projekt saab registreerida ühe lühikese prefiksi ja lasta Blockstudio-il ploki ühes või mitmes nimeruumis lahendada:

```php
add_filter('blockstudio/block_tags/prefixes', function ($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
```

Kui see on seadistatud, saab `<theme-card>` lahendada väärtuseks `theme-components/card`, `<theme-button>` saab varuvariandina lahendada väärtuseks `bsui/button` ning `<theme-ui-feature-matrix>` saab lahendada väärtuseks `theme-components/ui-feature-matrix`.

Selgesõnalised `tag_aliases`-id jäävad kehtima, kui projekt vajab ühekordset ülekirjutust. Tundmatud prefiksiga sildid jäetakse muutmata ning olemasolevad plokisiltide lubamis- ja keelamisfiltrid kehtivad endiselt prefiksi abil lahendatud plokkidele.

[Lugege plokisiltide dokumentatsiooni](https://blockstudio.dev/et/docs/blocks/rendering/#prefix-shorthands)

## Käitusaja ja redaktori parandused

Versioon 7.4 sisaldab ka parandusi, mis tulid välja pärisprojektide kasutamisel.

- Dünaamiliselt päringuga täidetud valikud püsivad ajakohased, kui postitused, terminid, kasutajad või seotud metaandmed muutuvad, ning `populate.fetch: true` päringuvalikud toovad redaktori tühjade otsingute puhul kaasaegsed valikud.
- Programmilised `core/query` ja `core/comments` plokisildid säilitavad loodud ümbrismärgistuses `className`.
- Mallide pseudokomponendid säilitavad camelCase'i atribuudid, nii et näiteks `allowedFormats` ja `withoutInteractiveFormatting` jõuavad redaktori komponendini, selle asemel et enne eemalduda.
- `bsui/select` käsitleb valikuandmeid ja üle ääre ulatuvaid menüüsid usaldusväärsemalt, eriti tihedalt paigutatud redaktorijuhikute sees.
- `blockstudio/phpstan` tunneb ära väljäd, mis on deklareeritud konteinerites `tabs`, nii et mallide, Twig/Blade ja plokisiltide valideerimine mõistab sama väljakuju, mida Blockstudio projektides kasutab.
- Kordaja rea kustutamine koos RichTextiga säilib pärast salvestamist. Aegunud RichTexti väärtused ei saa enam kustutatud rida taastada.

## Miks see väljalase on oluline

Versiooni 7.4 teema on teisaldatavus.

Lehekogud muudavad terved dokumentatsioonisaidid lähtefailide kaustadeks. Markdown lehti on lihtne kirjutada ja nende sisu on lihtne tagasi lugeda. Content Sync laiendab sama failipõhise mudeli kureeritud andmebaasisisule, nii et postitused, terminid ja seosed saavad asuda git ning liikuda keskkondade vahel. Plokisiltide prefiksid hoiavad suured plokiteegid mallides loetavana.

Blockstudio on endiselt failipõhine. Plokid on endiselt kaustad. Lehed on endiselt failid. Versioon 7.4 võimaldab lihtsalt suuremal osal projektist, selle lehestruktuuridest ja kureeritud sisust failides paikneda ning koos nendega liikuda.
