Hoppa till innehåll

Skapa filbaserade sidor

Traditionellt skapas WordPress-sidor i blockredigeraren: block dras in, inställningar konfigureras och ändringar sparas. Det fungerar för klienter som skapar egna sidor, men skapar problem för utvecklare som bygger strukturerade, versionshanterade sidor. Sidlayouten ligger i databasen, inte i koden. Du kan inte granska den i en pull request, återställa den med git eller återskapa den på en ny installation.

Blockstudios filbaserade sidor löser det här. Du definierar sidor som filer i ditt tema, skriver mallar i HTML som konverteras till block av typen WordPress och styr exakt vad klienter får och inte får redigera. Ett uttryckligt kommando synkroniserar filerna till vanliga inlägg av typen WordPress, och mallarna förblir den enda sanningskällan.

Den här guiden går igenom hur du bygger sidor från grunden, med stort fokus på låsning och redigeringskontroller som gör filbaserade sidor praktiska i klientprojekt.

Din första sida

Skapa en mapp pages i ditt tema och lägg sedan till en undermapp med två filer:

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

Kör kommandot för sidsynkronisering:

Shell
wp bs pages sync

Blockstudio tolkar HTML till block av typen WordPress och skapar en sida med namnet “About Us” och permalänken about. Öppna den i redigeraren så ser du en rubrik och ett stycke, precis som om du hade lagt till dem manuellt.

Redigera index.php, ändra texten och kör kommandot igen. Läs in redigeraren på nytt för att se uppdateringen. Det här är grundflödet: skriv HTML, synkronisera medvetet och få block.

Mallspråket

Blockstudios HTML-parser konverterar vanliga HTML-element till block av typen WordPress. Skriv en <p> så får du ett styckesblock. Skriv en <h2> så får du ett rubrikblock. Mappningen är intuitiv:

HTML Block
<p> Stycke
<h1> till <h6> Rubrik (nivån motsvarar taggen)
<ul>, <ol> Lista
<blockquote> Citat
<img> Bild
<div>, <section> Grupp
<hr> Avdelare
<details> Detaljer
<table> Tabell

För block utan en direkt motsvarighet i HTML använder du elementet <block> med attributet 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>

Attribut på <block>-element skickas vidare som blockattribut. Värden konverteras automatiskt: "true" blir ett booleskt värde, "3" blir ett heltal och JSON strängar som '{"type":"flex"}' avkodas till objekt.

Layouter

Grupper stöder olika layoutlägen via attributet 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>

Anpassade block

Syntaxen <block> fungerar för alla registrerade block, även dina egna block av typen Blockstudio:

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

Attribut mappas automatiskt till blockets fältvärden i Blockstudio.

Skapa en landningssida

Här är en komplett landningssida som använder kärnblock för struktur och layout:

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>

Sidan har en hero-bild, ett funktionsrutnät med tre kolumner, ett avsnitt med media och text, dragspelsmenyer för vanliga frågor och en CTA. Allt i en enda fil av typen HTML. templateLock: "all" i page.json innebär att klienten inte kan ändra någonting. Nästa avsnitt förklarar hur du lättar på den begränsningen.

Styra redigeraren

Här blir filbaserade sidor verkligen kraftfulla. Blockstudio ger dig två oberoende kontroller: mallås och blockredigeringsläge. Tillsammans låter de dig bestämma exakt vilka delar av en sida kunderna kan ändra. Lås strukturen men låt dem redigera text. Frys vissa avsnitt medan andra förblir helt öppna. Skapa en sida där kunden bara kan skriva i tre specifika rubriker.

Mallås

Egenskapen templateLock i page.json styr strukturell redigering: om block kan läggas till, tas bort eller ordnas om.

"all" (standard)

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

Det striktaste låset. Kunder kan inte lägga till, ta bort eller flytta block. De kan inte heller redigera blockinnehåll (om det inte kombineras med blockEditingMode). Detta är standardläget när du inte anger något värde.

När det ska användas: Juridiska sidor, användarvillkor och integritetspolicyer. Alla sidor där innehållet bara ska ändras via kod.

"insert"

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

Kunder kan inte lägga till eller ta bort block, men de kan flytta befintliga block och redigera innehållet. Antalet block förblir fast, men ordningen kan ändras.

När det ska användas: Sidor där du vill ha en fast uppsättning avsnitt men låta kunden ordna om dem. En portfoliosida där antalet avsnitt är förutbestämt, men kunden bestämmer ordningen.

"contentOnly"

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

Kunder kan redigera textinnehåll men inte lägga till, ta bort eller flytta block. Skillnaden jämfört med "all" är att "all" också förhindrar innehållsredigering, medan "contentOnly" uttryckligen tillåter den.

När det ska användas: Det vanligaste valet för sidor som kunder använder. Utvecklaren styr layouten. Kunden fyller i texten.

false

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

