Ga naar de inhoud

Pagina’s op basis van bestanden bouwen

Traditionele WordPress-pagina’s worden gebouwd in de blokeditor: blokken slepen, instellingen configureren en op Opslaan klikken. Dat werkt voor klanten die hun eigen pagina’s bouwen, maar levert problemen op voor ontwikkelaars die gestructureerde pagina’s met versiebeheer maken. De pagina-indeling staat in de database, niet in code. Je kunt die niet beoordelen in een pull request, terugdraaien met git of reproduceren op een schone installatie.

De bestandspagina’s van Blockstudio lossen dit op. Je definieert pagina’s als bestanden in je thema, schrijft sjablonen in HTML die worden omgezet in blokken van WordPress en bepaalt precies wat klanten wel en niet kunnen bewerken. Met een expliciete opdracht synchroniseer je die bestanden naar normale berichten van WordPress; je sjablonen blijven daarbij de bron van waarheid.

Deze gids laat zien hoe je pagina’s vanaf nul opbouwt, met veel aandacht voor de vergrendelings- en bewerkingsopties die bestandspagina’s praktisch maken voor projecten met klanten.

Je eerste pagina

Maak een map pages in je thema en voeg vervolgens een submap met twee bestanden toe:

Code
theme/
└── pages/
    └── about/
        ├── page.json
        └── index.php
JSON
{
  "name": "about",
  "title": "About Us",
  "postStatus": "publish"
}
HTML
<h1>About Us</h1>
<p>We build things for the web.</p>

Voer de opdracht voor paginasynchronisatie uit:

Shell
wp bs pages sync

Blockstudio verwerkt de HTML tot blokken van WordPress en maakt een pagina met de naam “Over ons” en de slug about aan. Open die in de editor en je ziet een kop en een alinea, precies alsof je die handmatig hebt toegevoegd.

Bewerk index.php, wijzig de tekst en voer de opdracht opnieuw uit. Vernieuw de editor om de wijziging te zien. Dit is de basiscyclus: schrijf HTML, synchroniseer bewust en krijg blokken.

De sjabloontaal

De parser van Blockstudio voor HTML zet standaardelementen van HTML om in blokken van WordPress. Schrijf een <p> en je krijgt een alineablok. Schrijf een <h2> en je krijgt een kopblok. De koppeling is intuïtief:

HTML Blok
<p> Alinea
<h1> t/m <h6> Kop (niveau komt overeen met tag)
<ul>, <ol> Lijst
<blockquote> Citaat
<img> Afbeelding
<div>, <section> Groep
<hr> Scheidingsteken
<details> Details
<table> Tabel

Gebruik voor blokken zonder een rechtstreeks equivalent van HTML het element <block> met een attribuut name:

HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h2>Hero Title</h2>
  <p>Content over the background image.</p>
</block>

<block name="core/spacer" height="80px" />

<block name="core/buttons">
  <block name="core/button" url="/contact">Get in Touch</block>
  <block name="core/button" url="/work">See Our Work</block>
</block>

Attributen van <block>-elementen worden doorgegeven als blokattributen. Waarden worden automatisch omgezet: "true" wordt een boolean, "3" wordt een geheel getal en tekenreeksen zoals '{"type":"flex"}' in JSON worden omgezet in objecten.

Lay-outs

Groepen ondersteunen verschillende lay-outmodi via het attribuut layout:

HTML
<!-- Default group (stacked) -->
<div>
  <p>Stacked by default.</p>
</div>

<!-- Row (horizontal flex) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
  <p>Side</p>
  <p>by side</p>
</block>

<!-- Stack (vertical flex) -->
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
  <p>Stacked</p>
  <p>with flex</p>
</block>

<!-- Columns -->
<block name="core/columns">
  <block name="core/column">
    <p>Left column.</p>
  </block>
  <block name="core/column">
    <p>Right column.</p>
  </block>
</block>

Aangepaste blokken

De syntaxis <block> werkt voor elk geregistreerd blok, ook voor je eigen blokken van Blockstudio:

