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

Програмно изобразяване

Тъй като Gutenberg се превръща във водещ инструмент за създаване на лесни за редактиране уебсайтове за клиенти, има смисъл всички необходими области на сайта да бъдат оформени като блокове. Този подход ще покрие нуждите на повечето потребители, но напредналите потребители и специфичните случаи може да изискват използването на тези блокове извън редактора.

Blockstudio предлага два подхода за програмно изобразяване на блокове:

  • Функции PHP: bs_render_block и bs_block за изобразяване от код PHP
  • Тагове HTML: тагове <bs:block-name>, които се заменят с изхода на блока навсякъде в страницата

Поддържат се всички специфични за Blockstudio функции, като вградени стилове, скриптове и ограничени до блока стилове.

Островите работят и при тези начини на изобразяване. Динамичен остров, изобразен с bs_render_block(), bs_block() или таг за блок, връща същия маркер за контейнер като блок, изобразен от съдържанието на публикацията. Средата за изпълнение на фронтенда се инжектира, когато този маркер присъства в отговора.

Структурирани композиции и пълни документи

За инструменти с дълъг жизнен цикъл, визуализации, експортиране и галерии на компоненти използвайте версионирания Blockstudio\Render API. Той приема една декларация или подреден списък и изобразява резултата, без да го извежда:

PHP
use Blockstudio\Render;

$composition = [
  'root' => 'theme/card',
  'example' => [
    'data' => [
      'heading' => 'Example card',
    ],
    'layers' => [
      [
        'name' => 'theme/button',
        'data' => [
          'label' => 'Continue',
        ],
      ],
    ],
  ],
];

$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
  'title' => 'Component preview',
  'contentElement' => 'main',
  'contentClasses' => ['component-preview'],
]);

Нормализираната канонична декларация съдържа четири ключа:

PHP
[
  'name' => 'theme/card',
  'attributes' => [],
  'content' => '',
  'children' => [],
]

data, inner, innerBlocks, root, layers и example улесняват въвеждането и се премахват при нормализацията. Вложените декларации се изобразяват рекурсивно чрез същия конвейер Blockstudio.

Render::document() връща schemaVersion, html, body, blocks, assets, warnings и errors. Стойността assets разделя head, footer, styles, scripts, modules, interactivity, ui и tailwind. Списъкът с блокове и ресурсите включват зависимостите, посочени от избраните шаблони, но изключват несвързаните ресурси и тези само за редактора.

Пълните документи могат да задават bodyClasses/bodyAttributes и по избор да обгръщат изобразеното тяло с contentElement, contentClasses и contentAttributes. Обвивката е ограничена до безопасно име на елемент; върнатото body остава неизобразеното съдържание без обвивката. Опциите head и footer добавят доверена маркировка на документа на съответните си места и се включват в набора от върнати ресурси.

За да съставите документ около вече изобразен HTML, подайте известните имена на коренните блокове:

PHP
$document = Render::document_from_html(
  $rendered_html,
  ['theme/hero', 'theme/button'],
  ['title' => 'Homepage preview']
);

Използвайте Render::content() за сериализирано съдържание на блокове WordPress. Клиентите, които изобразяват няколко независими документа в една заявка, трябва да извикват Blockstudio\Batch_Render::reset() между тях; Canvas::documents() прави това автоматично.

Рендиране извън страницата

Blockstudio поставя коментар <!--blockstudio/namespace/slug--> преди всеки блок, който рендира. На страница във фронтенда буферът прочита тези коментари, за да види кои блокове присъстват, зарежда техните ресурси и премахва коментарите, преди да изпрати отговора.

В изхода, който не минава през този буфер, коментарите остават. Това важи за отговорите REST, емисиите, AJAX обработчиците и HTML, които съхранявате или изпращате другаде след do_blocks(), Render::content() или bs_render_block(). Използвайте bs_strip_render_markers(), за да ги премахнете:

PHP
$html = bs_strip_render_markers(do_blocks($post->post_content));

