Oprettelse af filbaserede sider
Traditionel opbygning af WordPress-sider foregår i blokeditoren: træk blokke, konfigurér indstillinger, klik på Gem. Det fungerer for kunder, der opbygger deres egne sider, men skaber problemer for udviklere, der bygger strukturerede sider under versionsstyring. Sidens layout ligger i databasen, ikke i kode. Du kan ikke gennemgå det i en pull request, rulle det tilbage med git eller genskabe det i en ny installation.
Blockstudios filbaserede sider løser dette. Du definerer sider som filer i dit tema, skriver HTML-skabeloner, der konverteres til WordPress-blokke, og styrer præcist, hvad kunder kan og ikke kan redigere. En eksplicit kommando synkroniserer filerne med almindelige WordPress-indlæg, og dine skabeloner forbliver den autoritative kilde.
Denne guide gennemgår opbygningen af sider fra bunden med særligt fokus på låse- og redigeringskontrollerne, der gør filbaserede sider praktiske til kundeprojekter.
Din første side
Opret en mappe pages i dit tema, og tilføj derefter en undermappe med to filer:
theme/
└── pages/
└── about/
├── page.json
└── index.php
{
"name": "about",
"title": "About Us",
"postStatus": "publish"
}
<h1>About Us</h1>
<p>We build things for the web.</p>
Kør kommandoen til sidesynkronisering:
wp bs pages sync
Blockstudio analyserer HTML til WordPress-blokke og opretter en side med navnet
“Om os” og sluggen about. Åbn siden i editoren, så ser du en
overskrift og et afsnit, præcis som hvis du havde tilføjet dem manuelt.
Rediger index.php, skift teksten, og kør kommandoen igen. Genindlæs editoren
for at se opdateringen. Dette er den grundlæggende arbejdsgang: Skriv HTML, synkroniser efter behov, få blokke.
Skabelonsproget
Blockstudios HTML-parser konverterer standardelementer fra HTML til WordPress-blokke. Skriv et <p>, så får du en afsnitsblok. Skriv et <h2>, så får du en overskriftsblok. Tilknytningen er intuitiv:
| HTML | Blok |
|---|---|
<p> |
Afsnit |
<h1> til <h6> |
Overskrift (niveauet svarer til tagget) |
<ul>, <ol> |
Liste |
<blockquote> |
Citat |
<img> |
Billede |
<div>, <section> |
Gruppe |
<hr> |
Adskiller |
<details> |
Detaljer |
<table> |
Tabel |
Brug elementet <block> med attributten name til blokke uden et direkte HTML-modstykke:
<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>
Attributter på <block>-elementer overføres som blokattributter. Værdier konverteres automatisk: "true" bliver en boolsk værdi, "3" bliver et heltal, og strenge som '{"type":"flex"}' i JSON afkodes til objekter.
Layouts
Grupper understøtter forskellige layouttilstande via attributten layout:
<!-- 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>
Brugerdefinerede blokke
Syntaksen <block> fungerer med alle registrerede blokke, herunder dine egne blokke af typen Blockstudio:
<block name="my-theme/hero" title="Welcome" background="dark" />
<block name="my-theme/testimonial" quote="Great product." author="Jane" />
Attributter tilknyttes automatisk blokkens Blockstudio-feltværdier.
Opbygning af en landingsside
Her er en komplet landingsside, der bruger kerneblokke til struktur og layout:
{
"name": "landing",
"title": "Landing Page",
"slug": "landing",
"postStatus": "publish",
"templateLock": "all"
}
<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>
Denne side har en hero med cover, et funktionsgitter med tre kolonner, en sektion med medier og tekst, FAQ-felter, der kan foldes ud, og en CTA. Alt sammen i én HTML-fil. templateLock: "all" i page.json betyder, at kunden ikke kan ændre noget. Næste sektion forklarer, hvordan du åbner for redigering.
Styring af editoren
Her bliver filbaserede sider for alvor kraftfulde. Blockstudio giver dig to uafhængige indstillinger: skabelonlås og blokredigeringstilstand. Sammen lader de dig præcist bestemme, hvilke dele af en side klienter kan ændre. Lås strukturen, men lad dem redigere teksten. Frys nogle sektioner, mens andre er helt åbne. Opret en side, hvor klienten kun kan skrive i tre bestemte overskrifter.
Skabelonlås
Egenskaben templateLock i page.json styrer strukturel redigering: om blokke kan tilføjes, fjernes eller omarrangeres.
"all" (standard)
{
"name": "terms",
"templateLock": "all"
}
Den strengeste lås. Klienter kan ikke tilføje, fjerne eller flytte blokke. De kan heller ikke redigere blokindhold (medmindre den kombineres med blockEditingMode). Dette er standarden, når du ikke angiver en værdi.
Hvornår skal den bruges: Juridiske sider, servicevilkår, privatlivspolitikker. Alle sider, hvor indholdet kun bør ændres via kode.
"insert"
{
"name": "about",
"templateLock": "insert"
}
Klienter kan ikke tilføje eller fjerne blokke, men de kan flytte eksisterende blokke rundt og redigere deres indhold. Antallet af blokke forbliver fast, men rækkefølgen kan ændres.
Hvornår skal den bruges: Sider, hvor du ønsker et fast sæt sektioner, men klienten skal kunne ændre rækkefølgen. En portfolioside, hvor antallet af sektioner er fastlagt på forhånd, men klienten bestemmer rækkefølgen.
"contentOnly"
{
"name": "homepage",
"templateLock": "contentOnly"
}
Klienter kan redigere tekstindhold, men kan ikke tilføje, fjerne eller flytte blokke. Forskellen fra "all" er, at "all" også forhindrer redigering af indhold, mens "contentOnly" udtrykkeligt tillader det.
Hvornår skal den bruges: Det mest almindelige valg til sider, der er rettet mod klienter. Udvikleren styrer layoutet. Klienten udfylder teksten.
false
{
"name": "blog",
"templateLock": false
}
Ingen lås. Klienter har fuld kontrol: De kan tilføje, fjerne, flytte og redigere alle blokke. Skabelonen giver en grundstruktur, men derefter bestemmer klienten.
Hvornår skal den bruges: Blogoversigtssider, sider med frit indhold eller andre sider, hvor klienten skal have fuld redaktionel frihed.
Blokredigeringstilstand
Mens templateLock styrer strukturen (tilføj, fjern, flyt), styrer blockEditingMode interaktionen på den enkelte blok: om blokke overhovedet kan vælges, konfigureres eller redigeres.
Angiv en standard på sideniveau i page.json:
{
"name": "landing",
"templateLock": "all",
"blockEditingMode": "disabled"
}
"default"
Fuld redigering. Blokke kan vælges, deres indstillinger kan ændres, og indholdet kan redigeres. Dette er den normale redigeringsoplevelse.
"contentOnly"
Blokke kan redigeres, men kun deres tekstindhold. Du kan ikke åbne blokindstillinger, ændre farver, justere indvendig afstand eller ændre andre attributter end indholdet. Blokværktøjslinjen viser kun muligheder for tekstformatering.
"disabled"
Blokke er helt inaktive. De vises i editoren, men kan ikke klikkes på, vælges eller ændres på nogen måde. Klienten kan se indholdet, men ikke røre det.
Tilsidesættelser for enkelte elementer
Her bliver det interessant. Indstillingen blockEditingMode på sideniveau angiver en standard for alle blokkene på siden, men du kan tilsidesætte den for enkelte elementer i skabelonen:
{
"name": "landing",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<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>
Sidens standard er "disabled", så alle blokke er inaktive fra start. Derefter tilvælger bestemte elementer "contentOnly", så kun deres tekst kan redigeres. Resultatet er en side, hvor klienten kan skrive i præcis to tekstfelter (hero-overskriften og afsnittet) samt ét funktionsafsnit. Alt andet er låst.
Dette fungerer på alle elementer af typen HTML (<h1>, <p>, <div> osv.) og på elementer af typen <block>. Du kan også angive blockEditingMode="default" for bestemte elementer for at give fuld adgang til redigering:
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
Nu kan klienten ændre knapteksten, URL, typografier og alle andre indstillinger. Alt andet på siden forbliver låst.
Kaskaden fra overordnede blokke
Der er en vigtig detalje ved samspillet mellem tilsidesættelser for enkelte elementer og containerblokke. Hvis sidens standard er "disabled", og du angiver blockEditingMode="contentOnly" for en overskrift i en gruppe, skal overskriften være tilgængelig. Men dens overordnede gruppe er "disabled", hvilket betyder, at den slet ikke kan åbnes.
Blockstudio håndterer dette automatisk. Når en underordnet blok har en tilsidesættelse af redigeringstilstanden, sættes alle dens overordnede blokke til "contentOnly", så den underordnede blok forbliver tilgængelig. Du behøver ikke manuelt at angive tilstande for overordnede containere. Angiv blot tilsidesættelsen for den blok, du vil gøre redigerbar, så åbnes vejen til den.
<!-- 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>
Kaskaden fra overordnede blokke hæver kun containere til "contentOnly", aldrig til "default". Det betyder, at overordnede grupper kan navigeres (du kan åbne dem), men ikke redigeres fuldt ud (du kan ikke ændre deres indstillinger).
Beslutningsmatrix
Ved at kombinere templateLock og blockEditingMode får du forskellige grader af kontrol. Her er de mest nyttige kombinationer:
Udvikleren styrer alt
{ "templateLock": "all" }
Ingen blockEditingMode nødvendig. Standardværdien templateLock: "all" forhindrer alle ændringer. Brug dette til sider, der udelukkende administreres via kode.
Klienten redigerer al tekst
{ "templateLock": "contentOnly" }
Klienten kan redigere tekst i alle blokke, men kan ikke ændre sidens struktur. Enkelt og fleksibelt.
Klienten redigerer kun bestemt tekst
{
"templateLock": "all",
"blockEditingMode": "disabled"
}
Kombineret med blockEditingMode="contentOnly" på bestemte elementer i skabelonen. Dette er den mest præcise mulighed: Klienten kan kun redigere de blokke, du specifikt markerer.
Klienten ændrer rækkefølgen på faste sektioner
{ "templateLock": "insert" }
Klienten kan omarrangere sektioner og redigere indhold, men kan ikke tilføje eller slette blokke. Godt til sider med et fast sæt sektioner i en fleksibel rækkefølge.
Klienten har fuld kontrol
{ "templateLock": false }
Skabelonen er et udgangspunkt. Derefter kan klienten gøre, hvad som helst.
Bevar klientens redigeringer
Som standard erstatter Blockstudio hele sidens indhold, når du opdaterer en skabelonfil. Hvis klienten har redigeret en overskrift i editoren, går ændringen tabt ved næste synkronisering. Det er fint for sider, som udvikleren styrer, men sider, hvor klienter bidrager med indhold, kræver en måde at bevare deres arbejde på.
Nøgler
Tilføj attributten key til et vilkårligt element for at markere det til sammenfletning i stedet for erstatning:
<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>
Når skabelonen ændres, og siden synkroniseres igen:
- Blokke med nøgler bevarer klientens indhold (tekst, indre blokke, formatering). Skabelonens strukturelle attributter (som
urlfor coveret) opdateres stadig. - Blokke uden nøgler erstattes helt af skabelonversionen.
En nøgle beskytter hele blokken og alle dens underordnede blokke. Du behøver ikke at tilføje nøgler til enkelte afsnit i en gruppe med nøgle. Gruppens nøgle dækker alt indhold i den.
Nøgler skal være unikke
Nøgler skal være unikke på tværs af hele skabelonen. Hvis to elementer deler den samme nøgle, behandles det andet som et element uden nøgle (og der udsendes en advarsel fra PHP). Brug beskrivende navne: "hero", "features", "cta", "testimonial-section".
Skabeloner i udvikling
Med nøgler kan du føje nye sektioner til en skabelon uden at forstyrre eksisterende indhold fra klienten:
<h1 key="title">Welcome</h1>
<div key="services">
<h2>Our Services</h2>
<p>We do great work.</p>
</div>
<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>
Ved synkronisering bevares klientens ændringer i titlen og tjenesterne. Den nye sektion med kundeudtalelser vises med skabelonens standardindhold. Hvis du senere fjerner en blok med nøgle fra skabelonen, slettes den fra siden.
Hele klientens arbejdsgang
Sådan samles det hele i et rigtigt projekt:
{
"name": "homepage",
"title": "Home",
"slug": "home",
"postStatus": "publish",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<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>
Denne side har fire sektioner med nøgler. Klienten kan redigere overskrifter og afsnit markeret med blockEditingMode="contentOnly", og disse ændringer bevares ved skabelonopdateringer. Udvikleren styrer layoutet, billederne, knap-URL’erne og den overordnede struktur. Hvis udvikleren senere tilføjer en sektion med kundeudtalelser mellem “about” og “cta”, vises den ved næste synkronisering uden at forstyrre klientens tekst.
Blokbindinger: et alternativ til nøgler
WordPress 6.5 introducerede Block Bindings API, som forbinder blokattributter med indlæggets metadata. I stedet for at gemme redigerbart indhold i blokopmærkningen (hvor nøgler beskytter det) ligger indholdet i wp_postmeta (hvor skabelonsynkronisering ikke kan ændre det).
<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>
Metanøglerne skal registreres i PHP:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Blokbindinger har to fordele frem for nøgler: Dataene kan forespørges med WP_Query via meta_query, og de er tilgængelige i REST API. Ulempen er, at du skal registrere hver metanøgle i PHP, og bindinger kun fungerer for individuelle blokattributter (ikke komplekst indlejret indhold).
Brug nøgler til indholdssektioner med rigt indhold, hvor blokstrukturen er vigtig (en gruppe med overskrifter, afsnit og billeder). Brug bindinger til enkelte tekstværdier, som du også skal kunne forespørge på eller vise andre steder.
Skabeloner til indholdstyper
Brug templateFor til at angive en standardblokstruktur for alle nye indlæg af en bestemt type:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
<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>
Alle nye indlæg af typen “product” starter med denne struktur. templateLock: "insert" lader redaktører omarrangere sektioner og redigere indhold, men ikke tilføje eller fjerne blokke.
Tips
Synkroniser ved en planlagt udrulningsgrænse. Kør wp bs pages sync efter
ændring eller udrulning af sidekilder. Besøg på frontend eller i admin synkroniserer aldrig
sider. PHP-udrulningsværktøjer kan kalde Blockstudio\Pages::reconcile() og
gennemgå den maskinlæsbare rapport.
Fastlås vigtige indlægs-id’er. Brug postId i page.json for sider, der henvises til fra menuer, hardkodede links eller eksterne systemer. Uden fastlåsning får en side, der slettes og oprettes igen, et nyt id, og disse referencer går i stykker.
Brug sync: false til grundsider. Hvis du vil oprette en side én gang og derefter
overdrage den helt til klienten, skal du angive "sync": false og oprette den med
Blockstudio\Pages::force_sync(). Normal afstemning ignorerer den derefter.
Lås og lås op via PHP. Kald Blockstudio\Pages::lock('about') for at forhindre synkronisering af en bestemt side (nyttigt under redigeringsperioder for klienter). Kald Blockstudio\Pages::unlock('about') for at aktivere synkronisering igen.
Skabelonmotorer. Ud over PHP kan skabeloner skrives i Twig (kræver Timber) eller Blade (kræver illuminate/view). Det er nyttigt til løkker og filtre, men sideskabeloner kompileres under eksplicit synkronisering, ikke under en frontendforespørgsel. Brug PHP, hvis selve kildekompileringen har brug for hjælpere, der kun findes i PHP.
Tvungen synkronisering ignorerer nøgler. Kald Pages::force_sync('about') for at erstatte hele sidens indhold og ignorere nøgler samt kontrol af ændringstidspunkt. Brug det, når du bevidst vil nulstille en side til skabelontilstanden.
Næste trin
- Sider: reference: alle
page.json-egenskaber, PHP API og den nøglebaserede sammenfletningsalgoritme i detaljer. - Sider og mønstre: oversigt: HTML-parseren, reference til bloksyntaks, brugerdefinerede renderere og elementtilknytning.
- Mønstre: den samme skabelonsyntaks til genanvendelige blokmønstre i stedet for sider.