Перейти до вмісту

Створення сторінок на основі файлів

Традиційно сторінки WordPress створюють у редакторі блоків: перетягують блоки, налаштовують параметри, натискають кнопку збереження. Це підходить клієнтам, які створюють власні сторінки, але створює проблеми для розробників, що працюють зі структурованими сторінками під контролем версій. Макет сторінки зберігається в базі даних, а не в коді. Його не можна переглянути в запиті на злиття, відкотити за допомогою git чи відтворити під час нового встановлення.

Сторінки на основі файлів у Blockstudio розв’язують цю проблему. Ви визначаєте сторінки як файли у своїй темі, пишете шаблони HTML, які перетворюються на блоки WordPress, і точно контролюєте, що клієнти можуть і не можуть редагувати. Окрема команда синхронізує ці файли зі звичайними записами WordPress, а ваші шаблони залишаються єдиним джерелом правди.

У цьому посібнику описано створення сторінок з нуля з докладним розглядом блокування та засобів керування редагуванням, які роблять сторінки на основі файлів зручними для клієнтських проєктів.

Перша сторінка

Створіть у темі папку pages, а в ній — вкладену папку з двома файлами:

Код
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>

Запустіть команду синхронізації сторінок:

Командна оболонка
wp bs pages sync

Blockstudio розбирає HTML на блоки WordPress і створює сторінку з назвою “About Us” та частиною URL about. Відкрийте її в редакторі — побачите заголовок і абзац, наче додали їх вручну.

Відредагуйте index.php, змініть текст і знову запустіть команду. Перезавантажте редактор, щоб побачити зміни. Це основний цикл: пишіть HTML, запускайте синхронізацію за потреби й отримуйте блоки.

Мова шаблонів

Парсер HTML у Blockstudio перетворює стандартні елементи HTML на блоки WordPress. Напишіть <p> — отримаєте блок абзацу. Напишіть <h2> — отримаєте блок заголовка. Відповідність інтуїтивно зрозуміла:

HTML Блок
<p> Абзац
<h1> через <h6> Заголовок (рівень відповідає тегу)
<ul>, <ol> Список
<blockquote> Цитата
<img> Зображення
<div>, <section> Група
<hr> Роздільник
<details> Деталі
<table> Таблиця

Для блоків без прямого відповідника HTML використовуйте елемент <block> з атрибутом 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>

Атрибути елементів <block> передаються як атрибути блоку. Значення автоматично перетворюються: "true" стає логічним значенням, "3" — цілим числом, а рядки JSON на кшталт '{"type":"flex"}' декодуються в об’єкти.

Макети

Групи підтримують різні режими макета через атрибут 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>

Власні блоки

Синтаксис <block> працює з будь-яким зареєстрованим блоком, зокрема з вашими власними блоками Blockstudio:

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

Атрибути автоматично зіставляються зі значеннями полів Blockstudio блоку.

Створення цільової сторінки

Ось повна цільова сторінка, у якій для структури й макета використано базові блоки:

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>

Ця сторінка містить головний блок обкладинки, сітку функцій у три стовпці, секцію з медіа та текстом, розгортані блоки поширених запитань і CTA. Усе це міститься в одному файлі HTML. templateLock: "all" у page.json означає, що клієнт не може нічого змінити. У наступному розділі пояснюється, як послабити це обмеження.

Керування редактором

Саме тут сторінки на основі файлів розкривають свій потенціал. Blockstudio надає два незалежні засоби керування: блокування шаблону та режим редагування блоків. Разом вони дають змогу точно визначити, які частини сторінки можуть змінювати клієнти. Заблокуйте структуру, але дозвольте редагувати текст. Заморозьте одні розділи, залишивши інші повністю доступними для редагування. Створіть сторінку, де клієнт зможе лише вводити текст у три визначені заголовки.

Блокування шаблону

Властивість templateLock у page.json керує редагуванням структури: можливістю додавати, видаляти або переміщувати блоки.

"all" (за замовчуванням)

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

Найсуворіше блокування. Клієнти не можуть додавати, видаляти чи переміщувати блоки. Вони також не можуть редагувати вміст блоків (якщо не поєднати це з blockEditingMode). Це значення використовується за замовчуванням, якщо не вказати інше.

Коли використовувати: сторінки з юридичною інформацією, умовами обслуговування та політиками конфіденційності. Будь-які сторінки, вміст яких має змінюватися лише через код.

"insert"

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

Клієнти не можуть додавати чи видаляти блоки, але можуть переміщувати наявні та редагувати їхній вміст. Кількість блоків залишається незмінною, але їхній порядок можна змінювати.

Коли використовувати: сторінки з фіксованим набором розділів, порядок яких клієнт може змінювати. Наприклад, сторінка портфоліо з наперед визначеною кількістю розділів, порядок яких клієнт обирає сам.

"contentOnly"

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

Клієнти можуть редагувати текст, але не можуть додавати, видаляти чи переміщувати блоки. Відмінність від "all" полягає в тому, що "all" також забороняє редагувати вміст, а "contentOnly" явно це дозволяє.