Функцията премахва коментарите на регистрираните блокове Blockstudio и оставя всичко останало непокътнато, включително другите коментари HTML. Тя разпознава същите маркери, които премахва буферът на страницата. Извикайте я след регистрацията на блоковете (init или по-късно).

Не премахвайте маркировка, която все още се отпечатва в буферирана страница във фронтенда. На страницата са нужни коментарите, за да разбере кои ресурси на блокове да зареди, а Blockstudio ги премахва накрая.

Премахването на коментарите не добавя ресурси. Файловете CSS и JavaScript на блоковете се вмъкват само от буфера на страницата. Използвайте bs_block_assets() или Render::document(), когато и потребителят им има нужда от тях.

Проверка на блокове

Използвайте bs_block_fields() след регистрацията на блоковете (на init или по-късно), за да получите разрешените дефиниции на полетата, без да четете вътрешните регистри:

PHP
$fields = bs_block_fields('theme/card');

if ($fields === null) {
  // Unknown block, or not a Blockstudio block.
}

Върнатата стойност е регистрираният масив от дефиниции на полета, включително филтри за атрибути, разширени потребителски полета, замествания и вложени групи, раздели и повтарящи се групи. Блок Blockstudio без полета връща []. Резултатът е копие: промяната му не променя регистрирания блок.

Това са дефиниции, а не запазени стойности. За да валидирате запазена маркировка, използвайте bs_validate_block() вместо да поддържате отделен обход на полетата. За да опишете стойностите, които блокът приема, използвайте bs_block_schema(). Атрибутите, притежавани от WordPress, остават отделни.

Полетата, добавени от разширения, не са част от bs_block_fields(). Използвайте bs_block_extension_fields(), за да ги получите. Тя съпоставя разширенията по име на блок, така че работи и с основните блокове, и с блокове на трети страни:

PHP
$fields = array_merge(
  bs_block_fields('core/paragraph') ?? [],
  bs_block_extension_fields('core/paragraph')
);

Върнатата стойност изброява дефинициите на полета на всяко съвпадащо разширение в реда, в който са регистрирани разширенията, със същата структура като bs_block_fields(). За блок, с който не съвпада нито едно разширение, се връща []. Стойностите на разширенията се запазват в същия обект attrs.blockstudio.attributes като стойностите на собствените полета на блока, така че всички ID-та споделят едно пространство от имена. Ако две разширения дефинират едно и също ID, се връщат и двете дефиниции и променят една и съща стойност; при рендиране се прилага дефиницията на разширението, регистрирано по-късно.

За да прочетете стойностите на запазен блок така, както ги получава неговият шаблон, използвайте bs_block_values().

Използвайте bs_block_assets(), за да проверите откритите CSS и JavaScript на блока. За пълен документ за визуализация, включително вложени блокове и споделени зависимости по време на изпълнение, използвайте Render::document(), както е описано по-горе.

Валидиране на запазените стойности

Използвайте bs_validate_block() след регистрацията на блоковете (init или по-късно), за да проверите програмно генерирани или импортирани атрибути на блокове, преди да ги запазите:

PHP
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);

if ($findings === null) {
  // No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
  // No stored-value problems were found.
} else {
  // Review the findings before saving.
}

Подайте целия масив attrs, а не само blockstudio.attributes. Рендиране на Blockstudio приема и декларирани полета на най-горно ниво, а когато са подадени и двата вида, вложените стойности имат предимство. Разширенията на основни блокове и блокове на трети страни четат само blockstudio.attributes. Празен блок Blockstudio е управляван и връща [], а не null.

Валидирането се изпълнява изрично и е само за четене. То не рендира шаблони, не променя стойности, не запазва публикации, не прави заявки за медийни файлове и не изпълнява обратни извиквания за попълване. Не се изпълнява автоматично при запазване, синхронизиране на страници или рендиране. То не е средство за дезинфекция, проверка на оторизация или проверка дали даден прикачен файл съществува.

Всяка констатация съдържа следните неизменни ключове:

PHP
[
  'code' => 'unknown_option',
  'path' => 'steps/1/style',
  'source' => 'block',
  'message' => 'This value is not among the field options.',
  'value' => 'c',
  'expected' => ['a', 'b'],
]

Използвайте code, а не преведения message, в инструментите. source е block или extension. Пътищата използват ключове за съхранение и индекси на редове или избори в повторителите, започващи от нула, без водеща наклонена черта. Буквалните ~ и / в ключ се екранират като ~0 и ~1. Група от най-горно ниво добавя префикс към дъщерните си елементи (cta_title); анонимните групи и разделите не добавят ниво. Групи с ID в друга група или повторител не се поддържат от конструктора, затова ключовете им не се приемат. Полетата за съобщения нямат съхранена стойност. Поле за файлове допуска придружаващото си <id>__size. В основата на блок Blockstudio ключовете за счетоводна информация и глобалните атрибути на HTML, препратени към визуализирания елемент, не са неизвестни полета. Това не допуска произволни ключове в редовете на повторител или разширения на основни блокове.

Код Значение expected
unknown_field Нито едно запазено поле не декларира този ключ за съхранение. Познати ключове за съхранение.
unknown_option Изборът не е сред познатите опции. Допустими стойности за опции.
wrong_type Съхранената структура не се поддържа от полето. Очаквано семейство или тип на съхранение.
too_few_rows, too_many_rows Наличен повторител е извън min или max. Ограничението за броя редове.
definition_conflict Приложимите дефиниции за един ключ изискват различни структури за съхранение. Източникът и типът на полето за всяка дефиниция.
shadowed_value Вложена стойност замества различна стойност на поле от най-горно ниво. Вложената стойност, която надделява.
extension_top_level Шаблонът може да чете стойност от най-горно ниво, но обвързванията на разширенията не могат. Задължителният ѝ път под blockstudio/attributes.
unknown_attribute Ключ от най-горно ниво на блок Blockstudio не се чете от пътя за визуализиране и се премахва. Регистрирани имена на атрибути, полета на разширения и blockstudio.
missing_container attributes, disabled, name или editor се съхранява на най-горно ниво, а blockstudio липсва. Задължителният му път под blockstudio.
invalid_container blockstudio или blockstudio.attributes не е обект. object.

Съобщението за открита от unknown_field грешка посочва най-близкия ключ за съхранение на същото ниво, ако разликата е до три редакции — правилото, използвано при непознати настройки: This storage key is not declared by the block or its extensions. Did you mean "title"? expected продължава да показва всички известни ключове. Съвпадението не отчита регистъра и разглежда само ключовете за съхранение в този контейнер. Съобщенията са преведени; интеграциите трябва да използват code, path и expected вместо да анализират текста на съобщението.

Ключ от най-горно ниво на блок Blockstudio, който не е регистриран атрибут (неговите полета и атрибутите, които WordPress добавя за supports, lock и metadata), поле на съответстващо разширение, blockstudio, ключ за счетоводна информация или препратен атрибут на HTML, се премахва, преди шаблонът да се изпълни. Такъв ключ, например сгрешен ID на поле или обект със стойности, съхранен без обвивката си blockstudio, генерира констатация, защото блокът се визуализира без тази стойност. Блокове, които съдържат само полета на разширения, не се проверяват за ключове от най-горно ниво.

Приетите структури следват визуализирането: множествените избори и квадратчетата за отметка могат да съдържат списък, обект за една опция или импортирана скаларна стойност, включително числова нула. За числата се приемат низове с числови стойности. Файловете могат да съдържат ID на прикачени файлове, обекти с ID, списъци или низови препратки. Стойностите за връзки и икони трябва да са обекти; за персонализираните типове полета се използва регистрираният тип атрибут. Поле attributes съдържа списък от двойки с непразно име attribute и скаларна стойност value; незадължителните метаданни, като data.media, се запазват.

WordPress валидира регистрираните атрибути от най-горно ниво преди визуализиране и така може да отхвърли структура, приета във blockstudio.attributes. Например стойност за radio с "a" работи във вложения обект, но се премахва на най-горно ниво, където регистрираният ѝ тип е object. Такава стойност генерира wrong_type. Използвайте вложения обект за същата структура на съхранение, която редакторът записва.