Inget lås alls. Kunder har full kontroll: de kan lägga till, ta bort, flytta och redigera alla block. Mallen ger en startstruktur, men sedan är det kunden som bestämmer.

När det ska användas: Bloggindexsidor, sidor med fritt innehåll eller andra sidor där kunden ska ha full redaktionell frihet.

Blockredigeringsläge

Medan templateLock styr strukturen (lägga till, ta bort, flytta), styr blockEditingMode interaktionen på enskild blocknivå: om block över huvud taget kan markeras, konfigureras eller redigeras.

Ange ett standardvärde för sidan i page.json:

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

"default"

Full redigering. Block kan markeras, deras inställningar kan ändras och innehållet kan redigeras. Det här är den vanliga redigerarupplevelsen.

"contentOnly"

Blocken är redigerbara, men bara vad gäller textinnehållet. Du kan inte öppna blockinställningar, ändra färger, justera utfyllnad eller ändra andra attribut än innehållsattribut. Blockverktygsfältet visar bara textformateringsalternativ.

"disabled"

Blocken är helt icke-interaktiva. De visas i redigeraren men kan inte klickas på, markeras eller ändras på något sätt. Kunden ser innehållet men kan inte röra det.

Åsidosättningar per element

Här blir det intressant. Sidans blockEditingMode anger ett standardvärde för varje block på sidan, men du kan åsidosätta det för enskilda element i mallen:

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>

Sidans standardvärde är "disabled", så varje block börjar som icke-interaktivt. Sedan aktiverar specifika element "contentOnly", vilket gör att bara deras text kan redigeras. Resultatet: en sida där kunden kan skriva i exakt två textfält (huvudrubriken och stycket i herosektionen) och ett funktionsstycke. Allt annat är låst.

Det här fungerar på alla element av typen HTML (<h1>, <p>, <div> och så vidare) och på element av typen <block>. Du kan också ange blockEditingMode="default" för specifika element för att ge full redigeringsåtkomst:

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

Nu kan kunden ändra knapptexten, URL, stilar och alla andra inställningar. Allt annat på sidan förblir fryst.

Kaskad för överordnade element

Det finns en viktig detalj kring hur åsidosättningar per element samverkar med containerblock. Om sidans standardvärde är "disabled" och du anger blockEditingMode="contentOnly" för en rubrik inuti en grupp måste det gå att komma åt rubriken. Men den överordnade gruppen är "disabled", vilket innebär att den inte går att öppna alls.

Blockstudio hanterar detta automatiskt. När ett underordnat block har ett åsidosatt redigeringsläge ställs alla dess överordnade block in på "contentOnly" så att det underordnade blocket förblir åtkomligt. Du behöver inte ange lägen manuellt för överordnade containrar. Ange bara åsidosättningen för blocket du vill göra redigerbart, så öppnas vägen dit.

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>

Kaskaden för överordnade element höjer bara containrar till "contentOnly", aldrig till "default". Det innebär att överordnade grupper blir navigerbara (du kan öppna dem), men inte fullt redigerbara (du kan inte ändra deras inställningar).

Beslutstabellen

Genom att kombinera templateLock och blockEditingMode får du ett brett spektrum av kontroll. Här är de mest användbara kombinationerna:

Utvecklaren styr allt

JSON
{ "templateLock": "all" }

Du behöver inte ange blockEditingMode. Standardvärdet templateLock: "all" förhindrar alla ändringar. Använd detta för sidor som hanteras helt via kod.

Kunden redigerar all text

JSON
{ "templateLock": "contentOnly" }

Kunden kan redigera text i alla block men inte ändra sidans struktur. Enkelt och tillåtande.

Kunden redigerar bara viss text

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

Kombineras med blockEditingMode="contentOnly" för specifika element i mallen. Det här är det mest precisa alternativet: kunden kan bara redigera exakt de block du markerar.

Kunden ordnar om fasta avsnitt

JSON
{ "templateLock": "insert" }

Kunden kan ordna om avsnitt och redigera innehåll, men inte lägga till eller ta bort block. Bra för sidor med en fast uppsättning avsnitt i en flexibel ordning.

Kunden har full kontroll

JSON
{ "templateLock": false }

Mallen är en startpunkt. Därefter kan kunden göra vad som helst.

Bevara kundens ändringar

Som standard ersätter Blockstudio hela sidinnehållet när du uppdaterar en mallfil. Om kunden redigerade en rubrik i redigeraren försvinner ändringen vid nästa synkronisering. Det fungerar bra för sidor som utvecklaren styr, men för sidor där kunder bidrar med innehåll behöver du ett sätt att bevara deras arbete.

Nycklar

Lägg till attributet key på valfritt element för att markera det för sammanslagning i stället för ersättning:

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>

