Создание страниц на основе файлов
Обычно страницы WordPress создают в редакторе блоков: перетаскивают блоки, настраивают параметры и нажимают «Сохранить». Это подходит клиентам, которые создают собственные страницы, но создает проблемы для разработчиков, создающих структурированные страницы с управлением версиями. Макет страницы хранится в базе данных, а не в коде. Его нельзя проверить в запросе на слияние, откатить с помощью git или воспроизвести при чистой установке.
Страницы на основе файлов в Blockstudio решают эту проблему. Определяйте страницы в виде файлов в теме, пишите шаблоны HTML, преобразуемые в блоки WordPress, и точно задавайте, что клиенты могут и не могут редактировать. Специальная команда синхронизирует эти файлы с обычными записями WordPress, а источником истины остаются ваши шаблоны.
В этом руководстве показано, как создавать страницы с нуля. Особое внимание уделено блокировке и настройкам редактирования, благодаря которым страницы на основе файлов удобны для клиентских проектов.
Первая страница
Создайте в теме папку pages, затем добавьте в нее подпапку с двумя файлами:
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>
Запустите команду синхронизации страниц:
wp bs pages sync
Blockstudio разбирает HTML на блоки WordPress и создает страницу под названием
«О нас» со слагом 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:
<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:
<!-- 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:
<block name="my-theme/hero" title="Welcome" background="dark" />
<block name="my-theme/testimonial" quote="Great product." author="Jane" />
Атрибуты автоматически сопоставляются со значениями полей Blockstudio блока.
Создание целевой страницы
Вот готовая целевая страница, в которой базовые блоки используются для структуры и макета:
{
"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>
На этой странице есть обложка с главным блоком, сетка преимуществ из трех столбцов, раздел с медиа и текстом, раскрывающиеся блоки часто задаваемых вопросов и призыв к действию. Все содержимое собрано в одном файле HTML. Значение templateLock: "all" в page.json запрещает клиенту что-либо менять. В следующем разделе объясняется, как ослабить это ограничение.
Управление редактором
Именно здесь файловые страницы раскрывают свой потенциал. Blockstudio предоставляет два независимых способа управления: блокировку шаблона и режим редактирования блоков. Вместе они позволяют точно определить, какие части страницы могут изменять клиенты. Заблокируйте структуру, но разрешите редактировать текст. Зафиксируйте одни разделы, оставив другие полностью открытыми. Создайте страницу, на которой клиент сможет вводить текст только в три указанных заголовка.
Блокировка шаблона
Свойство templateLock в page.json управляет структурным редактированием: можно ли добавлять, удалять и перемещать блоки.
"all" (по умолчанию)
{
"name": "terms",
"templateLock": "all"
}
Самая строгая блокировка. Клиенты не могут добавлять, удалять и перемещать блоки. Они также не могут редактировать содержимое блоков (если это не сочетается с blockEditingMode). Это значение используется по умолчанию, если указать его явно.
Когда использовать: юридические страницы, условия использования, политики конфиденциальности. Любые страницы, содержимое которых должно меняться только через код.
"insert"
{
"name": "about",
"templateLock": "insert"
}
Клиенты не могут добавлять и удалять блоки, но могут перемещать существующие блоки и редактировать их содержимое. Число блоков остается неизменным, но их порядок можно менять.
Когда использовать: страницы с фиксированным набором разделов, порядок которых клиент может менять. Например, страница портфолио с заранее заданным числом разделов, порядок которых выбирает клиент.
"contentOnly"
{
"name": "homepage",
"templateLock": "contentOnly"
}
Клиенты могут редактировать текст, но не могут добавлять, удалять и перемещать блоки. Отличие от "all" в том, что "all" также запрещает редактировать содержимое, а "contentOnly" явно разрешает это.
Когда использовать: самый распространенный вариант для страниц, предназначенных клиентам. Разработчик управляет макетом, клиент заполняет текст.
false
{
"name": "blog",
"templateLock": false
}
Без блокировки. Клиенты полностью контролируют страницу: могут добавлять, удалять и перемещать любые блоки, а также редактировать их. Шаблон задает начальную структуру, а дальше клиент распоряжается страницей сам.
Когда использовать: страницы со списком записей блога, страницы со свободной компоновкой или любые страницы, где клиенту нужна полная редакторская свобода.
Режим редактирования блоков
Если templateLock управляет структурой (добавлением, удалением и перемещением), то blockEditingMode управляет взаимодействием с отдельными блоками: можно ли вообще выбирать, настраивать и редактировать их.
Задайте значение по умолчанию для всей страницы в page.json:
{
"name": "landing",
"templateLock": "all",
"blockEditingMode": "disabled"
}
"default"
Полное редактирование. Блоки можно выбирать, менять их настройки и редактировать содержимое. Это обычный режим работы редактора.
"contentOnly"
Блоки доступны для редактирования, но только в части текста. Нельзя открыть настройки блока, изменить цвета, отступы или другие атрибуты, не относящиеся к содержимому. На панели блока доступны только параметры форматирования текста.
"disabled"
Блоки полностью недоступны для взаимодействия. Они отображаются в редакторе, но их нельзя нажимать, выбирать и изменять. Клиент видит содержимое, но не может его трогать.
Переопределение для отдельных элементов
Вот здесь начинается самое интересное. Параметр blockEditingMode для страницы задает значение по умолчанию для каждого блока, но его можно переопределить для отдельных элементов шаблона:
{
"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>
Значение по умолчанию для страницы — "disabled", поэтому все блоки изначально недоступны для взаимодействия. Затем для отдельных элементов включается "contentOnly", чтобы можно было редактировать только их текст. В результате клиент может вводить текст ровно в двух текстовых полях (заголовке и абзаце главного экрана) и одном абзаце с описанием функции. Все остальное заблокировано.
Это работает с любыми элементами HTML (<h1>, <p>, <div> и т. д.) и элементами <block>. Для отдельных элементов также можно задать blockEditingMode="default", чтобы разрешить полное редактирование:
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
Теперь клиент может изменить текст кнопки, URL, стили и любые другие параметры. Все остальное на странице останется зафиксированным.
Наследование для родительских блоков
Важно учитывать, как переопределения для отдельных элементов взаимодействуют с блоками-контейнерами. Если для страницы задано значение по умолчанию "disabled" и вы задаете blockEditingMode="contentOnly" заголовку внутри группы, до этого заголовка нужно иметь возможность добраться. Но родительская группа находится в режиме "disabled", то есть открыть ее нельзя.
Blockstudio решает эту проблему автоматически. Если для дочернего блока переопределен режим редактирования, для всех его родительских блоков устанавливается "contentOnly", чтобы дочерний блок оставался доступным. Вручную задавать режимы для родительских контейнеров не нужно. Просто переопределите режим для блока, который хотите сделать доступным для редактирования, — путь к нему откроется.
<!-- 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 позволяет выбрать нужный уровень контроля. Вот самые полезные сочетания:
Разработчик контролирует все
{ "templateLock": "all" }
blockEditingMode не требуется. Значение templateLock: "all" по умолчанию запрещает любые изменения. Используйте его для страниц, которыми управляют только через код.
Клиент редактирует весь текст
{ "templateLock": "contentOnly" }
Клиент может редактировать текст в любом блоке, но не может менять структуру страницы. Простой и гибкий вариант.
Клиент редактирует только указанный текст
{
"templateLock": "all",
"blockEditingMode": "disabled"
}
Сочетайте с blockEditingMode="contentOnly" для отдельных элементов шаблона. Это самый точный вариант: клиент может редактировать только те блоки, которые вы отметили.
Клиент меняет порядок фиксированных разделов
{ "templateLock": "insert" }
Клиент может менять порядок разделов и редактировать содержимое, но не может добавлять и удалять блоки. Подходит для страниц с фиксированным набором разделов, порядок которых можно менять.
Клиент полностью контролирует страницу
{ "templateLock": false }
Шаблон задает начальную структуру. Дальше клиент может делать что угодно.
Сохранение изменений клиента
По умолчанию при обновлении файла шаблона Blockstudio заменяет все содержимое страницы. Если клиент отредактировал заголовок в редакторе, при следующей синхронизации это изменение пропадет. Для страниц, которыми управляет разработчик, это нормально. Но если клиент добавляет на страницу свое содержимое, нужно сохранять его работу.
Ключи
Добавьте к любому элементу атрибут key, чтобы при синхронизации объединять его содержимое, а не заменять:
<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".
Развитие шаблонов
Ключи позволяют добавлять в шаблон новые разделы, не затрагивая существующее содержимое клиента:
<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>
При синхронизации заголовок и описание услуг сохраняют изменения клиента. Новый раздел с отзывами появляется с содержимым по умолчанию из шаблона. Если позже удалить блок с ключом из шаблона, он также удалится со страницы.
Полный рабочий процесс для клиента
Рассмотрим все это на примере реального проекта:
{
"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>
На этой странице четыре раздела с ключами. Клиент может редактировать заголовки и абзацы, отмеченные blockEditingMode="contentOnly", и эти изменения сохраняются при обновлении шаблона. Разработчик управляет макетом, изображениями, URL-адресами кнопок и общей структурой. Если разработчик позже добавит раздел с отзывами между разделами «о нас» и «призыв к действию», он появится при следующей синхронизации и не затронет текст клиента.
Привязки блоков: альтернатива ключам
В версии WordPress 6.5 появилась функция Привязки блоковAPI, связывающая атрибуты блоков с метаданными записи. Вместо того чтобы хранить редактируемое содержимое в разметке блока (где его защищают ключи), содержимое хранится в wp_postmeta (где синхронизация шаблона не может его затронуть).
<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:
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, чтобы задавать структуру блоков по умолчанию для всех новых записей определенного типа:
{
"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>
Каждая новая запись типа «product» начинается с этой структуры. Параметр templateLock: "insert" позволяет редакторам менять порядок разделов и редактировать содержимое, но не добавлять и не удалять блоки.
Советы
Синхронизируйте на заранее выбранном этапе развертывания. Запускайте wp bs pages sync после изменения или развертывания исходников страниц. Посещение сайта или админки не запускает синхронизацию страниц. PHP инструменты развертывания могут вызывать Blockstudio\Pages::reconcile() и анализировать его машиночитаемый отчет.
Закрепляйте важные идентификаторы записей. Используйте postId в page.json для страниц, на которые ссылаются меню, жестко заданные ссылки или внешние системы. Без закрепления удаленная и созданная заново страница получит новый идентификатор, и эти ссылки перестанут работать.
Используйте 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, справочник по синтаксису блоков, пользовательские средства рендеринга и сопоставление элементов.
- Паттерны: тот же синтаксис шаблонов для повторно используемых паттернов блоков вместо страниц.