Липсващите полета не са задължителни. Празните вложени стойности (null, false, '', []) и деактивираните полета не генерират грешки за стойности. Изрично празен повторител все пак се проверява спрямо min; липсващ или деактивиран повторител не се проверява. Празна стойност от най-горно ниво се отчита, ако WordPress я премахне и възстанови непразна стойност по подразбиране. Същата стойност във вложения обект може да я изчисти. Конфликтите между дефиниции се отчитат дори когато ключът няма запазена стойност.

Статичните опции и опциите за попълване, разрешени при регистрацията, се проверяват, без попълването да се изпълнява отново. Отдалечените опции fetch и аргументите за попълване, съдържащи {attributes.*}, се пропускат. Цветовете и градиентите могат да бъдат персонализирани, освен ако не е зададено disableCustomColors или disableCustomGradients. Това проверява съхранените стойности, а не default, fallback или правилата за валидиране в редактора.

Съответстващите полета на разширения се включват за всеки блок, към който се отнасят. При визуализиране по-късните дефиниции надделяват в блока или в неговите разширения на най-горно ниво. Собствено поле на блока и поле на разширение остават отделни дефиниции на един и същ ключ и се прилагат и двете. В редовете на повторител визуализаторът чете първото поле със съвпадащ ID във всеки източник, затова се прилагат неговите опции и ограничения. Дублираните дефиниции се запазват за диагностика на конфликти: несъвместимите структури за съхранение генерират definition_conflict, дори ако по-късно дублирано поле не се чете при визуализиране.

Функцията проверява един блок. Обходете innerBlocks при валидиране на документ; синхронизираните шаблони и другите препратки не се разгръщат автоматично. Командата wp bs blocks validateпреминава през блоковете в една или повече публикации и отчита пътищата до блоковете.

Сайтове с персонализиран разрешител по време на визуализиране могат да адаптират констатациите, без да променят съхранените данни:

PHP
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
  if ($name !== 'my-theme/card') {
    return $findings;
  }

  return array_values(array_filter($findings, function($finding) {
    return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
  }));
}, 10, 3);

Винаги връщайте списък с констатации; връщането на [] приема блока. Този филтър се изпълнява само за управлявани блокове, никога за резултата null.

Описване на съхранените стойности

Използвайте bs_block_schema() след регистрирането на блока (init или по-нова версия), за да опишете стойностите, които блокът съхранява, например за генериране на маркировка на блок в инструмент или интеграция с AI, или за проверка на входните данни в маршрут на REST:

PHP
$schema = bs_block_schema('theme/card');

if ($schema === null) {
  // No Blockstudio fields or matching extensions apply.
}

Резултатът е схема JSON на обекта, запазен в attrs.blockstudio.attributes. Тя обхваща полетата на блока и полетата на съвпадащите разширения, заедно с ключовете за съхранение, използвани при валидирането: група от най-горно ниво добавя префикс към дъщерните си елементи, анонимните групи и разделите не добавят ниво, а поле за файл добавя своя спътник <id>__size. Повтарящите се полета са списъци от обекти на редове с minItems и maxItems от min и max. additionalProperties е false в корена на хранилището на полетата и в редовете на повтарящите се полета. Полета със стойности обекти, като връзки и персонализирани обекти, могат да носят свои собствени метаданни. Блок без полета няма properties, така че съвпада само празен обект.

Всяко поле е описано в каноничен формат, приет от bs_validate_block():

Поле Схема
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block Низ.
number, range Число с minimum и maximum от min и max.
toggle Булева стойност.
select, radio, checkbox Стойност на опция или списък със стойности на опции за checkbox и multiple с enum.
color, gradient Низ с enum, когато е зададено disableCustomColors или disableCustomGradients.
token Списък от низове.
files Неотрицателен идентификатор на прикачен файл или списък от идентификатори с multiple.
link Обект с url, title и opensInNewTab; url е задължително.
icon Обект с set, subSet и icon; set и icon са задължителни.
attributes Списък от обекти с непразно attribute и скаларно value.
repeater Списък от обекти на редове.
Типове персонализирани полета Регистрираният им тип атрибут.

