Как получить доступ к блокам Гутенберга и разобрать их с помощью PHP

В этом посте мы рассмотрим, как анализировать блоки Гутенберга поста и извлекать определенные блоки, чтобы сделать что-то еще. Мы рассмотрим PHP-функции WordPress для разбора, извлечения и рендеринга выбранных блоков.

Одним из преимуществ нового редактора Gutenberg в WordPress является более структурированные данные для контента публикации. В прежние времена все хранилось в виде HTML, и не было возможности извлечь определенные фрагменты контента без очень сложных регулярных выражений. Но с Gutenberg каждая часть контента, будь то абзац, заголовок, изображение, видео, кнопка или столбец, внутри которого есть другие блоки, хранится с информацией, которая говорит нам, что это за часть контента.

Со встроенными функциями WordPress очень легко получить все блоки в содержимом сообщения в виде массива со всей их информацией. Это открывает множество полезных функций для разработчиков тем. Просто упомянем несколько идей:

• Динамически сгенерируйте оглавление, выбрав все заголовки (учебник ниже).
• Получите все видео, изображения или цитаты, используемые во всех сообщениях, чтобы собрать и перечислить их все на другой странице.
• Извлеките первый абзац сообщения и используйте его как отрывок в архиве (учебник ниже).
• Получите обзор использования конкретных блоков и их положения. Например, скажем, у вас есть настраиваемый рекламный блок, и вам нужно знать, как часто он используется в ваших сообщениях и как далеко в содержании они появляются.
• Визуализируйте блоки сообщения, но исключите определенные типы блоков.
• Проверьте, начинается ли контент публикации с видео, и используйте это видео вместо избранного изображения в архивах.
• Если вы используете настраиваемый блок, содержащий технические характеристики продуктов, вы можете легко создать страницу, на которой отображаются и сравниваются технические характеристики сообщений о продуктах.
• Динамически собирайте все отдельные изображения, используемые в сообщении, и создавайте их галерею в конце или в другом месте.

Давайте просто прыгнем прямо в это!

Разбирать блоки поста

