Tworzenie stron na podstawie plików
Tradycyjne tworzenie stron WordPress odbywa się w edytorze bloków: przeciąganie bloków, konfigurowanie ustawień, klikanie przycisku zapisu. Sprawdza się to w przypadku klientów tworzących własne strony, ale stwarza problemy deweloperom budującym uporządkowane strony z kontrolą wersji. Układ strony znajduje się w bazie danych, a nie w kodzie. Nie można go sprawdzić w pull requeście, przywrócić za pomocą gita ani odtworzyć podczas nowej instalacji.
Strony oparte na plikach w Blockstudio rozwiązują ten problem. Definiujesz strony jako pliki w motywie, piszesz szablony HTML, które są przekształcane w bloki WordPress, i dokładnie określasz, co klienci mogą, a czego nie mogą edytować. Jawne polecenie synchronizuje te pliki ze zwykłymi wpisami WordPress, a źródłem prawdy pozostają szablony.
Ten przewodnik pokazuje, jak tworzyć strony od podstaw, koncentrując się szczegółowo na blokadach i ustawieniach edycji, dzięki którym strony oparte na plikach sprawdzają się w projektach dla klientów.
Twoja pierwsza strona
Utwórz folder pages w motywie, a następnie dodaj podfolder zawierający dwa pliki:
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>
Uruchom polecenie synchronizacji stron:
wp bs pages sync
Blockstudio analizuje HTML na bloki WordPress i tworzy stronę o nazwie
„O nas” z uproszczoną nazwą about. Otwórz ją w edytorze, a zobaczysz
nagłówek i akapit, dokładnie tak, jakby dodano je ręcznie.
Edytuj index.php, zmień tekst i ponownie uruchom polecenie. Odśwież edytor,
aby zobaczyć aktualizację. Tak wygląda główny cykl pracy: piszesz w HTML, celowo synchronizujesz, otrzymujesz bloki.
Język szablonów
Parser HTML w Blockstudio przekształca standardowe elementy HTML w bloki WordPress. Napisz <p>, a otrzymasz blok akapitu. Napisz <h2>, a otrzymasz blok nagłówka. Mapowanie jest intuicyjne:
| HTML | Blok |
|---|---|
<p> |
Akapit |
<h1> do <h6> |
Nagłówek (poziom odpowiada znacznikowi) |
<ul>, <ol> |
Lista |
<blockquote> |
Cytat |
<img> |
Obraz |
<div>, <section> |
Grupa |
<hr> |
Separator |
<details> |
Szczegóły |
<table> |
Tabela |
W przypadku bloków bez bezpośredniego odpowiednika HTML użyj elementu <block> z atrybutem name:
<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>
Atrybuty elementów <block> są przekazywane jako atrybuty bloku. Wartości są automatycznie konwertowane: "true" staje się wartością logiczną, "3" liczbą całkowitą, a ciągi JSON, takie jak '{"type":"flex"}', są dekodowane do obiektów.
Układy
Grupy obsługują różne tryby układu za pomocą atrybutu 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>
Własne bloki
Składnia <block> działa z każdym zarejestrowanym blokiem, w tym z własnymi blokami Blockstudio:
<block name="my-theme/hero" title="Welcome" background="dark" />
<block name="my-theme/testimonial" quote="Great product." author="Jane" />
Atrybuty są automatycznie mapowane na wartości pól Blockstudio bloku.
Tworzenie strony docelowej
Oto kompletna strona docelowa wykorzystująca podstawowe bloki do stworzenia struktury i układu:
{
"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>
Ta strona zawiera sekcję hero z okładką, siatkę funkcji w trzech kolumnach, sekcję z multimediami i tekstem, akordeony FAQ oraz CTA. Wszystko pochodzi z jednego pliku HTML. templateLock: "all" w page.json oznacza, że klient nie może niczego zmienić. W następnej sekcji wyjaśniono, jak poluzować to ograniczenie.
Kontrolowanie edytora
To właśnie tutaj strony oparte na plikach pokazują pełnię swoich możliwości. Blockstudio zapewnia dwie niezależne opcje: blokadę szablonu i tryb edycji bloków. Razem pozwalają dokładnie określić, które części strony klienci mogą modyfikować. Zablokuj strukturę, ale pozwól im edytować tekst. Zamroź niektóre sekcje, pozostawiając inne w pełni otwarte. Utwórz stronę, na której klient może jedynie wpisać tekst w trzy konkretne nagłówki.
Blokada szablonu
Właściwość templateLock w page.json steruje edycją struktury: tym, czy można dodawać, usuwać lub przestawiać bloki.
"all" (domyślnie)
{
"name": "terms",
"templateLock": "all"
}
Najbardziej restrykcyjna blokada. Klienci nie mogą dodawać, usuwać ani przenosić bloków. Nie mogą też edytować ich zawartości (chyba że połączysz tę opcję z blockEditingMode). Jest to ustawienie domyślne, jeśli nie podasz wartości.
Kiedy używać: strony prawne, regulaminy, polityki prywatności. Każda strona, której treść powinna zmieniać się wyłącznie za pomocą kodu.
"insert"
{
"name": "about",
"templateLock": "insert"
}
Klienci nie mogą dodawać ani usuwać bloków, ale mogą przestawiać istniejące bloki i edytować ich zawartość. Liczba bloków pozostaje stała, ale ich kolejność można zmieniać.
Kiedy używać: strony, na których chcesz zachować stały zestaw sekcji, ale umożliwić klientowi zmianę ich kolejności. Na przykład strona portfolio, na której liczba sekcji jest z góry ustalona, ale klient decyduje o ich kolejności.
"contentOnly"
{
"name": "homepage",
"templateLock": "contentOnly"
}
Klienci mogą edytować tekst, ale nie mogą dodawać, usuwać ani przenosić bloków. Różnica w porównaniu z "all" polega na tym, że "all" uniemożliwia także edycję treści, podczas gdy "contentOnly" wyraźnie na nią pozwala.
Kiedy używać: najczęstszy wybór w przypadku stron przeznaczonych dla klientów. Deweloper kontroluje układ, a klient uzupełnia tekst.
false
{
"name": "blog",
"templateLock": false
}
Brak blokady. Klienci mają pełną kontrolę: mogą dodawać, usuwać, przenosić i edytować dowolne bloki. Szablon zapewnia strukturę początkową, ale od tej chwili strona należy do klienta.
Kiedy używać: strony główne blogów, strony z treścią o dowolnym układzie lub każda strona, na której klient powinien mieć pełną swobodę redakcyjną.
Tryb edycji bloków
Podczas gdy templateLock kontroluje strukturę (dodawanie, usuwanie, przenoszenie), blockEditingMode określa sposób interakcji z poszczególnymi blokami: czy można je zaznaczać, konfigurować lub w ogóle edytować.
Ustaw domyślną opcję dla całej strony w page.json:
{
"name": "landing",
"templateLock": "all",
"blockEditingMode": "disabled"
}
"default"
Pełna edycja. Można zaznaczać bloki, zmieniać ich ustawienia i edytować treść. To standardowy sposób pracy w edytorze.
"contentOnly"
Bloki można edytować, ale tylko w zakresie ich tekstu. Nie można otwierać ustawień bloków, zmieniać kolorów, dostosowywać dopełnienia ani modyfikować atrybutów innych niż związane z treścią. Pasek narzędzi bloku pokazuje tylko opcje formatowania tekstu.
"disabled"
Bloki są całkowicie nieinteraktywne. Są wyświetlane w edytorze, ale nie można ich kliknąć, zaznaczyć ani w żaden sposób zmodyfikować. Klient widzi treść, ale nie może jej zmieniać.
Nadpisywanie ustawień poszczególnych elementów
W tym miejscu robi się ciekawie. Ustawienie blockEditingMode na poziomie strony określa wartość domyślną dla każdego bloku, ale możesz nadpisać je dla poszczególnych elementów szablonu:
{
"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>
Domyślne ustawienie strony to "disabled", więc każdy blok jest początkowo nieinteraktywny. Następnie wybrane elementy włączają "contentOnly", dzięki czemu można edytować tylko ich tekst. Rezultat: klient może wpisać tekst dokładnie w dwa pola tekstowe (nagłówek i akapit sekcji hero) oraz jeden akapit z funkcją. Wszystkie pozostałe elementy są zablokowane.
Działa to z każdym elementem HTML (<h1>, <p>, <div> itd.) oraz z elementami <block>. Możesz też ustawić blockEditingMode="default" dla wybranych elementów, aby zapewnić pełny dostęp do edycji:
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
Teraz klient może zmieniać tekst przycisku, URL, style i dowolne inne ustawienie. Cała pozostała zawartość strony pozostaje zamrożona.
Kaskadowanie ustawień na elementy nadrzędne
Warto pamiętać o tym, jak nadpisywanie ustawień poszczególnych elementów działa w połączeniu z blokami kontenerów. Jeśli domyślnym ustawieniem strony jest "disabled", a dla nagłówka w grupie ustawisz blockEditingMode="contentOnly", musisz mieć dostęp do tego nagłówka. Jego nadrzędna grupa ma jednak ustawienie "disabled", więc nie można jej w ogóle otworzyć.
Blockstudio obsługuje to automatycznie. Gdy blok podrzędny ma nadpisany tryb edycji, wszystkie jego bloki nadrzędne otrzymują ustawienie "contentOnly", dzięki czemu blok podrzędny pozostaje dostępny. Nie trzeba ręcznie ustawiać trybów dla nadrzędnych kontenerów. Wystarczy nadpisać ustawienie bloku, który ma być edytowalny, a ścieżka dostępu do niego zostanie otwarta.
<!-- 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>
Kaskadowanie ustawień na elementy nadrzędne podnosi poziom dostępności kontenerów tylko do "contentOnly", nigdy do "default". Oznacza to, że grupy nadrzędne można nawigować (można je otwierać), ale nie w pełni edytować (nie można zmieniać ich ustawień).
Macierz decyzji
Połączenie templateLock i blockEditingMode daje szeroki zakres kontroli. Oto najbardziej przydatne kombinacje:
Deweloper kontroluje wszystko
{ "templateLock": "all" }
Nie potrzeba blockEditingMode. Domyślne templateLock: "all" uniemożliwia wprowadzanie jakichkolwiek zmian. Użyj tego w przypadku stron zarządzanych wyłącznie za pomocą kodu.
Klient edytuje cały tekst
{ "templateLock": "contentOnly" }
Klient może edytować tekst w dowolnym bloku, ale nie może zmieniać struktury strony. Proste i elastyczne rozwiązanie.
Klient edytuje tylko wybrany tekst
{
"templateLock": "all",
"blockEditingMode": "disabled"
}
W połączeniu z blockEditingMode="contentOnly" ustawionym dla wybranych elementów szablonu. To najbardziej precyzyjna opcja: klient może edytować wyłącznie wskazane bloki.
Klient zmienia kolejność stałych sekcji
{ "templateLock": "insert" }
Klient może zmieniać kolejność sekcji i edytować treść, ale nie może dodawać ani usuwać bloków. Dobre rozwiązanie dla stron ze stałym zestawem sekcji, których kolejność można zmieniać.
Klient ma pełną kontrolę
{ "templateLock": false }
Szablon to punkt wyjścia. Klient może później zrobić wszystko.
Zachowywanie zmian klienta
Domyślnie po aktualizacji pliku szablonu Blockstudio zastępuje całą zawartość strony. Jeśli klient edytował nagłówek w edytorze, zmiana zniknie przy następnej synchronizacji. To dobre rozwiązanie w przypadku stron kontrolowanych przez dewelopera, ale gdy klienci dodają własną treść, potrzebujesz sposobu na zachowanie ich pracy.
Klucze
Dodaj atrybut key do dowolnego elementu, aby oznaczyć go do scalenia zamiast zastąpienia:
<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>
Gdy szablon się zmieni, a strona zostanie ponownie zsynchronizowana:
- Bloki z kluczami zachowują treść klienta (tekst, bloki wewnętrzne, formatowanie). Atrybuty strukturalne szablonu (takie jak
urlokładki) nadal są aktualizowane. - Bloki bez kluczy są w całości zastępowane wersją z szablonu.
Klucz chroni cały blok i wszystkie jego elementy podrzędne. Nie musisz przypisywać kluczy poszczególnym akapitom w grupie z kluczem. Klucz grupy obejmuje wszystko, co się w niej znajduje.
Klucze muszą być unikalne
Klucze muszą być unikalne w całym szablonie. Jeśli dwa elementy mają ten sam klucz, drugi jest traktowany tak, jakby go nie miał (i emitowane jest ostrzeżenie PHP). Używaj opisowych nazw: "hero", "features", "cta", "testimonial-section".
Rozwijanie szablonów
Klucze pozwalają dodawać do szablonu nowe sekcje bez naruszania istniejącej treści klienta:
<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>
Po synchronizacji tytuł i usługi zachowują zmiany klienta. Nowa sekcja z opiniami pojawia się z domyślną treścią szablonu. Jeśli później usuniesz blok z kluczem z szablonu, zostanie on usunięty ze strony.
Kompletny przepływ pracy klienta
Oto jak zastosować to wszystko w prawdziwym projekcie:
{
"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>
Ta strona ma cztery sekcje z kluczami. Klient może edytować nagłówki i akapity oznaczone przez blockEditingMode="contentOnly", a te zmiany są zachowywane podczas aktualizacji szablonu. Deweloper kontroluje układ, obrazy, adresy URL przycisków i ogólną strukturę. Jeśli później doda sekcję z opiniami między „about” a „cta”, pojawi się ona przy następnej synchronizacji, nie naruszając żadnego tekstu klienta.
Powiązania bloków: alternatywa dla kluczy
WordPress Wprowadzony w wersji 6.5 Wiązania bloków API łączą atrybuty bloków z metadanymi wpisu. Zamiast przechowywać edytowalną treść w znacznikach bloku (gdzie chronią ją klucze), treść znajduje się w wp_postmeta (gdzie synchronizacja szablonów nie może jej zmienić).
<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>
Klucze meta muszą być zarejestrowane w PHP:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Powiązania bloków mają dwie przewagi nad kluczami: dane można odpytywać za pomocą WP_Query przez meta_query, a także są dostępne w REST API. Kompromis polega na konieczności zarejestrowania każdego klucza meta w PHP; powiązania działają też tylko z pojedynczymi atrybutami bloków (nie ze złożoną, zagnieżdżoną treścią).
Używaj kluczy w sekcjach z rozbudowaną treścią, w których istotna jest struktura bloków (grupa z nagłówkami, akapitami i obrazami). Używaj powiązań dla pojedynczych wartości tekstowych, które chcesz też wyszukiwać lub wyświetlać w innych miejscach.
Szablony typów wpisów
Użyj templateFor, aby ustawić domyślną strukturę bloków dla wszystkich nowych wpisów danego typu:
{
"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>
Każdy nowy wpis typu „product” zaczyna się od tej struktury. templateLock: "insert" pozwala redaktorom zmieniać kolejność sekcji i edytować treść, ale nie dodawać ani usuwać bloków.
Wskazówki
Synchronizuj przy zaplanowanym wdrożeniu. Uruchom wp bs pages sync po
zmianie lub wdrożeniu źródeł stron. Wizyty na stronie głównej i w panelu administracyjnym nigdy nie synchronizują
stron. Narzędzia wdrożeniowe PHP mogą wywołać Blockstudio\Pages::reconcile() i
sprawdzić raport czytelny maszynowo.
Przypinaj ważne identyfikatory wpisów. Użyj postId w page.json dla stron, do których odwołują się menu, zakodowane na stałe linki lub systemy zewnętrzne. Bez przypięcia strona usunięta, a następnie utworzona ponownie, otrzyma nowy identyfikator, przez co takie odwołania przestaną działać.
Używaj sync: false do tworzenia szkieletów. Jeśli chcesz utworzyć stronę raz, a następnie
przekazać ją w całości klientowi, ustaw "sync": false i utwórz ją za pomocą
Blockstudio\Pages::force_sync(). Zwykłe uzgadnianie będzie ją wtedy pomijać.
Blokuj i odblokowuj za pomocą PHP. Wywołaj Blockstudio\Pages::lock('about'), aby wykluczyć konkretną stronę z synchronizacji (przydatne podczas intensywnej edycji przez klienta). Wywołaj Blockstudio\Pages::unlock('about'), aby ponownie włączyć synchronizację.
Silniki szablonów. Oprócz PHP szablony można zapisywać w Twig (wymaga Timber) lub Blade (wymaga illuminate/view). Przydaje się to w przypadku pętli i filtrów, ale szablony stron są kompilowane podczas jawnej synchronizacji, a nie w trakcie żądania do frontendu. Pozostań przy PHP, jeśli sama kompilacja źródła wymaga pomocników dostępnych wyłącznie w PHP.
Wymuszenie synchronizacji pomija klucze. Wywołanie Pages::force_sync('about') zastępuje całą zawartość strony, pomijając klucze i sprawdzanie czasu modyfikacji. Użyj go, gdy celowo chcesz przywrócić stronie stan z szablonu.
Następne kroki
- Dokumentacja Pages: szczegółowe omówienie wszystkich właściwości
page.json, PHP API oraz algorytmu scalania z użyciem kluczy. - Omówienie Pages i Patterns: parser HTML, dokumentacja składni bloków, własne renderery i mapowanie elementów.
- Patterns: ta sama składnia szablonów służąca do tworzenia wzorców bloków wielokrotnego użytku zamiast stron.