enum изброява опциите, които проверява валидирането: статични опции и опции за попълване, разрешени още при регистрацията. Отдалечените опции fetch и аргументите за попълване, съдържащи {attributes.*}, нямат enum. Ключ с дефиниции на различни форми на съхранение се пропуска, защото валидирането отчита всяка стойност, съхранена под него. Когато поле на блок и поле на разширение споделят ключ, enum изброява стойностите, които и двете приемат. Споделените повтарящи се полета комбинират дъщерните си полета и прилагат по-строгите ограничения за броя редове от двете дефиниции. В редовете на повтарящите се полета се използва първото поле със съвпадащ идентификатор във всеки източник, както при визуализиране. Изрично зададено поле с име <id>__size има предимство пред автоматично добавен спътник за размера на файла.

Когато затворено поле няма налични опции или два приложими набора от опции нямат общи стойности, каноничната му стойност е null за единичен избор или празен списък за множествен избор. Празният списък с опции не превръща полето в неограничено. Отдалечените опции и тези, които зависят от атрибути, остават отворени.

label на полето става title, неговото help става description, а default се запазва като пояснителна анотация. Собственото title на схемата е заглавието на блока. Полетата никога не са задължителни, а условната логика не е част от схемата.

Ограниченията използват само ключови думи, които rest_validate_value_from_schema() проверява, така че схемата може да се използва като входна схема на маршрут на REST или на възможност без промени:

PHP
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
  $result = rest_validate_value_from_schema($values, $schema);
}

Схемата описва по един формуляр за всяко поле; валидирането приема и импортирани форми като обекти с опции, числови низове и обекти с ID. Тя не замества bs_validate_block(): конфликтите в дефинициите са проблеми с конфигурацията и пак могат да доведат до резултати, дори когато конфликтният ключ е пропуснат. Филтрите за валидиране могат да налагат и специфични за сайта правила. Използвайте bs_validate_block(), за да проверите съхраненото съдържание. Сайтовете с персонализиран обработчик за резолвиране по време на визуализиране могат да адаптират схемата чрез филтъра blockstudio/blocks/attributes/schema.

Функции на PHP

Без данни

В най-простата си форма функцията приема една стойност — ID на блока, който трябва да бъде изобразен на страницата.

PHP
bs_render_block('blockstudio/cta');

С данни

За да изобразите блока с персонализирани данни, за първия параметър трябва да използвате масив вместо единична стойност. Стойността в ключа data ще бъде предадена на променливата $attributes и $a във вашия шаблон на блока.

PHP
bs_render_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
]);

Влагане

Блоковете могат да се влагат един в друг чрез функцията bs_block в комбинация с мощната променлива $content във вашите шаблони на блокове.

PHP
<div>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => bs_block([
    'id' => 'blockstudio/button',
    'data' => [
      'text' => 'Button Text',
    ]
  ])
]);

Блокът за бутон ще бъде изобразен на мястото на променливата $content в шаблона на блока.

Вградените блокове, изобразени с bs_render_block() или bs_block(), винаги извеждат HTML, разрешен за фронтенда, дори когато родителският блок в момента изобразява визуализация за редактора. Псевдокомпонентите на шаблона, като <RichText /> и <InnerBlocks />, се разрешават преди връщането на вградения блок.

Множество слотове

Възможно е също да създадете множество слотове за съдържание, като просто направите променливата $content асоциативен масив и извикате съответните му ключове във функцията bs_block.

PHP
<div>
  <?php echo $content['beforeContent']; ?>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content['afterContent']; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => [
    'beforeContent' => bs_block([
      'id' => 'blockstudio/badge',
      'data' => ['text' => 'Before Content']
    ]),
    'afterContent' => bs_block([
      'id' => 'blockstudio/button',
      'data' => ['text' => 'Button Text']
    ])
  ]
]);