HTML
<block name="my-theme/hero" title="Welcome" background="dark" />
<block name="my-theme/testimonial" quote="Great product." author="Jane" />

Attributen worden automatisch gekoppeld aan de veldwaarden van Blockstudio van het blok.

Een landingspagina bouwen

Hier is een volledige landingspagina die kernblokken gebruikt voor de structuur en lay-out:

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "slug": "landing",
  "postStatus": "publish",
  "templateLock": "all"
}
HTML
<block name="core/cover" url="https://images.unsplash.com/photo-1497366216548-37526070297c?w=1600">
  <h1>Build faster with Blockstudio</h1>
  <p>File-based blocks. Zero build step. Full editor integration.</p>
  <block name="core/buttons">
    <block name="core/button" url="/get-started">Get Started</block>
    <block name="core/button" url="/docs">Documentation</block>
  </block>
</block>

<div>
  <h2>Why developers love it</h2>
  <block name="core/columns">
    <block name="core/column">
      <h3>No build step</h3>
      <p>Write PHP, CSS, and JavaScript. No webpack, no bundler, no transpiler.</p>
    </block>
    <block name="core/column">
      <h3>File-based</h3>
      <p>Every block is a folder. Every page is a template. Version control everything.</p>
    </block>
    <block name="core/column">
      <h3>Full editor support</h3>
      <p>Fields, previews, and InnerBlocks work in the block editor out of the box.</p>
    </block>
  </block>
</div>

<block name="core/media-text" mediaurl="https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=800" mediatype="image">
  <h2>Ship entire sites from your IDE</h2>
  <p>Define pages, blocks, and patterns as files. Blockstudio handles the rest.</p>
</block>

<div>
  <h2>Frequently asked questions</h2>
  <details>
    <summary>Do I need to learn React?</summary>
    <p>No. Templates are PHP. Fields are JSON. Interactivity is optional.</p>
  </details>
  <details>
    <summary>Does it work with my existing theme?</summary>
    <p>Yes. Drop a blockstudio folder into any theme and start creating blocks.</p>
  </details>
</div>

<div>
  <block name="core/buttons">
    <block name="core/button" url="/get-started">Start Building</block>
  </block>
</div>

Deze pagina heeft een hero met omslagafbeelding, een raster met drie kolommen voor functies, een sectie met media en tekst, FAQ-accordeons en een CTA. Alles komt uit één bestand van HTML. De templateLock: "all" in page.json betekent dat de klant niets kan wijzigen. In het volgende gedeelte lees je hoe je die beperking versoepelt.

De editor aansturen

Hier worden pagina’s op basis van bestanden pas echt krachtig. Blockstudio biedt je twee onafhankelijke instellingen: sjabloonvergrendeling en blokbewerkingsmodus. Samen bepalen ze precies welke delen van een pagina klanten kunnen aanpassen. Vergrendel de structuur, maar laat ze tekst bewerken. Zet sommige secties vast en laat andere volledig open. Maak een pagina waarop een klant alleen tekst in drie specifieke koppen kan invoeren.

Sjabloonvergrendeling

De eigenschap templateLock in page.json bepaalt structurele bewerkingen: of blokken kunnen worden toegevoegd, verwijderd of verplaatst.

"all" (standaard)

JSON
{
  "name": "terms",
  "templateLock": "all"
}

De strengste vergrendeling. Klanten kunnen geen blokken toevoegen, verwijderen of verplaatsen. Ze kunnen ook de inhoud van blokken niet bewerken (tenzij gecombineerd met blockEditingMode). Dit is de standaard als je geen waarde opgeeft.

Wanneer gebruiken: juridische pagina’s, servicevoorwaarden en privacybeleid. Elke pagina waarvan de inhoud alleen via code mag veranderen.

"insert"

JSON
{
  "name": "about",
  "templateLock": "insert"
}

Klanten kunnen geen blokken toevoegen of verwijderen, maar wel bestaande blokken verplaatsen en de inhoud ervan bewerken. Het aantal blokken blijft gelijk, maar de volgorde is vrij.