Для разбора блоков мы используем функцию WordPress [parse_blocks](https://developer.wordpress.org/reference/functions/parse_blocks/)(). В качестве параметра вам необходимо указать строку содержимого сообщения. Если вы находитесь внутри цикла или имеете доступ к объекту сообщения, просто укажите $post->post_contentв качестве параметра функцию.

Возврат из parse_blocks()представляет собой массив, где каждый элемент массива является блоком. Для каждого элемента блока у вас есть такая информация, как тип блока (ключ ‘ blockName‘), атрибуты блока (ключ ‘ attrs‘), внутренние блоки для вложенных блоков, таких как столбцы (ключ ‘ innerBlocks‘), и два элемента для фактического содержимого блока (ключи ‘ innerHTML‘ и ‘ innerContent‘). Элемент innerHTMLпредставляет собой строку содержимого HTML, а innerContentпредставляет собой массив строк HTML.

И это все! Прокрутите возвращенный массив parse_blocks(), чтобы сделать свое дело. Мы рассмотрим дополнительные примеры кода ниже в этом посте.

Примечание о классических (не Гутенберговых) сообщениях

Возможно, вы работаете на старом сайте WordPress, на котором были созданы сообщения до обновления до Gutenberg (или вы использовали плагин Disable Gutenberg). В этом случае эти посты не будут иметь структурированного контента поста, а весь контент поста будет находиться внутри блока «Классический редактор».

Массив, возвращаемый функцией parse_blocks(), для таких сообщений будет возвращать один элемент массива блоков с blockNameустановленным значением null. Полный HTML-контент поста находится внутри innerHTMLстроки этого элемента.

Мы можем с уверенностью предположить, что если возврат поста parse_blocks()имеет один элемент и blockNameравен null, мы имеем дело с постом «до Гутенберга». В противном случае blockNameвсегда будет заполнено. Это хорошая проверка, о которой следует помнить при написании кода для синтаксического анализа блоков сообщений, и вы хотите обрабатывать старый контент WordPress.

Рендеринг блока

WordPress также предлагает функцию для рендеринга определенного блока с расширением [render_block](https://developer.wordpress.org/reference/functions/render_block/)(). В качестве параметра вам нужно предоставить массив для блока, как один из тех, что были возвращены parse_blocks()выше. Функция возвращает строку отображаемого HTML, которую вы можете просто вывести на экран.

Приведенный выше код будет отображать все блоки сообщения, как обычно при отображении содержимого сообщения. Самое интересное начинается, когда мы начинаем добавлять код для исключения или включения определенных блоков, которые нас интересуют.

Например, приведенный ниже код распечатает только блоки абзаца сообщения:

foreach ($blocks as $block) {
    if ($block['blockName'] == 'core/paragraph') {
        echo render_block($block);
    }
}

И это отобразит все блоки, но исключит все блоки шорткода:

foreach ($blocks as $block) {
    if ($block['blockName'] != 'core/shortcode') {
        echo render_block($block);
    }
}

Имена блоков

При разборе блоков поста вам, скорее всего, потребуется проверить тип блока. Их довольно просто угадать. Например, блок Paragraph — это, как вы уже догадались, paragraph. Однако имейте в виду, что все блоки Gutenberg в WordPress имеют префикс пространства имен. Для основных блоков WordPress (по умолчанию) все они имеют префикс «core/«. Исключением являются блоки Embed, которые имеют префикс " core-embed/". Так, например, блок абзаца будет иметь имя блока core/paragraph.

Чтобы избежать диких догадок, вот обзор блоков по умолчанию, предоставляемых WordPress (на момент написания этой статьи):

Общие блоки

• Параграф:core/paragraph
• Изображение:core/image
• Заголовок:core/heading
• Галерея:core/gallery
• Список:core/list
• Цитировать:core/quote
• Аудио:core/audio
• Покрытие:core/cover
• Файл:core/file
• Видео:core/video

Форматирование

• Предварительно отформатировано:core/preformatted
• Код:core/code
• Классический: core/freeform
  (но для сообщений, не относящихся к Гутенбергу, это будет null, см. примечание о сообщениях, не относящихся к Гутенбергу)
• Пользовательский HTML:core/html
• Цитата:core/pullquote
• Стол:core/table
• Стих:core/verse

Макет

• Кнопка:core/button
• Столбцы:core/columns
• Более:core/more
• Разрыв страницы:core/nextpage
• Разделитель:core/separator
• Разделитель:core/spacer
• Медиа и текст:core/media-text

Виджеты

• Короткий номер:core/shortcode
• Архивы:core/archives
• Категории:core/categories
• Последние комментарии:core/latest-omments
• Последние посты:core/latest-posts

Встраивает

• Встроить:core/embed

• Твиттер:core-embed/twitter

• YouTube:core-embed/youtube

• Фейсбук:core-embed/facebook

• Инстаграм:core-embed/instagram

• WordPress:core-embed/wordpress

• Саундклауд:core-embed/soundcloud

• Спотифай:core-embed/spotify

• Фликр:core-embed/flickr

• Видео:core-embed/vimeo

• Анимото:core-embed/animoto

• Облако:core-embed/cloudup

• Crowdsignal:core-embed/crowdsignal

• Ежедневное движение:core-embed/dailymotion

• Хулу:core-embed/hulu

• Изображение:core-embed/imgur

• Проблема:core-embed/issuu

• Кикстартер:core-embed/kickstarter

• Meetup.com: core-embed/meetup-com

• Миксклауд:core-embed/mixcloud

• Реддит:core-embed/reddit

• Реверберация:core-embed/reverbnation

• Скринкаст:core-embed/screencast

• Скрибд:core-embed/scribd

• Поделиться слайдом:core-embed/slideshare

• СмугКружка:core-embed/smugmug

• Колода динамиков:core-embed/speaker

• ТЕД:core-embed/ted

• Тамблер:core-embed/tumblr

• ВидеоПресс:core-embed/videopress

• WordPress.tv: core-embed/wordpress-tv

• Амазонка Киндл:core-embed/amazon-kindle

Пример кода: получение первого абзаца сообщения как отрывка

Хорошо написанный пост должен начинаться с абзаца, который представляет, о чем пост, и побуждает людей продолжать чтение. Они идеально подходят для использования в качестве выдержек вместо того, чтобы полагаться на автоматическую функцию выдержки в WordPress!

Это функция, которую вы можете добавить в свою тему functions.php, чтобы вернуть первый абзац сообщения. Если сообщение не было предоставлено, оно будет ссылаться на глобальный объект сообщения. Он также размещает сообщения, не относящиеся к Гутенбергу, возвращая для них фактическую выдержку WordPress.

После parse_blocks()вызова функции мы проверяем, содержит ли пост неверные данные блока (пост был создан до Гутенберга), и возвращаем выдержку поста, если это так. В противном случае мы перебираем блоки сообщения, находим первый блок абзаца и возвращаем его innerHTML. В самом конце мы возвращаем строку с (это не обязательно) <div>вокруг нее.

Чтобы использовать эту функцию, все, что вам нужно сделать, это вызвать:

echo awp_get_excerpt();

Предположим, что вызов функции находится где-то там, где есть глобальный $postобъект, например, внутри цикла. Если вы хотите указать сообщение, укажите объект сообщения в качестве параметра для вызова функции:

$post_id = 1;
$post = get_post($post_id);
echo awp_get_excerpt($post);

Пример: создание оглавления из заголовков сообщения

Вы можете автоматически и динамически создавать оглавление на основе блоков заголовков сообщения. Процесс достаточно прост; разобрать блоки поста и найти все блоки типа core/heading. Но мы можем сделать еще один шаг вперед и включить уровни; например, помещая h3как подзаголовок под h2и так далее.

Заголовочный блок содержит информацию о своем уровне в элементе массива атрибутов (ключ ‘ attrs‘). Внутри attrsмассива это будет элемент массива с ключом ‘ level‘ и целым числом, обозначающим уровень. A h3будет иметь levelзначение 3, a h4будет иметь levelзначение 4, и так далее.

Однако обратите внимание, что attrsблоки for header могут быть пустыми! Это происходит, когда автор не изменил тип заголовка в сторону от значений по умолчанию в настройках блока. Чтобы обойти это, нам нужно сделать некоторые предположения. Заголовки по умолчанию будут h2(если вы не изменили это в своей теме). Таким образом, мы можем предположить, что если блок заголовка не имеет атрибута уровня, это блок h2. В противном случае мы получаем информацию об уровне из атрибутов.

Если вы действительно готовы принять вызов, я предлагаю вам улучшить приведенный ниже код. Проблема создания правильного структурированного olсписка заключается в том, что мы не можем контролировать, как автор структурирует свои заголовки. Они вполне могут сойти с ума и начать с h4заголовка, а затем перейти сразу к h2заголовку. И вдруг они смешиваются h1в середине. Поэтому мое решение включает в себя создание плоского olсписка и предоставление информации об уровне в классах элементов списка. Затем с помощью умного CSS вы можете сделать отступ для элементов списка с некоторым левым отступом.

Код

Вот функция оглавления:

Функция начинается с обработки поста и разбора его блоков. В строке #9мы размещаем посты, не относящиеся к Гутенбергу. Функция продолжает перебирать все блоки, и всякий раз, когда она находит блок заголовка, он добавляется в наш $headingsмассив. Мы используем [wp_strip_all_tags](https://developer.wordpress.org/reference/functions/wp_strip_all_tags/)(), чтобы удалить теги HTML из заголовков. Мы также добавляем информацию об уровне в наш массив, где по умолчанию установлено значение, 2если атрибуты пусты.

После блочного цикла $headingsмассив должен содержать все заголовки постов по порядку. Затем мы можем просто сгенерировать строку HTML и вывести ее содержимое. Как уже упоминалось, я создаю имя класса для каждого элемента с информацией об уровне заголовка, чтобы мы могли создать иллюзию структурированного списка с помощью CSS.

Как и в случае с приведенной выше функцией выдержки, мы можем вызвать эту функцию, когда находимся внутри цикла, например так:

echo awp_table_of_contents();

Или если мы находимся вне цикла или хотим указать пост;

$post_id = 1;
$post = get_post($post_id);
echo awp_table_of_contents($post);

Это создаст список, выглядящий примерно так:

Вывод

Как мы видели, благодаря структурированному богатому контенту постов, который стал возможен благодаря Гутенбергу, мы можем очень легко находить и извлекать определенные части контента постов. Вернитесь к списку примеров, которые я упомянул в начале поста. Нет никаких ограничений на то, что вы, как разработчик темы, можете сделать. Это просто зависит от того, в чем нуждается ваша тема или сайт WordPress (или что было бы просто круто).