Етикети на блокове

Вградете всеки блок чрез синтаксиса на етикетите HTML. Поддържат се два формата:

HTML
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />

И двата формата изобразяват един и същ блок. Синтаксисът <bs:> превръща тирето в разделител на пространство от имена (acme-hero става acme/hero). Търсенето по тирета се извършва отляво надясно и се използва първият регистриран кандидат, така че се разрешават и пространства от имена, съдържащи тирета: <bs:acme-ui-button> проверява acme/ui-button, после acme-ui/button. Синтаксисът <block> задава пълното име на блока като атрибут name.

Работят както блокове Blockstudio, така и основни блокове на WordPress. Блоковете Blockstudio се изобразяват чрез целия конвейер (шаблони, Tailwind, ресурси). Основните блокове се изобразяват чрез системата за изобразяване на блокове на WordPress, като се използват вградените рендерери на блокове.

Как работи

Етикетите на блокове се държат различно в зависимост от мястото, на което се намират:

В шаблоните на блокове и съдържанието на публикации етикетите се заменят с изобразени HTML по време на изпълнение. Резултатът е окончателната маркировка на посочения блок, вградена директно в страницата. В редактора няма блок WordPress за тях. Те служат само за изобразяване.

В страници, образци и шаблони на сайта етикетите се преобразуват в основни блокове на WordPress, преди изходният код на файла да бъде синхронизиран или регистриран в WordPress. Това означава, че блоковете се показват в редактора, могат да се редактират, когато целевото място поддържа редактиране, и преминават през целия жизнен цикъл на блоковете в WordPress. Синтаксисът на етикетите е съкратен начин за дефиниране на съдържание на блокове във файловете с шаблони.

Това разграничение е важно: етикетите на блокове в шаблоните генерират изход, а в страниците, образците и шаблоните на сайта създават основни блокове.

В шаблоните на блокове

Етикетите на блокове се изобразяват автоматично в шаблоните Twig и PHP. Не е необходима настройка. Това включва синтаксисите <bs:> и <block>, както и всички регистрирани етикети с представка и псевдоними, така че шаблонът може да ги изведе директно, вместо да извиква bs_render_block(). Резултатът се изобразява HTML и се вгражда директно в изхода на шаблона на блока:

Twig
<div class="my-page">
  <bs:mytheme-card title="Featured" />
  <block name="core/separator" />
  <bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
  <block name="core/heading" level="2">Also WordPress</block>
  <theme-card title="Prefix shorthand" />
</div>

В съдържанието на публикации

Изобразяването на ниво страница (съдържание на публикации, области с джаджи) е по избор:

JSON
{
  "blockTags": {
    "enabled": true
  }
}

Или чрез филтър:

PHP
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');

Синтаксис

Самозатварящи се етикети:

HTML
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />

Сдвоени етикети с вътрешно съдържание:

HTML
<bs:mytheme-section layout="wide">
  <p>Content inside the block.</p>
</bs:mytheme-section>

<block name="core/group">
  <block name="core/paragraph">Inside a group.</block>
</block>

Комбинирайте свободно. И двата синтаксиса могат да се влагат един в друг:

HTML
<bs:mytheme-section>
  <block name="core/heading" level="2">Title</block>
  <bs:mytheme-card title="Features" />
  <block name="core/paragraph">Description text.</block>
</bs:mytheme-section>

Съкратени представки

Етикетите на блокове могат да използват и съкратени представки, специфични за проекта. Регистрирайте представка с едно или повече пространства от имена и Blockstudio ще разреши <prefix-slug> към първия регистриран блок в този ред на пространствата от имена:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
HTML
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />

В примера по-горе <theme-card> се разрешава до theme-components/card, <theme-button> преминава към bsui/button, когато theme-components/button не е регистриран, а <theme-ui-feature-matrix> се разрешава до theme-components/ui-feature-matrix.