Коли використовувати: найпоширеніший варіант для сторінок, призначених клієнтам. Розробник керує макетом, а клієнт заповнює текст.

false

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

Без блокувань. Клієнти мають повний контроль: можуть додавати, видаляти й переміщувати блоки, а також редагувати будь-який блок. Шаблон задає початкову структуру, але далі клієнт розпоряджається нею сам.

Коли використовувати: сторінки індексу блогу, сторінки з довільним вмістом або будь-які сторінки, де клієнт має повну свободу редагування.

Режим редагування блоків

Якщо templateLock керує структурою (додаванням, видаленням і переміщенням), то blockEditingMode визначає взаємодію з окремими блоками: чи можна їх вибирати, налаштовувати та взагалі редагувати.

Установіть значення за замовчуванням для всієї сторінки в page.json:

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

"default"

Повне редагування. Блоки можна вибирати, змінювати їхні налаштування та редагувати вміст. Це звичний режим роботи редактора.

"contentOnly"

Блоки можна редагувати, але лише їхній текст. Не можна відкривати налаштування блоків, змінювати кольори, відступи чи будь-які атрибути, не пов’язані з вмістом. На панелі інструментів блока відображаються лише параметри форматування тексту.

"disabled"

Блоки повністю недоступні для взаємодії. Вони відображаються в редакторі, але їх не можна натиснути, вибрати чи змінити. Клієнт бачить вміст, але не може його редагувати.

Перевизначення для окремих елементів

Тут починається найцікавіше. Параметр blockEditingMode для сторінки задає значення за замовчуванням для кожного блока, але для окремих елементів шаблону можна встановити інші значення:

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>

За замовчуванням для сторінки встановлено "disabled", тому всі блоки спочатку недоступні для взаємодії. Потім для окремих елементів можна ввімкнути "contentOnly", щоб дозволити редагування лише їхнього тексту. У результаті клієнт зможе вводити текст рівно у два текстові поля (заголовок і абзац першого екрана) та один абзац із описом функції. Решта вмісту буде заблокована.

Це працює з будь-яким елементом HTML (<h1>, <p>, <div> тощо) і з елементами <block>. Також для окремих елементів можна встановити blockEditingMode="default", щоб надати повний доступ до редагування:

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

Тепер клієнт може змінювати текст кнопки, URL, стилі та будь-які інші параметри. Решта сторінки залишиться незмінною.

Каскад від предків

Є важлива деталь щодо взаємодії перевизначень для окремих елементів із блоками-контейнерами. Якщо для сторінки за замовчуванням установлено "disabled", а для заголовка всередині групи — blockEditingMode="contentOnly", цей заголовок має бути доступним. Але його батьківська група має значення "disabled", а це означає, що перейти всередину не можна.

Blockstudio вирішує це автоматично. Коли для дочірнього блока перевизначено режим редагування, для всіх його блоків-предків установлюється "contentOnly", щоб дочірній блок залишався доступним. Не потрібно вручну задавати режими для батьківських контейнерів. Просто встановіть перевизначення для блока, який має бути доступним для редагування, і шлях до нього відкриється.

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>

Каскад від предків підвищує доступність контейнерів лише до "contentOnly", але ніколи до "default". Це означає, що до батьківських груп можна перейти (увійти в них), але їх не можна повністю редагувати (змінювати їхні налаштування).

Матриця рішень

Комбінування templateLock і blockEditingMode дає змогу налаштувати потрібний рівень контролю. Ось найкорисніші комбінації:

Розробник контролює все

JSON
{ "templateLock": "all" }

blockEditingMode не потрібен. Значення templateLock: "all" за замовчуванням забороняє будь-які зміни. Використовуйте його для сторінок, якими повністю керують через код.

Клієнт редагує весь текст

JSON
{ "templateLock": "contentOnly" }

Клієнт може редагувати текст у будь-якому блоці, але не може змінювати структуру сторінки. Просто й зручно.

Клієнт редагує лише визначений текст

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

Поєднайте з blockEditingMode="contentOnly" для окремих елементів шаблону. Це найточніший варіант: клієнт може редагувати лише ті блоки, які ви позначили.

Клієнт змінює порядок фіксованих розділів

JSON
{ "templateLock": "insert" }

Клієнт може змінювати порядок розділів і редагувати вміст, але не може додавати чи видаляти блоки. Підходить для сторінок із фіксованим набором розділів, порядок яких можна змінювати.

Клієнт має повний контроль

JSON
{ "templateLock": false }

Шаблон задає початкову структуру. Далі клієнт може робити все, що завгодно.

Як зберегти зміни клієнта

За замовчуванням під час оновлення файлу шаблону Blockstudio замінює весь вміст сторінки. Якщо клієнт відредагував заголовок у редакторі, після наступної синхронізації ця зміна зникне. Для сторінок, якими керує розробник, це нормально, але якщо клієнти додають вміст, потрібно зберігати їхні зміни.

Ключі

Додайте атрибут key до будь-якого елемента, щоб позначити його для об’єднання замість заміни:

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>

