Към съдържанието

Създаване на страници от файлове

Традиционното създаване на страници 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, след което създава страница, наречена „За нас“, със slug 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>

Тази страница съдържа hero секция тип корица, мрежа с характеристики в три колони, секция с медия и текст, разгъващи се FAQ елементи и 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 адресите на бутоните и цялостната структура. Ако по-късно разработчикът добави секция с отзиви между „about“ и „cta“, тя ще се появи при следващата синхронизация, без да засегне текста на клиента.

Свързвания на блокове: алтернатива на ключовете

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() и да проверят машинночетимия отчет.

Фиксирайте важните идентификатори на публикации. Използвайте 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') заменя цялото съдържание на страницата, като игнорира ключовете и проверките на времето на промяна. Използвайте го, когато умишлено искате да върнете страницата към състоянието от шаблона.

Следващи стъпки

  • Справочник за Pages: подробности за всички свойства на page.json, PHP API и алгоритъма за обединяване с ключове.
  • Преглед на Pages & Patterns: парсерът HTML, справочник за синтаксиса на блоковете, персонализирани визуализатори и съпоставяне на елементи.
  • Patterns: същият синтаксис на шаблони за модели от блокове за повторна употреба вместо страници.