Представките могат също да се комбинират. Когато етикет с представка не се разреши директно, а оставащият идентификатор сам по себе си е регистриран етикет с представка, разрешаването се повтаря рекурсивно, така че представка на марка може да се базира на представка на пространство от имена:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components'];
  $prefixes['ui'] = ['bsui'];

  return $prefixes;
});
HTML
<theme-ui-input />

<theme-ui-input> няма блок theme-components/ui-input, затова преминава към представката ui и се разрешава до bsui/input. Директните съвпадения винаги имат предимство пред вложеното разрешаване, а правилата за разрешаване и забрана се прилагат към окончателно разрешения блок.

Можете също да конфигурирате представки в blockstudio.json:

JSON
{
  "blockTags": {
    "prefixes": {
      "theme": ["theme-components", "bsui"]
    }
  }
}

Представките трябва да съдържат малки букви или цифри, да започват с буква и да не съдържат тирета. Изричните псевдоними от blockstudio/block_tags/tag_aliases имат предимство пред разрешаването на представки. Етикетите с непознати представки остават непроменени.

Представките и етикетите с псевдоними продължават да се поддържат за удобство при създаването на съдържание. Каноничният, преносим запис винаги е <bs:namespace-slug>, защото съдържа истинското име на блока и не зависи от филтрите на проекта:

HTML
<bs:theme-components-card />
<bs:bsui-input />

В примерите за Blockstudio, генерираните диагностични съобщения и програмния изход се използва този каноничен запис. Проектите, които искат да премахнат по-стар съкратен синтаксис, могат да използват самостоятелната миграция към канонични етикети, която първо изпълнява пробна операция, без да стартира WordPress.

Основни блокове

Може да се използва всеки блок с регистриран рендерер:

HTML
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
  <bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>

Или със синтаксиса <block>:

HTML
<block name="core/group">
  <block name="core/columns">
    <block name="core/column">
      <block name="core/paragraph">Left column</block>
    </block>
    <block name="core/column">
      <block name="core/paragraph">Right column</block>
    </block>
  </block>
</block>

Списъци за разрешаване и забрана

Контролирайте кои блокове могат да се изобразяват чрез етикети:

JSON
{
  "blockTags": {
    "enabled": true,
    "allow": ["mytheme/*", "core/*"],
    "deny": ["mytheme/internal-*"]
  }
}

allow разрешава само съвпадащите шаблони. deny изключва съвпадащите шаблони и има предимство. И двете поддържат заместващи символи * чрез fnmatch(). Те се прилагат и към двата синтаксиса, както и към изобразяването на ниво шаблон и страница.

Филтри: blockstudio/block_tags/allow и blockstudio/block_tags/deny.

Пропускане на HTML

Атрибутите с представка data- се предават към коренния елемент на изобразения блок. Атрибутите с представка html- също се предават, като представката се премахва. Работи и с двата синтаксиса. Предаваният атрибут замества съществуващата стойност на коренния елемент, вместо да се обединява с нея, така че html-class заменя собствените класове на блока.

Блокът Blockstudio добавя и глобалните атрибути, които не са декларирани като полета, към коренния си елемент: id, style, role, title, lang, dir, hidden, tabindex и всеки атрибут aria-*. Декларираното поле винаги има предимство, така че блок с поле title получава стойността в $a['title']. Препратените стилове минават през safecss_filter_attr(); филтърът WordPress се прилага към атрибутите за стил в съдържанието на публикации, а стиловете се добавят към стил, който шаблонът вече задава.

Стойностите на атрибутите са HTML, затова обектите се декодират веднъж при анализирането на етикета: title="Tom &amp; Jerry" достига до шаблона като Tom & Jerry и се екранира отново при извеждането. Стойностите в кавички могат да съдържат >, както е при вариантите Tailwind и селекторите за анимация, както в самозатварящи се, така и в сдвоени етикети.

Всеки друг атрибут, който блокът не декларира, включително class, никога не достига до HTML. Когато WP_DEBUG е включено, Blockstudio съобщава за всеки такъв атрибут веднъж на заявка чрез _doing_it_wrong(). Декларирайте поле за него или го задайте като атрибут data-, aria- или html-.