Коли шаблон зміниться й сторінка синхронізується повторно:

  • Блоки з ключами зберігають вміст клієнта (текст, внутрішні блоки, форматування). Структурні атрибути шаблону (наприклад, url обкладинки) усе одно оновлюються.
  • Блоки без ключів повністю замінюються відповідною версією з шаблону.

Ключ захищає весь блок і всіх його дочірніх елементів. Не потрібно призначати ключ кожному абзацу всередині групи з ключем. Ключ групи охоплює весь її вміст.

Ключі мають бути унікальними

Ключі мають бути унікальними в межах усього шаблону. Якщо два елементи мають однаковий ключ, другий вважається елементом без ключа (і виводиться попередження PHP). Використовуйте описові назви: "hero", "features", "cta", "testimonial-section".

Розвиток шаблонів

Ключі дають змогу додавати до шаблону нові розділи, не зачіпаючи наявний вміст клієнта:

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>

Після синхронізації заголовок і послуги збережуть зміни клієнта. Новий розділ із відгуками з’явиться зі вмістом шаблону за замовчуванням. Якщо згодом видалити блок із ключем із шаблону, його буде видалено зі сторінки.

Повний робочий процес для клієнта

Ось як застосувати все це в реальному проєкті:

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>

Ця сторінка має чотири розділи з ключами. Клієнт може редагувати заголовки й абзаци, позначені blockEditingMode="contentOnly", і ці зміни зберігатимуться після оновлення шаблону. Розробник контролює макет, зображення, URL-адреси кнопок і загальну структуру. Якщо згодом розробник додасть розділ із відгуками між «про нас» і «заклик до дії», він з’явиться після наступної синхронізації, не зачіпаючи текст клієнта.

Прив’язки блоків: альтернатива ключам

У версії WordPress 6.5 з’явився Прив’язки блоківAPI, які пов’язують атрибути блоків із метаданими допису. Замість зберігання вмісту для редагування в розмітці блока (де його захищають ключі), вміст зберігається в wp_postmeta (де синхронізація шаблону не може його змінити).

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>

Метаключі потрібно зареєструвати в PHP:

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

Прив’язки блоків мають дві переваги перед ключами: дані можна запитувати за допомогою WP_Query через meta_query, і вони доступні в REST API. Компроміс полягає в тому, що кожен метаключ потрібно зареєструвати в PHP, а прив’язки працюють лише з окремими атрибутами блоків (не зі складним вкладеним вмістом).

Використовуйте ключі для розділів із форматованим вмістом, де важлива структура блоків (група із заголовками, абзацами та зображеннями). Прив’язки використовуйте для окремих текстових значень, які також потрібно запитувати або відображати в інших місцях.

Шаблони типів записів

Використовуйте templateFor, щоб задати структуру блоків за замовчуванням для всіх нових дописів певного типу:

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>

Кожен новий допис типу «product» матиме цю структуру. templateLock: "insert" дозволяє редакторам змінювати порядок розділів і редагувати вміст, але не додавати чи видаляти блоки.

Поради

Синхронізуйте під час запланованого розгортання. Запускайте wp bs pages sync після зміни або розгортання джерел сторінок. Відвідування фронтенду й адмінпанелі не синхронізують сторінки. Інструменти розгортання PHP можуть викликати Blockstudio\Pages::reconcile() й перевіряти його машиночитний звіт.

Закріплюйте важливі ID дописів. Використовуйте postId у page.json для сторінок, на які посилаються меню, жорстко прописані посилання чи зовнішні системи. Без закріплення сторінка після видалення й повторного створення отримає новий ID, і ці посилання перестануть працювати.

Використовуйте sync: false для заготовок. Якщо ви хочете створити сторінку один раз, а потім повністю передати її клієнту, установіть "sync": false і створіть її за допомогою Blockstudio\Pages::force_sync(). Під час звичайної звірки вона ігноруватиметься.

Блокуйте й розблоковуйте через PHP. Викликайте Blockstudio\Pages::lock('about'), щоб заборонити синхронізацію певної сторінки (це корисно під час періодів активного редагування клієнтом). Викликайте Blockstudio\Pages::unlock('about'), щоб відновити синхронізацію.

Системи шаблонів. Окрім PHP, шаблони можна писати на Twig (потрібні Timber) або Blade (потрібні illuminate/view). Це корисно для циклів і фільтрів, але шаблони сторінок компілюються під час явної синхронізації, а не під час запиту до фронтенду. Використовуйте PHP, якщо для компіляції вихідного коду потрібні допоміжні засоби лише для PHP.

Примусова синхронізація ігнорує ключі. Виклик Pages::force_sync('about') замінює весь вміст сторінки, ігноруючи ключі й перевірки часу зміни. Використовуйте його, коли потрібно повернути сторінку до стану шаблону.

Наступні кроки

  • Довідник сторінок: докладний опис усіх властивостей page.json, PHP API та алгоритму об’єднання за ключами.
  • Огляд сторінок і патернів: парсер HTML, довідник синтаксису блоків, власні засоби рендерингу та зіставлення елементів.
  • Патерни: той самий синтаксис шаблонів для повторно використовуваних патернів блоків замість сторінок.