Wanneer gebruiken: pagina’s met een vaste set secties die de klant wel moet kunnen herschikken. Bijvoorbeeld een portfolio met een vooraf bepaald aantal secties, waarvan de klant de volgorde bepaalt.

"contentOnly"

JSON
{
  "name": "homepage",
  "templateLock": "contentOnly"
}

Klanten kunnen tekst bewerken, maar geen blokken toevoegen, verwijderen of verplaatsen. Het verschil met "all" is dat "all" ook inhoudsbewerking voorkomt, terwijl "contentOnly" die uitdrukkelijk toestaat.

Wanneer gebruiken: de meest gebruikelijke keuze voor pagina’s voor klanten. De ontwikkelaar bepaalt de lay-out. De klant vult de tekst in.

false

JSON
{
  "name": "blog",
  "templateLock": false
}

Helemaal geen vergrendeling. Klanten hebben volledige controle: ze kunnen elk blok toevoegen, verwijderen, verplaatsen en bewerken. Het sjabloon biedt een beginstructuur, maar daarna is de pagina van de klant.

Wanneer gebruiken: blogoverzichtspagina’s, pagina’s met vrije inhoud of elke pagina waarop de klant volledige redactionele vrijheid moet hebben.

Blokbewerkingsmodus

Terwijl templateLock de structuur bepaalt (toevoegen, verwijderen, verplaatsen), bepaalt blockEditingMode de interactie per blok: of blokken kunnen worden geselecteerd, ingesteld of überhaupt bewerkt.

Stel een standaardwaarde voor de pagina in via page.json:

JSON
{
  "name": "landing",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}

"default"

Volledige bewerking. Blokken kunnen worden geselecteerd, hun instellingen kunnen worden gewijzigd en de inhoud kan worden bewerkt. Dit is de normale editorervaring.

"contentOnly"

Blokken zijn bewerkbaar, maar alleen qua tekstinhoud. Je kunt blokinstellingen niet openen, kleuren niet wijzigen, opvulling niet aanpassen en geen andere kenmerken dan de inhoud wijzigen. De blokwerkbalk toont alleen opties voor tekstopmaak.

"disabled"

Blokken zijn volledig niet-interactief. Ze worden weergegeven in de editor, maar kunnen niet worden aangeklikt, geselecteerd of op welke manier dan ook aangepast. De klant ziet de inhoud, maar kan er niets aan veranderen.

Instellingen per element

Hier wordt het interessant. De pagina-instelling blockEditingMode bepaalt de standaard voor elk blok op de pagina, maar je kunt die voor afzonderlijke elementen in het sjabloon overschrijven:

JSON
{
  "name": "landing",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h1 blockEditingMode="contentOnly">Edit This Heading</h1>
  <p blockEditingMode="contentOnly">Edit this paragraph too.</p>
</block>

<div>
  <h2>Features</h2>
  <p>This paragraph cannot be edited (inherits "disabled").</p>
  <p blockEditingMode="contentOnly">But this one can.</p>
</div>

<block name="core/buttons">
  <block name="core/button" url="/contact">This button is frozen</block>
</block>

De standaard voor de pagina is "disabled", dus elk blok is aanvankelijk niet-interactief. Specifieke elementen schakelen vervolgens "contentOnly" in, zodat alleen hun tekst bewerkbaar is. Het resultaat: een pagina waarop de klant precies twee tekstvelden (de kop en alinea van de hero) en één alinea met een functie kan invullen. Al het andere blijft vergrendeld.

Dit werkt voor elk element van HTML (<h1>, <p>, <div> enzovoort) en voor elementen van <block>. Je kunt ook blockEditingMode="default" instellen voor specifieke elementen om volledige bewerkingsrechten te geven:

HTML
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>

Nu kan de klant de knoptekst, URL, stijlen en alle andere instellingen wijzigen. De rest van de pagina blijft vergrendeld.

De cascade van voorouders

Er is een belangrijk detail bij de manier waarop instellingen per element samenwerken met containerblokken. Als de standaard voor de pagina "disabled" is en je blockEditingMode="contentOnly" instelt voor een kop binnen een groep, moet die kop bereikbaar zijn. Maar de bovenliggende groep is "disabled", waardoor je die helemaal niet kunt openen.

Blockstudio regelt dit automatisch. Wanneer een onderliggend blok een overschrijving van de bewerkingsmodus heeft, worden alle voorouderblokken ingesteld op "contentOnly" zodat het onderliggende blok bereikbaar blijft. Je hoeft de modi van bovenliggende containers niet handmatig in te stellen. Stel de overschrijving in voor het blok dat je bewerkbaar wilt maken; de route ernaartoe wordt dan geopend.

HTML
<!-- page default: "disabled" -->
<div>
  <!-- this group is auto-set to "contentOnly" because it contains an override -->
  <div>
    <!-- this group is also auto-set to "contentOnly" -->
    <p blockEditingMode="contentOnly">Deeply nested but still editable.</p>
  </div>
</div>

De cascade van voorouders verhoogt containers alleen naar "contentOnly", nooit naar "default". Daardoor kun je bovenliggende groepen navigeren (je kunt ze openen), maar niet volledig bewerken (je kunt hun instellingen niet wijzigen).

De beslismatrix

Door templateLock en blockEditingMode te combineren, krijg je verschillende niveaus van controle. Dit zijn de nuttigste combinaties:

De ontwikkelaar bepaalt alles

JSON
{ "templateLock": "all" }

blockEditingMode is niet nodig. De standaardinstelling templateLock: "all" voorkomt alle wijzigingen. Gebruik dit voor pagina’s die volledig via code worden beheerd.

De klant bewerkt alle tekst

JSON
{ "templateLock": "contentOnly" }

De klant kan tekst in elk blok bewerken, maar de paginastructuur niet wijzigen. Eenvoudig en flexibel.

De klant bewerkt alleen specifieke tekst

JSON
{
  "templateLock": "all",
  "blockEditingMode": "disabled"
}

Gecombineerd met blockEditingMode="contentOnly" voor specifieke elementen in het sjabloon. Dit is de nauwkeurigste optie: de klant kan alleen de blokken bewerken die jij markeert.

De klant herschikt vaste secties

JSON
{ "templateLock": "insert" }

De klant kan secties herschikken en inhoud bewerken, maar geen blokken toevoegen of verwijderen. Geschikt voor pagina’s met een vaste set secties waarvan de volgorde mag veranderen.

De klant heeft volledige controle

JSON
{ "templateLock": false }

Het sjabloon is een beginpunt. Daarna kan de klant alles aanpassen.

Bewerkingen van klanten behouden

Standaard vervangt Blockstudio de volledige pagina-inhoud wanneer je een sjabloonbestand bijwerkt. Heeft de klant een kop in de editor aangepast, dan verdwijnt die wijziging na de volgende synchronisatie. Dat is prima voor pagina’s die door ontwikkelaars worden beheerd, maar voor pagina’s waaraan klanten inhoud toevoegen, moet je hun werk kunnen behouden.

Sleutels

Voeg een attribuut key toe aan een element om het samen te voegen in plaats van te vervangen:

HTML
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
  <h1>Default Hero Title</h1>
  <p>Default hero description.</p>
</block>

<div key="features">
  <h2>Features</h2>
  <p>Feature introduction text.</p>
</div>

<div>
  <h2>Unkeyed Section</h2>
  <p>This gets replaced on every sync.</p>
</div>

Wanneer het sjabloon verandert en de pagina opnieuw wordt gesynchroniseerd:

  • Blokken met een sleutel behouden de inhoud van de klant (tekst, binnenliggende blokken en opmaak). De structurele attributen van het sjabloon (zoals url van de omslagafbeelding) worden nog steeds bijgewerkt.
  • Blokken zonder sleutel worden volledig vervangen door de versie uit het sjabloon.

Een sleutel beschermt het hele blok en alle onderliggende elementen. Je hoeft geen afzonderlijke alinea’s binnen een groep met een sleutel te markeren. De sleutel van de groep beschermt alles daarin.

Sleutels moeten uniek zijn

Sleutels moeten uniek zijn binnen het hele sjabloon. Als twee elementen dezelfde sleutel hebben, wordt het tweede behandeld als een element zonder sleutel (en verschijnt er een waarschuwing PHP). Gebruik beschrijvende namen: "hero", "features", "cta", "testimonial-section".

Sjablonen uitbreiden

Met sleutels kun je nieuwe secties aan een sjabloon toevoegen zonder bestaande inhoud van klanten te verstoren:

HTML
<h1 key="title">Welcome</h1>
<div key="services">
  <h2>Our Services</h2>
  <p>We do great work.</p>
</div>
HTML
<h1 key="title">Welcome</h1>
<div key="services">
  <h2>Our Services</h2>
  <p>We do great work.</p>
</div>
<div key="testimonials">
  <h2>What Clients Say</h2>
  <p>Default testimonial text.</p>
</div>

Na de synchronisatie behouden de titel en diensten de wijzigingen van de klant. De nieuwe sectie met testimonials verschijnt met de standaardinhoud van het sjabloon. Verwijder je later een blok met een sleutel uit het sjabloon, dan wordt het van de pagina verwijderd.

De volledige workflow voor klanten

Zo breng je alles samen in een echt project:

JSON
{
  "name": "homepage",
  "title": "Home",
  "slug": "home",
  "postStatus": "publish",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
  <h1 blockEditingMode="contentOnly">Your Company Name</h1>
  <p blockEditingMode="contentOnly">Your tagline goes here.</p>
  <block name="core/buttons">
    <block name="core/button" url="/contact">Contact Us</block>
  </block>
</block>

<div key="features">
  <h2 blockEditingMode="contentOnly">What We Do</h2>
  <block name="core/columns">
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service One</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service Two</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service Three</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
  </block>
</div>

<block name="core/media-text" key="about" mediaurl="https://example.com/team.jpg" mediatype="image">
  <h2 blockEditingMode="contentOnly">About Us</h2>
  <p blockEditingMode="contentOnly">Tell your story here.</p>
</block>

<div key="cta">
  <h2 blockEditingMode="contentOnly">Ready to get started?</h2>
  <block name="core/buttons">
    <block name="core/button" url="/contact">Get in Touch</block>
  </block>
</div>

Deze pagina heeft vier secties met een sleutel. De klant kan koppen en alinea’s bewerken die zijn gemarkeerd met blockEditingMode="contentOnly"; die wijzigingen blijven behouden wanneer het sjabloon wordt bijgewerkt. De ontwikkelaar bepaalt de lay-out, afbeeldingen, knop-URL’s en de algemene structuur. Voegt de ontwikkelaar later een sectie met testimonials toe tussen “about” en “cta”, dan verschijnt die bij de volgende synchronisatie zonder de tekst van de klant te verstoren.

Blokkoppelingen: een alternatief voor sleutels

WordPress 6.5 introduceerde de Block Bindings API, waarmee blokattributen aan berichtmeta worden gekoppeld. In plaats van bewerkbare inhoud op te slaan in de blokopmaak (waar sleutels die beschermen), staat de inhoud in wp_postmeta (waar synchronisatie van sjablonen er niet bij kan).

HTML
<h1 metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'>
  Default Title
</h1>

<p metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'>
  Default description.
</p>

De metasleutels moeten worden geregistreerd in PHP:

PHP
register_post_meta( 'page', 'hero_title', array(
    'show_in_rest' => true,
    'single'       => true,
    'type'         => 'string',
    'default'      => 'Default Title',
) );

Blokkoppelingen hebben twee voordelen ten opzichte van sleutels: je kunt de gegevens opvragen met WP_Query via meta_query en ze zijn beschikbaar in de REST API. Het nadeel is dat je elke metasleutel moet registreren in PHP en dat koppelingen alleen werken voor afzonderlijke blokkenmerken (niet voor complexe geneste inhoud).

Gebruik sleutels voor uitgebreide inhoudssecties waarbij de blokstructuur van belang is (een groep met koppen, alinea’s en afbeeldingen). Gebruik koppelingen voor afzonderlijke tekstwaarden die je ook wilt opvragen of elders wilt weergeven.

Templates voor berichttypen

Gebruik templateFor om een standaard blokstructuur in te stellen voor alle nieuwe berichten van een bepaald type:

JSON
{
  "name": "product-template",
  "title": "Product Template",
  "templateFor": "product",
  "templateLock": "insert"
}
HTML
<h1>Product Name</h1>

<block name="core/columns">
  <block name="core/column">
    <img src="" alt="Product image" />
  </block>
  <block name="core/column">
    <p>Product description goes here.</p>
    <block name="core/buttons">
      <block name="core/button" url="#">Buy Now</block>
    </block>
  </block>
</block>

<div>
  <h2>Specifications</h2>
  <table>
    <thead>
      <tr><th>Feature</th><th>Value</th></tr>
    </thead>
    <tbody>
      <tr><td>Weight</td><td>1.2 kg</td></tr>
    </tbody>
  </table>
</div>

Elk nieuw bericht van het type “product” begint met deze structuur. Met templateLock: "insert" kunnen redacteuren secties herschikken en inhoud bewerken, maar geen blokken toevoegen of verwijderen.

Tips

Synchroniseer op een bewust gekozen implementatiemoment. Voer wp bs pages sync uit nadat je paginabronnen hebt gewijzigd of geïmplementeerd. Bezoeken aan de frontend en het beheergedeelte synchroniseren pagina’s nooit. PHP-implementatietools kunnen Blockstudio\Pages::reconcile() aanroepen en het machineleesbare rapport inspecteren.

Leg belangrijke bericht-ID’s vast. Gebruik postId in page.json voor pagina’s waarnaar menu’s, hardgecodeerde links of externe systemen verwijzen. Zonder deze vastlegging krijgt een verwijderde en opnieuw aangemaakte pagina een nieuwe ID, waardoor die verwijzingen niet meer werken.

Gebruik sync: false voor startpagina’s. Wil je een pagina één keer maken en daarna volledig aan de klant overdragen, stel dan "sync": false in en maak de pagina met Blockstudio\Pages::force_sync(). Bij normale afstemming wordt die pagina vervolgens genegeerd.

Vergrendel en ontgrendel via PHP. Roep Blockstudio\Pages::lock('about') aan om te voorkomen dat een specifieke pagina wordt gesynchroniseerd (handig tijdens bewerkperiodes van klanten). Roep Blockstudio\Pages::unlock('about') aan om synchronisatie weer in te schakelen.

Sjabloonengines. Naast PHP kun je sjablonen schrijven in Twig (vereist Timber) of Blade (vereist illuminate/view). Dit is handig voor lussen en filters, maar paginasjablonen worden gecompileerd tijdens expliciete synchronisatie, niet tijdens een frontendverzoek. Gebruik PHP als ook de broncompilatie zelf PHP-specifieke helpers nodig heeft.

Geforceerde synchronisatie negeert sleutels. Met Pages::force_sync('about') wordt de volledige pagina-inhoud vervangen; sleutels en controles van de wijzigingstijd worden genegeerd. Gebruik dit als je een pagina bewust wilt terugzetten naar de sjabloontoestand.

Volgende stappen

  • Paginareferentie: alle eigenschappen van page.json, het PHP API en het samenvoegalgoritme met sleutels, in detail.
  • Overzicht van pagina’s en patronen: de parser van HTML, de referentie voor bloksynchronisatie, aangepaste renderers en elementkoppeling.
  • Patronen: dezelfde sjabloonsyntaxis voor herbruikbare blokpatronen in plaats van pagina’s.