HTML
<bs:mytheme-card
  title="My Card"
  html-class="featured-card"
  html-id="main-card"
  data-analytics="card-click"
/>

<block name="core/paragraph" html-class="highlight" data-section="intro">
  Highlighted paragraph.
</block>

Персонализирани рендерери

Регистрирайте персонализирани рендерери на блокове за допълнителни типове блокове. Рендерерите приемат масив от атрибути и низ с вътрешно съдържание и връщат масив от блокове WordPress:

PHP
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
    $builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
        $html = '<div class="my-block">' . $inner_content . '</div>';
        return [
            'blockName'    => 'myplugin/custom-block',
            'attrs'        => $attrs,
            'innerBlocks'  => [],
            'innerHTML'    => $html,
            'innerContent' => [$html],
        ];
    };
    return $builders;
}, 10, 2);

За блокове-контейнери, които трябва да анализират вътрешното съдържание като дъщерни блокове, добавете втори запис в същия филтър:

PHP
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
    $inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
    $content = ['<div class="my-wrapper">'];
    foreach ($inner_blocks as $block) {
        $content[] = null;
    }
    $content[] = '</div>';
    return [
        'blockName'    => 'myplugin/wrapper',
        'attrs'        => $attrs,
        'innerBlocks'  => $inner_blocks,
        'innerHTML'    => '<div class="my-wrapper"></div>',
        'innerContent' => $content,
    ];
};

blockstudio/block_tags/builders се прилага както към етикети на блокове, така и към персонализирани блокове, избрани чрез blockstudio/parser/element_mapping. Това е подходящият хук, когато блок на проекта със съответствие към елемент трябва да премести вътрешния текст в поле Blockstudio или да създаде персонализиран масив от блокове.

blockstudio/block_tags/renderers и blockstudio/parser/renderers получават един и същ регистър и имат еднаква форма на обратното извикване. Те остават налични за съвместимост и окончателни замени на ниво анализатор. Филтрите се изпълняват в този ред:

  1. blockstudio/block_tags/builders
  2. blockstudio/block_tags/renderers
  3. blockstudio/parser/renderers

По-късен филтър може да замени рендерер, регистриран от по-ранен.

Програмна употреба

Приложете изобразяване на етикети към всеки низ от PHP:

PHP
$html = apply_filters('blockstudio/block_tags/render', $content);

Компоненти

Етикетите на блокове се съчетават добре с компонентите. Компонентите са блокове, които се изобразяват само програмно и никога не се показват в редактора.

HTML
<bs:mytheme-card title="My Card" description="Card content." />

Анализатор

Етикетите на блокове се обработват от лек скенер за низове, който заменя DOMDocument. Анализаторът обработва както синтаксиса <bs:>, така и <block>, вложени етикети с едно и също име чрез проследяване на дълбочината, стойности на атрибути в кавички и рекурсивни блокове-контейнери. Той е създаден специално за този случай на употреба, работи по-бързо от DOMDocument и WP_HTML_Tag_Processor на WordPress, и избягва известните проблеми на DOMDocument с премахването на представки от пространства от имена и преобразуването на имената на атрибутите в малки букви.

За страници, образци и шаблони на сайта същият анализатор обработва и необработени елементи HTML (<p>, <div>, <h1> и т.н.), като ги съпоставя със съответните основни блокове WordPress.

Когато съпоставянето на елементи насочва <p> към регистриран небазов блок Blockstudio, който декларира атрибут content от тип richtext, вътрешният HTML автоматично се насочва към този атрибут content, включително вградени етикети като code и img, съпоставени с елемент на ниво блок. Абзац, чието единствено дъщерно съдържание е изображение, се преобразува в блока, към който сочи <img>. Вложените етикети на блокове или елементите HTML на ниво блок продължават да се обработват чрез обичайния анализ на вътрешните блокове. <block name="core/shortcode"> запазва текста на шорткода си като съдържание на блока.