När mallen ändras och sidan synkroniseras igen:

  • Block med nyckel behåller kundens innehåll (text, inre block och formatering). Mallens strukturella attribut (som url för omslaget) uppdateras fortfarande.
  • Block utan nyckel ersätts helt med mallversionen.

En nyckel skyddar hela blocket och alla dess underordnade element. Du behöver inte ange nycklar för enskilda stycken i en grupp som redan har en nyckel. Gruppens nyckel omfattar allt i den.

Nycklar måste vara unika

Nycklar måste vara unika i hela mallen. Om två element delar samma nyckel behandlas det andra som om det saknade nyckel (och en varning om PHP visas). Använd beskrivande namn: "hero", "features", "cta", "testimonial-section".

Mallar som utvecklas

Med nycklar kan du lägga till nya avsnitt i en mall utan att störa befintligt innehåll från kunden:

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>

Vid synkronisering behåller titeln och tjänsterna kundens ändringar. Det nya avsnittet med kundomdömen visas med mallens standardinnehåll. Om du senare tar bort ett block med nyckel från mallen tas det bort från sidan.

Kundens fullständiga arbetsflöde

Så här kan allt sättas ihop i ett verkligt projekt:

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>

Den här sidan har fyra avsnitt med nycklar. Kunden kan redigera rubriker och stycken markerade med blockEditingMode="contentOnly", och ändringarna bevaras vid malluppdateringar. Utvecklaren styr layouten, bilderna, knappadresserna och den övergripande strukturen. Om utvecklaren senare lägger till ett avsnitt med kundomdömen mellan “about” och “cta” visas det vid nästa synkronisering utan att störa kundens texter.

Blockbindningar: ett alternativ till nycklar

WordPress 6.5 introducerade BlockbindningarAPI, som kopplar blockattribut till inläggsmetadata. I stället för att lagra redigerbart innehåll i blockets markup (där nycklar skyddar det) lagras innehållet i wp_postmeta (där mallsynkroniseringar inte kan påverka det).

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>

Metanycklarna måste registreras i PHP:

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

Blockbindningar har två fördelar jämfört med nycklar: data kan efterfrågas med WP_Query via meta_query och är tillgänglig i REST API. Nackdelen är att du måste registrera varje metanyckel i PHP, och bindningar fungerar bara för enskilda blockattribut (inte komplext nästlat innehåll).

Använd nycklar för innehållsrika avsnitt där blockstrukturen spelar roll (en grupp med rubriker, stycken och bilder). Använd bindningar för enskilda textvärden som du också behöver efterfråga eller visa någon annanstans.

Inläggstypsmallar

Använd templateFor för att ange en standardstruktur för block för alla nya inlägg av en viss typ:

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>

Varje nytt inlägg av typen “product” börjar med den här strukturen. Med templateLock: "insert" kan redaktörer ordna om avsnitt och redigera innehåll, men inte lägga till eller ta bort block.

Tips

Synkronisera vid en avsiktlig driftsättningsgräns. Kör wp bs pages sync efter att sidkällor har ändrats eller driftsatts. Besök i frontend och admin synkroniserar aldrig sidor. PHP driftsättningsverktyg kan anropa Blockstudio\Pages::reconcile() och granska dess maskinläsbara rapport.

Lås viktiga inläggs-ID:n. Använd postId i page.json för sidor som hänvisas till från menyer, hårdkodade länkar eller externa system. Utan låsning får en sida som tas bort och återskapas ett nytt ID, vilket bryter dessa hänvisningar.

Använd sync: false för grundsidor. Om du vill skapa en sida en gång och sedan helt överlåta den till kunden anger du "sync": false och skapar den med Blockstudio\Pages::force_sync(). Vanlig avstämning ignorerar den därefter.

Lås och lås upp via PHP. Anropa Blockstudio\Pages::lock('about') för att förhindra synkronisering av en viss sida (användbart under intensiva redigeringsperioder för kunden). Anropa Blockstudio\Pages::unlock('about') för att återuppta synkroniseringen.

Mallmotorer. Förutom PHP kan mallar skrivas i Twig (kräver Timber) eller Blade (kräver illuminate/view). Det är användbart för loopar och filter, men sidmallar kompileras vid uttrycklig synkronisering, inte vid frontend-begäran. Håll dig till PHP om själva källkompileringen behöver enbart PHP-hjälpfunktioner.

Tvångssynkronisering ignorerar nycklar. Ett anrop till Pages::force_sync('about') ersätter hela sidinnehållet och ignorerar nycklar och kontroller av ändringstid. Använd det när du avsiktligt vill återställa en sida till mallens tillstånd.

Nästa steg

  • Sidor: referens: alla egenskaper för page.json, PHP API och algoritmen för sammanslagning med nycklar i detalj.
  • Översikt över sidor och mönster: parsern HTML, referens för blocksyntax, anpassade renderare och elementmappning.
  • Mönster: samma mallsyntax för återanvändbara blockmönster i stället för sidor.