Бесконечная страница: динамическая загрузка контента на WordPress

Все чаще и чаще на в сайты интегрируют элементы SPA, в частности “бесконечную страницу”… здравствуй, читатель! По ходу этой статьи будет описан принцип работы такой страницы, реализация и посадка на вордпресс.

SPA и бесконечная страница

В принципе, и SPA(Single Page Application – одно-страничное приложение) и бесконечная страница исповедуют один и тот же принцип(извиняюсь за тавтологию) – динамическая загрузка контента. Все очень просто – когда поступает событие(клик либо скролл, либо еще что-то), javascript’ом загружается новая порция контента и вставляется в страницу.

Реализация

Использовать буду jQuery(тут часть любителей хайповых React, Vue и прочего, вышли…). Обьясню свой выбор – зачем перегружать страницу яваскриптом? да, jQuery тоже библиотека без которой можно обойтись, но если он используется для многих других элементов – почему бы и нет?

Вот примерная разметка, составленная мной

<div class="container">
    <div class="page-1">
        <div class="card">
            <img src="path/to/img-1" class="img-fluid">
            <a href="path/to/single-post-1">
                <h2>Post Title 1</h2>
            </a>
            <p>post 1 excerpt</p>
        </div>
        ***
    </div>
    <div class="page-2"></div>
    ***
    <template id="post">
        <div class="card">
            <img src="" alt="" class="img-fluid">
            <a href="">
                <h2></h2>
            </a>
        </div>
    </template>
</div>

Немного о ней: поскольку я черпать контент буду в ворпрессе – то и использую пагинацию для разбивки на загружаемые блоки. Первую страницу загрузим обычным способом(каждая страница – это div class="page-%n"). В теге template будет содержаться разметка нашего поста – после загрузки пачки постов я буду ее клонировать.

Далее, нужно прибегнуть к javascript. Как я говорил ранее, на странице будет jQuery, поэтому сделаем AJAX-запрос к WP REST API со списком постов и их данными. Но прежде – определим условия для начала загрузки постов. Раз уж бесконечное полотно – значит условие это достижение нижней границы текущей страницы

var prevScroll = 0,
    page = 1,
    windowH = $(window).height(),
    positionY = $('.page-1').offset().top,
    blockH = $('.page-1').height(),
    template = $('#post').html(),
    currentScroll, tmpl

$(window).scroll(function (event) {
    currentScroll = $(this).scrollTop()

    if (currentScroll > prevScroll) {
        prevScroll = currentScroll

        if (Math.round(blockH + positionY) === (windowH + currentScroll)) {
            // Получаем посты, рисуем их и высчитываем новую границу для загрузки
        }
    }
})

Немного пояснений для этого куска кода. Эта строка(12) позволяет отсеять скролл вверх; можно было б отслеживать прокрутку колеса на мишке – но тогда скрипт был бы мертв на мобильниках. По поводу Math.round() свойства – высота(как и ширина) может быть дробной, в то время как значение скролла всегда целое число. Еще замечу – этот скрипт рабочий только в случаи если под блоком(не по разметке, а по позиции) с постами нет больше блоков(отсутствует футер). Дело в том, что при быстрой прокрутке scrollTop() имеет разрывы и тогда может произойти перескок нужного значения – потому, заменим его(===) простым сравниванием(>). Также, поскольку загрузка постов требует времени, используем коэффициент(что пользователю не пришлось ждать и он не покинул из-за этого сайт). В итоге, строка 15 трансформируется в

if (0.8 * (blockH + positionY) < (windowH + currentScroll)) {

Теперь, перейдем к тому, что внутри блока – содержимому строки 15. Само собой там загрузка и оттрисовка постов, но не только… вот полный код

$(window).off('scroll')
page++

$.get(
    '/wp-json/wp/v2/posts',
    {
        per_page: 5,
        page: page,
        _embed: 'wp:featuredmedia'
    },

    function (response) {
        $(response).each(function (i, e) {
            tmpl = $(template).clone()
            $(tmpl).find('img').attr('src', e._embedded["wp:featuredmedia"][0].source_url)
            $(tmpl).find('a').attr('href', e.link)
            $(tmpl).find('h2').text(e.title.rendered)
            $(tmpl).append(e.excerpt.rendered)

            $('.page-' + page).append(tmpl)
        })

        $('.page-' + page).find('img').on('load', function (i, e) {
            positionY = $('.page-' + page).offset().top
            blockH = $('.page-' + page).height()
        })

        if (page < pagesCount) {
            $(window).on('scroll', onScroll)
        }
    }
)

Традиционно, пояснения:

  • строка 1 “убивает” прослушивание события прокрутки. Это нужно потому, что js асинхронен и способен отослать несколько одинаковых запросов к серверу – что, в свою очередь, приведет к повторению постов(помимо ненужной нагрузки на сервер);
  • строки 4 – 33 сам запрос к серверу: первый аргумент это адрес эндпоинта WP REST API, который возвращает список постов, второй – обьект с параметрами постов, третий – функция, которая будет исполнена при получении ответа;
  • строки 23 – 26 – почему измерения высоты блока заперты в load’е? – у меня нет контейнера с размерами для картинки, а поскольку они грузятся отдельно от аякса – они изменяют размер блока постов через некоторое время;
  • строка 29 возвращаем прослушку прокрутки.

По ходу написания статьи я немного изменил скрипт, а именно, анонимную функцию слушателя присвоил переменной onScroll. Немного о том, почему в строке 14 я постоянно клонирую шаблончик – каждый клон одноразовый, т.е. один раз вставив клон его переменная стает пустой.

В общем, полный код бесконечной страницы(уже посаженой на шаблон страницы вордпрес) можно увидеть и взять здесь.

Elementor Addon. Пишем кастомный виджет к билдеру

Elementor – популярный wp плагин для построения страниц; данный тип плагинов называют pagebuilder. Это плагин(как и все в его категории) оперирует специальными виджетами – именно его я и создам, по ходу статьи…

Содержание

Предисловие

Здесья расскажу о том, что толкнуло меня на создание виджета(помимо получения опыта для написания этой писульки). Дело было так: была страница на которую выводилось видео с YouTube. К нему был список тайм-кодов, клик по которым включал воспроизведение видео с определенного момента. Временная метка(таймкод) состоит из самого времени, картинки и текста-описания. При переезде страницы на Элементор – всё взаимодействие сламалось. Задача: создать аддон к Элементор, добавляющий эти возможности в виджете.

Немного воды…

Всем, кто знаком с веб-программированием, с ходу стало понятно в чем причина – javascript; теперь для тех, кто незнаком: за прослушивание всех событий в браузере отвечает javascript. И правда, билдер изменил структуру DOM-дерева страницы и, за часик(долго разбирался в новой структуре), изменив селекторы в скрипте все заработало…

И что ж?.. на этом все? Было бы всё, если бы владелец не сказал, что неудобно так: строить ряд, в нем колонки с текстовым полем в(которых снова ряды с колонками) – сделай-ка единым блоком, чтоб в элементы управления просто вбить значения.

Приступим…

Начал я, разумеется, с оболочки плагина. На сайте плагина, в доках, есть шаблон кода основного файла для аддонов Элементор. Немного опишу главный метод, который в нем присутствует

add_action('elementor/init', function () {
    add_action('elementor/widgets/widgets_registered', function () {
        require_once(__DIR__ . '/class-youtube-widget.php');
        ElementorPlugin::instance()->widgets_manager->register_widget_type(new Elementor_YouTube_Widget());
    });
});

чтоб написать любое расширение к элементору нужно расширить его класс; чтобы получить доступ к ядру плагина(а именно там лежат они) нужно вызывать аддон после загрузки плагина. В движке есть хук(plugins_loaded), срабатывающий после загрузки всех плагинов – однако, в виду того, как устроен сам Элементор – в этот момент его ядро уже недоступно.

Плагин Элементор имеет свои хуки, позволяющие получить доступ к разным классам его ядра:

  • elementor/init – ко всем;
  • ementor/widgets/widgets_registered – к классу ElementorWidget_Base(и прочим, необходимым для создания нового виджета);
  • elementor/controls/control_registered – к классу ElementorControl_Base(и прочим, необходимым для создания нового типа контролера для плагина);

Это все хуки, которые нужно знать, для того чтоб построить свой виджет. На деле, из-за довольно широкой палитры встроенных контролей, 3ий хук я никогда не использовал – не было нужды создавать свои контроллеры.

Теперь можно переходить к созданию самого виджета… хотя, нет – пару строк о скрипте. Здесь, как и в вордпресс, нет метода, который подключал бы скрипты только когда виджет есть на странице(по крайней мере я таких не увидел – если ты о них знаешь – напиши в комментах, буду благодарен!) и потому я подключаю их как обычные скрипты.

Теперь немного о самом скрипте – в нем я буду использовать YouTube Iframe Player API. Начнем с html-разметки, которую будем строить на странице

        <section>
            <h2>{{ section_title }}</h2>
            <div class="elementor-row {{ video_position }}" data-id="{{ video_id }}">
                <div class="elementor-column frame-container">
                    <img src="https://img.youtube.com/vi/{{ video_id }}/hqdefault.jpg" class="youtube-preview" alt="Video Preview">
                </div>
                <div class="elementor-column">
                    {{ timestamps_loop }}
                        <figure class="stamp">
                            <img src="{{ timestamp_image_url }}" alt="Stamp Icon">
                            <span class="timestamp">{{ timestamp_time }}</span>
                            <span class="description">{{ timestamp_description }}</span>
                        </igure>
                    {{ endloop }}
                </div>
            </div>
        </section>

Думал использовать Iframe API, но глянув, что он делает – послал его лесом. Дело в том, что беглый анализ кода показал, что апи содержит методы постройки тега iframe с его атрибутами; учитывая, что страница индексируемая(должна быть оптимизирована под скорость загрузки) я решил не захламлять ее дополнительной библиотекой(jquery и так хорошо выполняет эту задачу). В общем, вот скрипт для работы с метками с вышеприведенной разметкой

(function($) {
    'use strict';

    $(document).on('click', '.youtube-preview', function() {
        var id = $(this).closest('.elementor-row').data('id');

        YTFrame.build(id, 0, $(this).parent());
    });

    $(document).on('click', 'figure.stamp', function() {
        console.log(this);
        var id = $(this).closest('.elementor-row').data('id'),
            time = $(this).find('.timestamp').text().split(':'),
            seconds = 60 * parseInt(time[0]) + parseInt(time[1]);
        console.log($(this).closest('.elementor-row').find('.frame-container')[0]);

        YTFrame.build(id, seconds, $(this).closest('.elementor-row').find('.frame-container')[0]);

    });

    var YTFrame = {
        build: function(id, seconds, container) {
            var iframe = document.createElement('iframe');

            iframe.src = 'https://www.youtube-nocookie.com/embed/' + id + '?autoplay=1&start=' + seconds;
            $(container).html(iframe);
        }
    }
})(jQuery);

Также, данный скрипт позволил обойти некоторые ограничения.

Доделываем

Имея скрипт и накидав разметку, а также оболочку для аддона – создадим класс нашего виджета. Он является дочерним для базового абстрактного виджета элементор(который доступен только в ядре плагина); также, необходимы классы для контроля виджета в редакторе

<?php

use ElementorControls_Manager;
use ElementorWidget_Base;
use ElementorUtils;
use ElementorRepeater;

Теперь создадмим сам класс со следующими методами

<?php
class Elementor_Test_Widget extends ElementorWidget_Base {

	public function get_name() {}

	public function get_title() {}

	public function get_icon() {}

	public function get_categories() {}

	protected function _register_controls() {}

	protected function render() {}

	protected function _content_template() {}

}

Первые 4 методы просто возвращают по строке. Метод render() строит разметку в редакторе(с приметкой) и на сайте

    protected function render()
    {
        $settings = $this->get_settings_for_display();
        $this->add_inline_editing_attributes('title', 'advanced'); ?>
        <section>
            <h2 <?php echo $this->get_render_attribute_string('text_attr') ?>>
                <?php echo $this->get_settings('title') ?>
            </h2>
            <div class="elementor-row  <?php echo esc_attr($settings['video_position']) ?>" data-id="<?php echo esc_attr($settings['video_id']) ?>">
                <div class="elementor-column frame-container">
                    <img src="<?php printf('https://img.youtube.com/vi/%s/hqdefault.jpg', esc_attr($settings['video_id'])) ?>" class="youtube-preview" alt="Video Preview">
                </div>
                <div class="elementor-column">
                    <?php foreach ($settings['timestams_repeater'] as $key => $value): ?>
                        <figure class="stamp">
                            <img src="<?php echo esc_url($value['stamp_image']['ur']) ?>" alt="Stamp Icon">
                            <span class="timestamp"><?php echo esc_html($value['time_stamp']) ?></span>
                            <span class="description"><?php echo esc_html($value['stamp_description']) ?></span>
                        </igure>
                    <?php endforeach; ?>
                </div>
            </div>
        </section>
        <?php
    }

Здесь Widget_Base->get_settings_for_display() это получение настроек виджета, которые я создам в следующем методе.

Метод _register_controls() отвечает за создание контролей виджета в сайдбаре редактора – здесь немного поподробней. Все настройки растоложены в 3х табах – контент, стиль и дополнительные(их не трожь – они всегда дефолтные!). чтоб выбрать таб нужно в этом методе написать

        $this->start_controls_section(
            'content_section',
            [
                'label' => __('Video'),
                'tab' => Controls_Manager::TAB_CONTENT,
            ]
        );

затем следует открывающий и закрывающий секцию настроек код

        $this->add_control(
            'title',
            [
                'label' => __('Section Title'),
                'type' => Controls_Manager::TEXT,
                'input_type' => 'text'
            ]
        );

        $this->end_controls_section();

и уже между этими тегами можно писать свою настройку.

Вся “слоенка” будет выглядеть так

        // указание на таб
        //  если TAB_CONTENT поменять на TAB_STYLE
        // будет запись в стиль-таб 
        $this->start_controls_section(
            'content_section',
            [
                'label' => __('Video'),
                'tab' => Controls_Manager::TAB_CONTENT,
            ]
        );

        // открытие новой секции
        $this->add_control(
            'title',
            [
                'label' => __('Section Title'),
                'type' => Controls_Manager::TEXT,
                'input_type' => 'text'
            ]
        );


        // настройка в секции, их может быть много
        $this->add_control(
            'video_id',
            [
                'label' => __('Video ID'),
                'type' => Controls_Manager::TEXT,
                'input_type' => 'text'
            ]
        );

        // закрытие текущей секции, но не таба!
        // после этого можно открыть новую секцию
        // она будет в том же табе
        $this->end_controls_section();

Впринципе, этих методов достаточно для того, чтоб сделать рабочий виджет. Далее пойдет вещь, которую я не делал в этой работе, но хочу показать и рассказать.

Наверняка внимательный читатель не только статьи но и кода, заметил в рендеринг-методе эти строки

$this->add_inline_editing_attributes('title', 'advanced');
$this->get_render_attribute_string('title');
$this->get_settings('title');

все они не имеют смысла без метода _content_template(). Поясню: виджет элементор – блок визуально редактируемый; это значит его можно редактировать в поле редактора, а не в сайдбаре. Кароч, 1ая строка это указатель на то, что эта настройка имееит возможность визуального редактирования; 2ой – получает набор классов для того чтоб javascript элементора взял под контроль этот тег; 3я – получает само значение настройки. В случаи с ‘advanced’ можно увидеть расширенную панель редактирования текста

расширенная панель редактирования текста
расширенная панель редактирования текста

Однако, чтоб все это сработало – необходим вышеуказанный метод с следующими строками

<# view.addInlineEditingAttributes( 'title', 'advanced' ); #>
<div {{{ view.getRenderAttributeString( 'title' ) }}}>{{{ settings.title }}}</div>

Заметь(!) эти строки должны выводиться, тк они будут вставлены в backbone-шаблоны(документация по ним). 2ая строка это т, что в окне редактора будет вставлено вместо редактируемой строки.

Заключение

Было разработанное расширение для Элементор. Код сможешь глянуть здесь, конечно он не полный(я удалил из него интеграции с другими плагинами, кастомными плагинами и сократил дерево настроек). Больше примеров ты увидишь в самом Элементор, ну а я попытался немного объяснить – что и как там работает.

Создаем блок редактора Gutenberg

Редактор Gutenberg блочный редактор wordpress для создания контентной части страницы. Он пример того, как плагин стал частью движка. В этой статье я буду не обозревать редактор, а выполнять разработку блока для расширения возможностей редактора.

Содержание

Постановка задачи

  • Задача: разработать плагин, добавляющий блок последних записей в редактор.
  • В блоке можно редактировать:
    • Количество выводимых постов;
    • Категорию постов(из существующих, не пустых)
    • Статус отображения изображения записи

Я уверен, что подобные плагины существуют и, что подобный блок можно собрать используя другие плагины, на подобии ACF. Но данная задача – это реальное тестовое задание, выполнением которого я хотел бы поделится.

Теоретические выкладки

Начнем из далека – нужно же статье придать объёма!

Редактор Gutenberg – это новый(относительно, частью wp он стал в версии движка 5, до этого был плагином) визуальный редактор WordPress для записей и страниц. Проект назван именем Иогана Гутерберга, презентовавшего Европе печатный станок и начавшего печатную революцию. Его работа сделала знание и информацию доступнее и запустила социальную революцию. Аналогично этому, разработчики хотят сделать доступным создание продвинутый макетов страниц для всех пользователей WordPress(источник).

Основная особенность редактора Gutenberg – это преставление всего контента в виде блоков и определение макета записи прямо в редакторе.

Ну все, хватит копи-паста, мой внутренний борец с плагиатом не позволит более. Да, я знаю, что все мои статейки – это, всего лишь, пере озвучка документаций и других источников… но, иногда, пишу и свои наблюдения.

В общем, каждый блок редактора – скрипт написанный на javascript с использованием библиотеки react. Все, что нужно для создания блока – это зарегистрировать скрипт и стили(коль нужны); в скрипте определить зависимости и функцию(с методами и свойствами).

Опишу свои мысли о том, что я буду делать – дабы выполнить поставленную задачу. Первым делом, учитывая, что по правилам хорошего тона react общается с приложениями по средствам REST API, и нужного пути вордпресс по умолчанию не имеет – создам этот путь в WP REST API. Второе – я знаю, что в таблицу БД движок сохраняет запись о блоке; поскольку, наш блок во фронте должен быть динамичен – то запись должна хранить элемент, который вордпресс ассоциирует с функцией. Кто ранее знакомился с этим движком, понял о чем я – о шоркоде, который мне также предстоит создать. И последнее, несколько слов о javascript – внутри функции регистрации блока нужно будет определить 4 вещи: мета инфу о блоке, его атрибуты, сохраняемую строку и вид в редакторе.

Установка рабочей среды

Это действие нужно чисто для удобства и скорости разработки. Но, в принципе, код можно писать и в блокноте – но все используют специальные редакторы. Так-что, советую эти операции проделать тоже…

Первое, при любой разработке на PHP(а язык бэка wordpress именно php) понадобится локальный сервер. Я использую OpenServer: просто скачай с официального сайта и установи его.

Второе – это компилятор JSX в JS, SCSS в CSS. В качестве такого компилятора, я использую NodeJS с пакетами; далее, подробно об установке.

С официального сайта грузим и устанавливаем NodeJS. После успешной установки, зашел в командную строку, у нас появиться менеджер пакетов npm. Первое, что нужно сделать – это сформировать package.json запуском команды

npm init

и дальнейшими ответами на поставленные вопросы. После чего, в командной строке пишем

npm install --save-dev @babel/core @babel/cli

это установи транскриптор babel в зависимости для ноды. И, для полного понимания при компиляции, нужен пресет @wordpress/babel-preset-default. Запустим

npm install @wordpress/babel-preset-default --save-dev

Среда для компиляции JSX готова. Немного о нахождении компилируемого файла и самого запуска процесса компиляции. Пусть компилируемый файл называется script.js и скомпилированный script-compiled.js; как я понял наблюдением, файл script.js должен лежать на одном уровне с package.json и папкой node_modules, так как ругается на указанные пути(по крайней мере, так было у меня). Сам процесс компиляции запускается так

npx babel --presets @wordpress/default script.js --watch --out-file script-compiled.js

После окончания компиляции, будет создан script-compiled.js

Backend блока

Бэк блока, как было ранее сказано, заключается в подключении скрипта и стилей, а также, нового rest-пути и шорткода. Делается это следующим кодом

<?php
function blocks_scripts()
{
    wp_enqueue_script(
        'gutenberg-latest-posts',
        plugins_url('/block/js/gutenberg-latest-posts-block.js'),
        ['wp-blocks', 'wp-element', 'wp-editor', 'wp-i18n'],
        true
    );
}
add_action('enqueue_block_editor_assets', 'blocks_scripts');

но, по условию, мне нужно выбрать категорию постов. Для этого передадим список категорий и путь, по которому блок будет брать информацию о постах – конечный PHP скрипт в этой части

<?php
function blocks_scripts()
{
    $categories = get_categories();

    if (!empty($categories)) {
        foreach ($categories as $key => $value) {
            $cats[$value->term_id] = $value->name;
        }
    }
    // скрываем блок если нет категорий
    if (!empty($cats)) {
        // подключаем блок
        wp_enqueue_script(
            'gutenberg-latest-posts',
            plugins_url('/block/js/gutenberg-latest-posts-block.js'),
            ['wp-blocks', 'wp-element', 'wp-editor', 'wp-i18n'],
            true
        );
        // создаем обьект glp, содержащий
        // список категорий и ссылку на WP REST API постов
        wp_localize_script(
            'gutenberg-latest-posts',
            'glp',
            [
            'categories' => $cats,
            'restURL' => esc_url(get_rest_url(null, 'block/v1/latest-posts'))
          ]
        );
    }
}
add_action('enqueue_block_editor_assets', 'blocks_scripts');

немного о зависимостях – скрипт wp-blocks содержит функции, необходимые для регистрации блока и образует js объект wp.blocks; wp-element содержит функции react с ворпрессовской “прокладкой”, объект wp.element; wp-i18n функции для создания translate ready, wp.18n. Зависимость wp-editor можно пропустить, но она содержит готовые функции для размещения элементов управления атрибутами блока.

Следующий шаг – создание пути ‘wp/v2/latest-posts‘ – ведь его еще не существует. Этот код его зарегистрирует в системе

<?php
add_action('rest_api_init', 'blocks_rest_endpoint');
function blocks_rest_endpoint()
{
  register_rest_route('block/v1', '/latest-posts', [
    'method' => 'GET',
    'callback' => 'blocks_return_data'
  ]);
}

Теперь то, что он будет выводить(имеется в виду, что получит перешедший по этому пути)

<?php
function blocks_return_data()
{
    $category = isset($_GET['cat']) ? absint($_GET['cat']) : 0;
    $count = isset($_GET['count']) ? absint($_GET['count']) : 5;

    return json_encode(blocks_get_latest_posts($category, $count));
}

function blocks_get_latest_posts($category, $count)
{
    $result = [];
    $posts = get_posts([
      'numberposts' => $count,
      'category' => $category
    ]);

    foreach ($posts as $key => $value) {
        $result[] = [
          'title' => get_the_title($value->ID),
          'excerpt' => get_the_excerpt($value->ID),
          'link' => get_permalink($value->ID),
          'src' => get_the_post_thumbnail_url($value->ID, 'full'),
          'id'  => $value->ID
        ];
    }

    return $result;
}

и в конце, зарегистрируем шорткод

<?php
add_shortcode('gutenberg-block-latest-posts', 'blocks_shortcode');
function blocks_shortcode($atts)
{
    $atts = shortcode_atts([
      'count' => 5,
      'cat' => array_shift(array_keys(blocks_get_categories())),
      'thumb' => 1
    ], $atts);

    $posts = blocks_get_latest_posts(absint($atts['cat']), absint($atts['count']));

    ob_start(); ?>
    <div class="latest-posts">
      <?php if (!empty($posts)): ?>
        <?php foreach ($posts as $key => $value): ?>
          <div class="post-<?php echo $value['id']; ?> row">
            <?php if ($atts['thumb'] && !empty($value['src'])): ?>
              <div class="thumbnail">
                <img src="<?php echo $value['src'] ?>" alt="<?php echo $value['title'] ?>">
              </div>
            <?php endif; ?>
            <div class="post-content">
              <a href="<?php echo $value['link'] ?>">
                <h2><?php echo $value['title'] ?></h2>
              </a>
              <p><?php echo $value['excerpt'] ?></p>
            </div>
          </div>
        <?php endforeach; ?>
      <?php endif; ?>
    </div>
    <?php
    wp_reset_postdata();

    return ob_get_clean();
}

Вот и весь бэк-энд блока

Frontend блока

Создадим js-файл по ранее указанному пути и, во избежание конфликтов с другими, сделаем замыкание. Замыкание выглядит как анонимная само исполняющаяся функция

(function(blocks, element, i18n, editor, data) {
    // code
})(
  window.wp.blocks,
  window.wp.element,
  window.wp.i18n,
  window.wp.editor,
  window.glp
);

В нижних скобках указаны те объекты, которые нужно “впустить”, сверху – под какими именами их использовать в порядке соответствия. Далее, для удобства(поймете после компиляции файла), нужно “вытянуть” некоторые методы с объектов

  const { createElement } = element;
  const { __ } = i18n;
  const { registerBlockType } = blocks;
  const { InspectorControls } = editor;
  const { BlockControls } = editor;

Далее, зарегистрируем блок редактора, его описания и атрибуты, коими будем манипулировать

  registerBlockType('block/gutenberg-latest-posts', {
      title: __('Latest Posts'),
      icon: 'dashicons-excerpt-view',
      category: 'common',
      attributes: {
        thumb: {
          type: 'integer',
          default: 1
        },
        count: {
          type: 'integer',
          default: 5
        },
        category: {
          type: 'integer',
          default: Object.keys(data.categories)[0]
        },
        checked: {
          type: 'bool',
          default: true
        },
        posts:  {
          type: 'array',
          default: []
        }
      }
  }
});

поля title и icon интуитивно понятные(есть еще и другие, необязательные), скажу только, что category это блок, где будет отображен блок(блоки по умолчанию ). Чтобы создать свою категорию добавь следующий PHP-код

<?php
function my_plugin_block_categories( $categories, $post ) {
    if ( $post->post_type !== 'post' ) {
        return $categories;
    }
    return array_merge(
        $categories,
        array(
            array(
                'slug' => 'my-category',
                'title' => __( 'My category', 'my-plugin' ),
                'icon'  => 'wordpress',
            )
    );
}
add_filter( 'block_categories', 'my_plugin_block_categories', 10, 2 );

Отдельно упомяну об атрибутах – из-за строгого отношения к типам данных, чтобы булевое значение не сохранить в БД; поэтому, приходится булевое ставить в зависимость от других типов, значение которых можно сохранить. Так у меня, выбор отображения изображения поста происходит чекбоксом(атрибут checked), состояние которого возвращается в типе bool. Чтобы сохранять это состояние, я ввел доп.атрибут в типе integer(thumb), значение которого в полной зависимостти от checked.

Осталось определить 2 метода, которые должны возвращать HTML-разметку имеющую по контейнеру. Первый(edit) отвечает за разметку в редакторе блоков, второй(save) – за то, что будет сохранено в БД. Начнем с первого(полный код, написанный мною)

      edit: ({attributes, setAttributes}) => {
        function Item(props) {
          return (
            <div class={ 'row post-' + props.props.id }>
              { (() => {
                if (attributes.thumb && props.props.src.length) {
                  return (
                    <div class="thumbnail">
                      <img src={ props.props.src } alt={ props.props.title }/>
                    </div>
                  );
                }
              })() }
              <div class="post-excerpt">
                <a href={ props.props.link } onClick={ abort }><h3>{ props.props.title }</h3></a>
                <p>{ props.props.excerpt }</p>
              </div>
            </div>
          );
        }
        function setCount(event) {
          setAttributes({count:parseInt(event.target.value)});
          setPosts(attributes.category, event.target.value);
        }
        function setCategory(event) {
          setAttributes({category:parseInt(event.target.value)});
          setPosts(event.target.value, attributes.count);
        }
        function setThumb(event) {
          if (event.target.checked) {
            setAttributes({
              thumb: 1,
              checked: true
            });
          } else {
            setAttributes({
              thumb: 0,
              checked: false
            });
          }
        }
        function abort(event) {
          event.preventDefault();
        }
        function setPosts(category, count) {
          var xhr = new XMLHttpRequest();
          xhr.open('GET', data.restURL + '?cat=' + category + '&count=' + count);

          xhr.onload = function () {
            setAttributes({posts:JSON.parse(xhr.responseText)});
          };

          xhr.send();
        }
        return (
          <div className={ attributes.className }>
            <BlockControls>
              <h3>{ __('Latest Posts') }</h3>
            </BlockControls>
            <InspectorControls>
              <p>
                <label>{ __('Posts Count') }</label><br/>
                <input type="number" value={ attributes.count } onChange={ setCount } min="1"/>
              </p>
              <p>
                <label>{ __('Posts Category') }</label><br/>
                  { (() => {
                    let option = Object.keys(data.categories).map((i) => {
                      return (
                        <option value={ i }>{ data.categories[i] }</option>
                      );
                    });
                    return (
                      <select value={ attributes.category } onChange={ setCategory }>
                        { option }
                      </select>
                    )
                  })() }
              </p>
              <p>
                <label>
                  <input type="checkbox" checked={ attributes.checked } onChange={ setThumb }/>
                  { __('Show Thumbnail') }
                </label>
              </p>
            </InspectorControls>
              { (() => {
                if (!attributes.posts.length) {
                  setPosts(attributes.category, attributes.count);
                }
                let items = attributes.posts.map((post) => {
                  return (
                    <Item props={ post }/>
                  );
                });
                return (
                  <div class="preview">
                    { items }
                  </div>
                );
              })() }
          </div>
        );
      }

немного о написанном: функции setCount, setCategory и setThumb – для изменения состояния атрибутов; Item и ее вызов кодом <Item /> – чисто реактовский прикол; setPosts получает список постов по нашему маршруту, и устанавливает его в атрибут posts. BlockControls и InspectorControls – методы объекта wp.editor: первый размещает внутреннюю разметку в верхней панели(toolbar) блока, второй – в боковой панели.

И, наконец-то, edit. Он очень прост, если бы разрабатываемый блок был стационарен – он возвращал бы такую же разметку, как и основное поле блока

      save: ({attributes}) => {
        return (
          <div class="latest-posts-block">
            [gutenberg-block-latest-posts cat="{ attributes.category }" count="{ attributes.count }" thumb="{ attributes.thumb }"]
          </div>
        );
      }

но поскольку он динамичен – содержит мой шорткод. Обратите внимание, поскольку результатом должна быть HTML-разметка – я обернул шорткод в тег.

Заключение

После компиляции js был получен код регистрации нового блока. Забыл сказать в основном теле статьи – особенностью react есть то, что он рендерит по фреймам, а не по клику. Из этого следует, что любое действие следует “запирать” в функцию. Весь код выполненного тестового лежит здесь.

Шаблон страницы записи WordPress

Все страницы сайта – это PHP шаблоны, содержащие HTML разметку с PHP тегами. Здесь будет рассмотрено создание шаблона страницы для отдельной записи – начиная от вордпресс цикла и до построения элементов навигации…

Содержание

Что представляет собой запись?

Каждая запись это отдельный представитель типа поста. Из коробки, есть 2 типа постов – страницы и записи; у каждой свои приколы по отображению – у страниц шаблоны для отображения, записей – форматы

шаблоны и форматы
1 – шаблоны страниц; 2 – форматы записей

Для создания шаблона страницы, в начало файла достаточно добавить комментарий

<?php
// Template Name: TemplateName

с форматами постов все немного сложнее…

Чтобы активировать возможность выбора формата, в functions.php на экшн after_setup_theme функцию со следующим содержимым

<?php
	add_theme_support(
		'post-formats',
		array(
			'aside',
			'image',
			'video',
			'quote',
			'link',
			'gallery',
			'audio',
		)
	);

Данный код содержит все допустимые форматы для постов; чтобы получить формат текущего поста используйте функцию get_post_format без аргументов, если ты внутри цикла(о нем позже), или с указанием ID поста.

При создании шаблона для своего типа записей – движок позволяет использовать только схему с форматами. По наименованию: для страниц с заголовком требований нет(если стандартный шаблон, без заголовка – page.php). Для постов и нестандартных типов записей – схема такова single-{post_type}.php, ну или single.php для всех типов кроме страниц(page).

WordPress циклы

Будь-то страница или любой другой тип записи(с условием, что он публичен – смотрите “Создаем свой тип записи. Метадата, роли пользователей, таксономии“) его вывод будет начат с цикла. В принципе, тип записей может быть и непубличным, но тогда его нужно будет принудительно доставать, что, я считаю, нехорошо. Итак, цикл(иногда его называют loop, поскольку это перевод) будет выглядеть так

<?php
if (have_posts()) {
    while (have_posts()) {
        the_post();
        // post content
    }
}

Естественно, что в начале выводится шапка(get_header) и подвал(get_footer) в конце. Касательно наполнения цикла – принято подключать кусочек шаблона(отдельный файл) при помощи get_template_part($patth), содержащий разметку страницы.

Элементы страницы

Здесь я рассмотрю основные элементы сингл-поста, которые применимы как к записям, так и страницам и прочим типам.

Изображение записи

Для начала – нужно включить их поддержку – это делает следующий код

<?php
add_action( 'after_setup_theme', 'themeslug_setup_theme' );
function themeslug_setup_theme(){
	add_theme_support( 'post-thumbnails' );
}

После этого, на странице редактирования записи появиться такой метабокс

thumbnail metabox Шаблон страницы записи WordPress

Теперь о том, как сохраняется загруженное изображение. По умолчанию, при сохранении , сохраняется оригинал и три нарезанных картинки из оригинала. Перейдя по “Settongs > Media” размеры этих изображений можно менять. Чтобы отключить нарезку достаточно выставить размеры в 0. Также, можно задать свой размер для кадрирования

<?php
add_action( 'after_setup_theme', 'custom_size' );
function custom_size() {
	add_image_size( 'custom-size', 100, 100 );
}

Теперь мы имеем 2 варианта по получению установленного изображения; первый – это получение url на оригинал изображения; второй – получение всего img-тега

<?php
// Получение url изображения 
$src = esc_url(get_the_post_thumbnail_url());
// вывод url изображения
the_post_thumbnail_url();
// Получение img-тега
$img = get_the_post_thumbnail();
// вывод img-тега
the_post_thumbnail();

Приведенный выше код работает только внутри вордпресс-цикла, иначе, в качестве первого аргумента, следует указать ID поста. Но функции вывода работают только в цикле. Размеры кадров я упомянул в предыдущем абзаце к тому, что в данных функциях(получение во втором, вывод первым) можно указывать в виде аргумента название размеров. Стандартно full(оригинал), large(1024px*1024px), medium(300px*300px) и thumbnail(150px*150px). Также, вместо строки с названием размера, можно указать массив с шириной и высотой; при этом, при первой загрузке страницы с новым размером, будет создан и сохранен новый кадр.

Касательно получения и выведения img-тега. Последним аргументом в функцию можно передать массив атрибутов тега. Поскольку, в данной функции задается дефолтное значение этого аргумента, то задать можно только такие атрибуты – src, class и alt.

Таксономии

Будь-то стандартные, либо же кастомные таксономии, древовидные они или нет – вывод их одинаков

<?php
$terms = wp_get_post_terms( $post_id, $taxonomy, $args );

Первые 2 аргумента понятны, третий это поля, которые будут возвращены; по умолчанию all, возможные значения – names ids.

В случаи, если нужны особые условия применить к получаемым данным, можно применить

<?php
$terms = wp_get_object_terms($object_ids, $taxonomies, $args);

здесь $object_ids это ID записи, а вот на $args, пожалуй, поподробнее:

orderby -поле, по которому сортировать порядок вывода:

  • поиск в полях терминов – term_id, name, slug, term_group;
  • по полям таксономии терминов – id(поле term_taxonomy_id в таблице БД), description, parent, count(количество терминов в таксономии);
  • среди полей таблицы term_relationships – term_order;
  • по полям меты – meta_value_num(количеству полей meta_value) и по значению meta_key

Можно и вообще отключить сортировку установив значение в ‘none’. Ключ order устанавливает порядок сортировки(ASK/DESC).

Также, в этом массиве можно задать множество других параметров поиска. К примеру, наличие/отсутствие/равенство метаполей, вложенность, древовидность и т.д. Получаем ссылку на архив термина

<?php
$url = esc_url(get_term_link( $term, $taxonomy ));

Контент и метадата

Для начала выведем заголовок записи

<?php
// вывод
the_title('<h1>', '</h1>');
// получение в переменную
$title = esc_html(get_the_title());

В случаи с выведением на страницу, указывать аргументы не обязательно, но в такой записи заголовок будет обрамлен H1-тегом. Не много о том, почему не стоит вытягивать post_title с обьекта WP_Post – потому, что запись может быть личной или защищенной паролем; при правильном выводе эти статусы являются частью заголовка, при неправильном – этот функционал придется дублировать… а это плохо!

Что касается контента, там все аналогично(почти)

<?php
// вывод
the_content();
// получение в переменную
$content = get_the_content();

Опять таки, можно вытянуть контент с обьекта WP_Post, но в функции get_the_content происходит ряд об робок другими фильтрами…

Следующее, это вывод/получение даты, а также ссылки на ее архив

<?php
$format = get_option( 'date_format' );
//вывод
the_date( $format, $before, $after );
// получение
$date = the_date( $format, $before, $after, false );
// или
$date = get_the_date( $format, $post );
// ссылка на архив
$url = esc_url(get_day_link( $year, $month, $day ));

Здесь, как и в случаи с заголовком, $before и $after это текст(включая html) до и после даты.

Пару слов о метадате поста. Вся дополнительная информация к посту – это метадата. Чтоб ее достать достаточно знать метаключ за коим она храниться

<?php
$metadata = get_post_meta($post_id, $metakey, true);

поскольку одинаковых метаключей к одной записи может быть много, то данные извлекаются в виде массива; если поле одно – можно сразу его извлечь, указав true третьим аргументом – иначе, по умолчанию, будет false.

Навигация

Под контентом поста принято делать ссылки на предыдущий и следующий посты. Делается это следующим кодом

<?php
$nav = get_the_post_navigation($args);

Переменная будет содержать следующую разметку

<nav class="navigation post-navigation" role="navigation" aria-label="Posts">
	<h2 class="screen-reader-text">Post navigation</h2>
	<div class="nav-links">
	    <div class="nav-previous">
	        <a href="{prevPostLink}" rel="prev">Prev Post Title</a>
	    </div>
    	<div class="nav-next">
    	    <a href="{nextPostLink}" rel="next">Next Post Title</a>
    	</div>
    </div>
</nav>

Через аргумент функции моно кастомизировать только атрибуты class у и aria-label тега nav, а также то, что в ссылке. Для этого в массиве $args есть ключи prev_text(может содержать html-теги), next_text(тоже), aria_label и class.

Если же такой уровень кастомизации не достаточен и нужна своя разметка – делаем следующее: получаем а-теги

<?php
$prevLink = get_previous_post_link();
$nextLink = get_next_post_link();

Комментарии

В вордпресс принято поключать комментарии таким образом

<?php
if ( comments_open() || get_comments_number() ) :
	comments_template();
endif;

Здесь проверяется открытые ли комментарии у поста и их наличие. При выполнении хотя б одного условия – будут загружены стандартные форма комментирования и список комментов, которые можно перезаписать в файле comments.php темы.

Рекомендую сделать также, это избавит от некоторых проблем. Дальше, создаем файл comments.php и пишем в него.

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

Здесь ситуация похожа на ситуацию с навигацией: форму комментария строит отдельная функция.

<?php
comment_form( $args, $post_id );

внутри цикла $post_id можно пропустить. При пустом $args получим следующий html

<div id="respond" class="comment-respond">
	<h3 id="reply-title" class="comment-reply-title">Leave a Reply <small><a rel="nofollow" id="cancel-comment-reply-link" href="{cancelReplyLink}" style="display:none;">Cancel reply</a></small></h3>
	<form action="{actionLink}" method="post" id="commentform" class="comment-form" novalidate="">
        <!-- if current user logged in -->
	    <p class="logged-in-as">
	        <a href="{profileLink}" aria-label="Logged in as admin. Edit your profile.">Logged in as admin</a>. <a href="nonce=dc4f1aa958">Log out?</a>
	    </p>
	    <!-- endid -->
    	<p class="comment-form-comment">
    	    <label for="comment">Comment</label>
    	    <textarea id="comment" name="comment" cols="45" rows="8" maxlength="65525" required="required"></textarea>
    	</p>
        <!-- if current user not logged in -->
        <p class="comment-form-author">
            <label for="author">Name <span class="required">*</span></label> 
            <input id="author" name="author" type="text" value="" size="30" maxlength="245" required="required">
        </p>
        <p class="comment-form-email">
            <label for="email">Email <span class="required">*</span></label>
            <input id="email" name="email" type="email" value="" size="30" maxlength="100" aria-describedby="email-notes" required="required">
        </p>
        <p class="comment-form-url">
            <label for="url">Website</label> 
            <input id="url" name="url" type="url" value="" size="30" maxlength="200">
        </p>
        <p class="comment-form-cookies-consent">
            <input id="wp-comment-cookies-consent" name="wp-comment-cookies-consent" type="checkbox" value="yes"> <label for="wp-comment-cookies-consent">Save my name, email, and website in this browser for the next time I comment.</label>
        </p>
        <!-- endif -->
    	<p class="form-submit">
    	    <input name="submit" type="submit" id="submit" class="submit" value="Post Comment">
    	    <input type="hidden" name="comment_post_ID" value="10" id="comment_post_ID">
            <input type="hidden" name="comment_parent" id="comment_parent" value="0">
        </p>
        <input type="hidden" id="_wp_unfiltered_html_comment_disabled" name="_wp_unfiltered_html_comment" value="f6a52e0808"><script>(function(){if(window===window.parent){document.getElementById('_wp_unfiltered_html_comment_disabled').name='_wp_unfiltered_html_comment';}})();</script>
    </form>
</div>

Но, в отличие от навигации, здесь можно провести полную кастомизацию через функцию. Для этого заполним массив $args:

  • ключ fields – массив шаблонов(начиная с тега р), содержащий поля формы комментария за ключами author, email и url;
  • comment_field – содержит шаблон, непосредственно, поля ввода комментария;
  • must_log_in – текст для не залогиненных пользователей при обязательном логировании, чтоб оставить коммент;
  • logged_in_as – текст для залогиненного пользователя;
  • submit_field – шаблон поля отправки формы.

В принципе, для полной кастомизации этого достаточно, однако, в аргументе есть еще дополнительные поля для более тонкой настройки… и не только вида.

Немного о добавлении своих полей в форму комментирования: для добаления поля – фильтром comment_form_fields изменяй массив полей

<?php
add_filter('comment_form_fields', 'custom_comment_form_field');
function custom_comment_form_field($comment_fields)
{
    $custom_field['custom_field'] = '<p><label>My query<input name="my_query"></label></p>';
    // insert $custom_field after name(index = 1)
    return array_merge(
        array_slice($comment_fields, 0, 2),
        $custom_field,
        array_slice($comment_fields, 2)
    );
}

после этого экшном wp_insert_comment нужно сохранить данное поле

<?php
add_action('wp_insert_comment', 'wp_insert_custom_comment_field', 10, 2);
function wp_insert_custom_comment_field($id, $comment)
{
    if (isset($_POST['my_query'])) {
        update_comment_meta($id, 'my_query', sanitize_text_field($_POST['my_query']));
    }
}
Список комментариев

Следующая вещь, которая, по сути, есть продолжением формы комментариев – это список ранее оставленных комментариев. Он также выводится функцией

<?php
wp_list_comments($args, $comments);

При использовании стандартной схемы аргумент $comments указывать не нужно. Иначе, $comments = get_comments() в котором нужно формировать свой массив аргументов. При пустом $args wp_list_comments выведет следующую разметку для каждого коммента

<li id="comment-1" class="comment even thread-even depth-1">
	<article id="div-comment-1" class="comment-body">
		<footer class="comment-meta">
			<div class="comment-author vcard">
				<img alt="" src="{avatar}" srcset="{avatar}" class="avatar avatar-32 photo" height="32" width="32" loading="lazy">						
				<b class="fn"><a href="https://wordpress.org/" rel="external nofollow ugc" class="url">A WordPress Commenter</a></b> 
				<span class="says">says:</span>					
			</div><!-- .comment-author -->

			<div class="comment-metadata">
				<a href="{linkToComment}">
					<time datetime="{commentTime}">
						Comment Time						
					</time>
				</a>
				<span class="edit-link">
					<a class="comment-edit-link" href="{linkToEditComment}">Edit</a>
				</span>					
			</div><!-- .comment-metadata -->

		</footer><!-- .comment-meta -->
			
		<div class="comment-content">
			<p>Comment Text</p>
		</div><!-- .comment-content -->

		<div class="reply">
		    <a rel="nofollow" class="comment-reply-link" href="{linkToReply}" data-commentid="1" data-postid="1" data-belowelement="div-comment-1" data-respondelement="respond" data-replyto="Reply to A WordPress Commenter" aria-label="Reply to A WordPress Commenter">Reply</a>
		</div>			
	</article><!-- .comment-body -->
</li>

Здесь самый широкий, даже, наверное, излишний, способ кастомизации – и все доступно через функцию:

  • max_depth – максимально разрешенная вложенность комментов;
  • style – стиль вывода дерева – ul, ol(по умолчанию) или div. Данный аргумент имеет значение для вложенных комментариев, поскольку сама функция должна быть при вызове обнесенная контейнером отдельно;
  • type – отображаемый тип комментариев;
  • per_page – в случаи необходимости пагинации – количество комментариев на странице;
  • page – страница пагинации коммента;
  • avatar_size – размер аватара комментатора
  • callback – функция-строитель каждого комментария, без закрывающего тега;
  • end-callback – строитель закрывающего тега;
  • walker экземпляр класса-строителя дерева комментариев.

Есть еще много ключей для “мелкой настройки” этой функции, но главное уже приведено. По поводу того, что функции открывающего и закрывающего тега разделены – тут, как и в меню, есть вложенность, и для ее реализации сделано так.

Сайдбар

Сайдбар – это место для вывода виджетов, виджет-зона. У нее, также как и у комментов, свой стандарт для выведения. В шаблоне страницы ставят такой код

<?php
get_sidebar($slug);

данный код подключит sidebar.php из темы; если $slug не пустая строка, то подключит sidebar-{$slug}.php

<?php
if (is_active_sidebar($slug)) {
    dynamic_sidebar($slug);
}

$slug здесь это идентификатор виджет-зоны, который был указан при ее регистраци в функции register_sidebar().

Заключение

Рассмотрены все стандартные элементы шаблон страницы записи WordPress. О чем стоит упомянуть еще – так это о том, что в обертке каждого поста должны быть теги

<article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
    <!-- post content -->
</article>

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

Навигационное меню в WordPress

Навигационное меню это один из 6-и типов навигации представленных в вордпресс. Поскольку 3 это часть “архитектурного ансамбля” других элементов – расскажу о них в будущих статьях; оставшиеся 2 типа – это виджеты со списками последних записей и различных архивов. О них, я считаю, и говорить не стоит…

Содержание

Подготовительные работы

Прежде, чем вызывать в шаблоне менюху, нужно зарегистрировать меню в системе. Да, в любом шаблоне это уже сделано, но ведь я рассматриваю случай с разработкой собственной! Итак, код регистрации(в functions.php темы)

<?php
add_action( 'after_setup_theme', 'theme_register_nav_menu' );
function theme_register_nav_menu() {
	register_nav_menu( 'primary', 'Primary Menu' );
}

Данным кодом я регнул локацию для вывода меню с идентификатором “primary” и именем “Primary Menu”. В случаи регистрации множества локаций для меню, код будет таким

<?php
add_action( 'after_setup_theme', 'theme_register_nav_menus' );
function theme_register_nav_menus(){
	register_nav_menus( [
		'primary' => 'Primary Menu',
		'secondary' => 'Secondary Menu'
	] );
} );

Результатом регистрации будет появление дополнительного чекбокса в зоне Display location в Menu Settings на странице Appearance > Menus

Display location в настройках меню

Все, следующий шаг – это, непосредственно, вывод самого меню.

Вывод меню

Вывод всего дерева меню производится вызовом одной функции(неожиданно, да?). Вот он:

<?php
wp_nav_menu( [
	'theme_location'  => '',
	'menu'            => '', 
	'container'       => 'div', 
	'container_class' => '', 
	'container_id'    => '',
	'container_aria_label' => '',
	'items_wrap' => '<ul id="%1$s" class="%2$s">%3$s</ul>',
	'menu_class'      => 'menu', 
	'menu_id'         => '',
	'echo'            => true,
	'fallback_cb'     => 'wp_page_menu',
	'before'          => '',
	'after'           => '',
	'link_before'     => '',
	'link_after'      => '',
	'depth'           => 0,
	'walker'          => '',
] );

массив аргументов необязателен, но тогда будет выведено первое непустое меню.

Теперь по аргументам… theme_location идентификатор зоны регистрации меню(если равно primary из примера реги, будет выведено меню, закреплённое за этой зоной в админке – выбран чекбокс). В menu будет слаг, название или id созданного меню.

Ключи container, container_class, container_id и container_aria_label – это тег обертки меню и ее атрибуты class, id и aria-label соответственно. В items_wrap, menu_class, menu_id хранятся разметка для обертки списка и ее атрибуты. Если ты используешь свой шаблон обертки – обязательно делай плейсхолдер %3$s, поскольку именно он будет заменен на пункты списка.

Каждый пункт меню – это ссылка, тег а; before и after – это содержимое перед и после ссылки. link_before и link_after – содержимое до и после текста ссылки(между открывающим и закрывающим тегами а).

Также, есть настройки, не связанные непосредственно с постройкой дерева – fallback_cb, depth и walker. Первая – это название функции, которая будет вызвана при отсутствии меню в БД; вторая – разрешенная глубина меню, третья – класс, который будет строить само меню(нужно указывать объект класса, а не строку). О нем то мы и поговорим более подробно.

Класс Walker. Кастомизация базового шаблона меню

По умолчанию, функция wp_nav_menu использует родной класс Walker_Nav_Menu расширяющий класс Walker. По сути, класс Walker_Nav_Menu содержит методы-шаблону постройки пунктов меню и оберток для них, а родительский класс содержит всю логику посстроения скелета по шаблонам ребенка. Для кастомизации шаблонов, в нем(классе), как и во всем вордпресс, предусмотрены фильтры и экшны; предлагая их кратко рассмотреть.

<?php
class Walker_Nav_Menu extends Walker {
	/**
	 * What the class handles.
	 *
	 * @since 3.0.0
	 * @var string
	 *
	 * @see Walker::$tree_type
	 */
	public $tree_type = array( 'post_type', 'taxonomy', 'custom' );

	/**
	 * Database fields to use.
	 *
	 * @since 3.0.0
	 * @todo Decouple this.
	 * @var array
	 *
	 * @see Walker::$db_fields
	 */
	public $db_fields = array(
		'parent' => 'menu_item_parent',
		'id'     => 'db_id',
	);

	/**
	 * Starts the list before the elements are added.
	 *
	 * @since 3.0.0
	 *
	 * @see Walker::start_lvl()
	 *
	 * @param string   $output Used to append additional content (passed by reference).
	 * @param int      $depth  Depth of menu item. Used for padding.
	 * @param stdClass $args   An object of wp_nav_menu() arguments.
	 */
	public function start_lvl( &$output, $depth = 0, $args = null ) {
		if ( isset( $args->item_spacing ) && 'discard' === $args->item_spacing ) {
			$t = '';
			$n = '';
		} else {
			$t = "t";
			$n = "n";
		}
		$indent = str_repeat( $t, $depth );

		// Default class.
		$classes = array( 'sub-menu' );

		/**
		 * Filters the CSS class(es) applied to a menu list element.
		 *
		 * @since 4.8.0
		 *
		 * @param string[] $classes Array of the CSS classes that are applied to the menu `<ul>` element.
		 * @param stdClass $args    An object of `wp_nav_menu()` arguments.
		 * @param int      $depth   Depth of menu item. Used for padding.
		 */
		$class_names = join( ' ', apply_filters( 'nav_menu_submenu_css_class', $classes, $args, $depth ) );
		$class_names = $class_names ? ' class="' . esc_attr( $class_names ) . '"' : '';

		$output .= "{$n}{$indent}<ul$class_names>{$n}";
	}

	/**
	 * Ends the list of after the elements are added.
	 *
	 * @since 3.0.0
	 *
	 * @see Walker::end_lvl()
	 *
	 * @param string   $output Used to append additional content (passed by reference).
	 * @param int      $depth  Depth of menu item. Used for padding.
	 * @param stdClass $args   An object of wp_nav_menu() arguments.
	 */
	public function end_lvl( &$output, $depth = 0, $args = null ) {
		if ( isset( $args->item_spacing ) && 'discard' === $args->item_spacing ) {
			$t = '';
			$n = '';
		} else {
			$t = "t";
			$n = "n";
		}
		$indent  = str_repeat( $t, $depth );
		$output .= "$indent</ul>{$n}";
	}

	/**
	 * Starts the element output.
	 *
	 * @since 3.0.0
	 * @since 4.4.0 The {@see 'nav_menu_item_args'} filter was added.
	 *
	 * @see Walker::start_el()
	 *
	 * @param string   $output Used to append additional content (passed by reference).
	 * @param WP_Post  $item   Menu item data object.
	 * @param int      $depth  Depth of menu item. Used for padding.
	 * @param stdClass $args   An object of wp_nav_menu() arguments.
	 * @param int      $id     Current item ID.
	 */
	public function start_el( &$output, $item, $depth = 0, $args = null, $id = 0 ) {
		if ( isset( $args->item_spacing ) && 'discard' === $args->item_spacing ) {
			$t = '';
			$n = '';
		} else {
			$t = "t";
			$n = "n";
		}
		$indent = ( $depth ) ? str_repeat( $t, $depth ) : '';

		$classes   = empty( $item->classes ) ? array() : (array) $item->classes;
		$classes[] = 'menu-item-' . $item->ID;

		/**
		 * Filters the arguments for a single nav menu item.
		 *
		 * @since 4.4.0
		 *
		 * @param stdClass $args  An object of wp_nav_menu() arguments.
		 * @param WP_Post  $item  Menu item data object.
		 * @param int      $depth Depth of menu item. Used for padding.
		 */
		$args = apply_filters( 'nav_menu_item_args', $args, $item, $depth );

		/**
		 * Filters the CSS classes applied to a menu item's list item element.
		 *
		 * @since 3.0.0
		 * @since 4.1.0 The `$depth` parameter was added.
		 *
		 * @param string[] $classes Array of the CSS classes that are applied to the menu item's `<li>` element.
		 * @param WP_Post  $item    The current menu item.
		 * @param stdClass $args    An object of wp_nav_menu() arguments.
		 * @param int      $depth   Depth of menu item. Used for padding.
		 */
		$class_names = join( ' ', apply_filters( 'nav_menu_css_class', array_filter( $classes ), $item, $args, $depth ) );
		$class_names = $class_names ? ' class="' . esc_attr( $class_names ) . '"' : '';

		/**
		 * Filters the ID applied to a menu item's list item element.
		 *
		 * @since 3.0.1
		 * @since 4.1.0 The `$depth` parameter was added.
		 *
		 * @param string   $menu_id The ID that is applied to the menu item's `<li>` element.
		 * @param WP_Post  $item    The current menu item.
		 * @param stdClass $args    An object of wp_nav_menu() arguments.
		 * @param int      $depth   Depth of menu item. Used for padding.
		 */
		$id = apply_filters( 'nav_menu_item_id', 'menu-item-' . $item->ID, $item, $args, $depth );
		$id = $id ? ' id="' . esc_attr( $id ) . '"' : '';

		$output .= $indent . '<li' . $id . $class_names . '>';

		$atts           = array();
		$atts['title']  = ! empty( $item->attr_title ) ? $item->attr_title : '';
		$atts['target'] = ! empty( $item->target ) ? $item->target : '';
		if ( '_blank' === $item->target && empty( $item->xfn ) ) {
			$atts['rel'] = 'noopener noreferrer';
		} else {
			$atts['rel'] = $item->xfn;
		}
		$atts['href']         = ! empty( $item->url ) ? $item->url : '';
		$atts['aria-current'] = $item->current ? 'page' : '';

		/**
		 * Filters the HTML attributes applied to a menu item's anchor element.
		 *
		 * @since 3.6.0
		 * @since 4.1.0 The `$depth` parameter was added.
		 *
		 * @param array $atts {
		 *     The HTML attributes applied to the menu item's `<a>` element, empty strings are ignored.
		 *
		 *     @type string $title        Title attribute.
		 *     @type string $target       Target attribute.
		 *     @type string $rel          The rel attribute.
		 *     @type string $href         The href attribute.
		 *     @type string $aria_current The aria-current attribute.
		 * }
		 * @param WP_Post  $item  The current menu item.
		 * @param stdClass $args  An object of wp_nav_menu() arguments.
		 * @param int      $depth Depth of menu item. Used for padding.
		 */
		$atts = apply_filters( 'nav_menu_link_attributes', $atts, $item, $args, $depth );

		$attributes = '';
		foreach ( $atts as $attr => $value ) {
			if ( is_scalar( $value ) && '' !== $value && false !== $value ) {
				$value       = ( 'href' === $attr ) ? esc_url( $value ) : esc_attr( $value );
				$attributes .= ' ' . $attr . '="' . $value . '"';
			}
		}

		/** This filter is documented in wp-includes/post-template.php */
		$title = apply_filters( 'the_title', $item->title, $item->ID );

		/**
		 * Filters a menu item's title.
		 *
		 * @since 4.4.0
		 *
		 * @param string   $title The menu item's title.
		 * @param WP_Post  $item  The current menu item.
		 * @param stdClass $args  An object of wp_nav_menu() arguments.
		 * @param int      $depth Depth of menu item. Used for padding.
		 */
		$title = apply_filters( 'nav_menu_item_title', $title, $item, $args, $depth );

		$item_output  = $args->before;
		$item_output .= '<a' . $attributes . '>';
		$item_output .= $args->link_before . $title . $args->link_after;
		$item_output .= '</a>';
		$item_output .= $args->after;

		/**
		 * Filters a menu item's starting output.
		 *
		 * The menu item's starting output only includes `$args->before`, the opening `<a>`,
		 * the menu item's title, the closing `</a>`, and `$args->after`. Currently, there is
		 * no filter for modifying the opening and closing `<li>` for a menu item.
		 *
		 * @since 3.0.0
		 *
		 * @param string   $item_output The menu item's starting HTML output.
		 * @param WP_Post  $item        Menu item data object.
		 * @param int      $depth       Depth of menu item. Used for padding.
		 * @param stdClass $args        An object of wp_nav_menu() arguments.
		 */
		$output .= apply_filters( 'walker_nav_menu_start_el', $item_output, $item, $depth, $args );
	}

И еще… мало не забыл… немного о методах. Для строительства скелета, есть 4 метода: start_lvl и end_lvl – строят открывающий и закрывающий теги обертки вложенных меню; start_el и end_el – открывающий и закрывающий теги пункта меню.

Глянем фильтры

Буду описывать их по порядку встречи в коде. Первым мы встречаем фильтр “nav_menu_submenu_css_class”. Он расположен в методе start_lvl и отвечает за фильтрацию классов оберток дочерних оберток списков. Функции-фильтру передаются 3 параметра – массив классов, вложенность строящейся обертки и массив, переданный при вызове wp_nav_menu. В этом методе хуков больше нет, перейду к следующему.

Метод end_lvl в принципе не может содержать ничего меняющегося, соответственно – хуков он не содержит. Глянем следующий метод – start_el – он то уж содержит много хуков.

Первый хук который мы здесь видим – фильтр nav_menu_item_args. Как можно понять с его кода, предназначен он для фильтрации массива с функции строителя(wp_nav_menu). Фильтр принимает 3 аргумента: массив для фильтрации, объект данных о строящемся пункте меню и его вложенность. Следующий, тоже фильтр, nav_menu_css_class фильтрует классы у тега li, принимает уже 4 аргумента – массив классов, объект пункта, массив из строителя и вложенность. Следующим, идет фильтр атрибута id тега li. Он принимает те же аргументы, что и предыдущий фильтр с той лишь разницей, что вместо массива классов – строка с текущим id(строка, поскольку class`ов может быть много, а id один).

Следующий фильтр nav_menu_link_attributes фильтрует атрибуты тега а. Принимает он те же аргументы, что и фильтр выше, с разницей в место строки id массив атрибутов тега а. Затем идет общий фильтр the_title, которым можно изменить текст ссылки, исходя из текущего текста и id пункта меню. После общего фильтра, идет местный nav_menu_item_title фильтр анкора ссылки. Если честно – не знаю и не понимаю, зачем прилепили общий, ведь этот получает данные для фильтрации, включающие предыдущие; а именно те же, что и с классами, только в место массива классов текст ссылки.

Ну и последним фильтром класса(метод end_el как и end_lvl не содержит никаких данных) является фильтр всего пункта меню. Он, вполне ожидаемо, принимает те же аргументы, что предыдущий, только вместо строки текста передана строка с HTML разметкой пункта.

Создание своего шаблона меню

В принципе, я не знаю что нужно поместить в меню, чего б не можно было сделать фильтрами в дефолтном классе; может, чтоб не наращивать код и с точки зрения оптимизации – выиграть какую-то долю процента…

Но ладно, раз уж это сделать можно – почему об этом не рассказать?… Первым делом – идем в файл wp-includes/class-walker-nav-menu.php, копируем к нам в файл соответствующий класс и переименовываем его. Именно копируем – я то знаю, где-то в буковке ошибся и все – ошибка, ничего не работает… хотя, впрочем, можете и с нуля набрать… только прочти до конца!

Итак, допустим, я решил создать walker-класс который будет строить только такую разметку

<ul class="main-menu">
  <li class="menu-item">POINT 1
    <ul class="sub-menu depth1">
      <li class="menu-item">
        <img src="path/to/image.png" alt="">
        <a href="#">POINT 1.1</a>
      </li>
    </ul>
  </li>
  <li class="menu-item">
    <a href="#">POINT 2</a>
  </li>
</ul>

Первое, что можно заметить – наличие картинки, возможность выбора коей с админки пока не существует.

Безусловно, можно сделать кнопку у каждого пункта меню, которая бы открывала фрейм с медиатекой(как у миниатюры поста, к примеру); с целью укорочения этой статьи, я приделаю ввод id картинки с медиатеки

<?php
add_action('wp_nav_menu_item_custom_fields', 'action_function_name_6494', 10, 5);
function action_function_name_6494($item_id, $item, $depth, $args, $id)
{
    ?>
	<p class="field-thumbnail description description-thin">
		<label for="edit-menu-item-thumbnail-<?php echo $item_id; ?>">
			<?php _e('Thumbnail'); ?><br />
			<input type="number" id="edit-menu-item-thumbnail-<?php echo $item_id; ?>" class="widefat code edit-menu-item-thumbnail" name="menu-item-thumbnail[<?php echo $item_id; ?>]" value="<?php echo get_post_meta($item_id, '_item_thumbnail', 1); ?>" />
		</label>
	</p>
	<?php
}

Этот код выведет под каждым пунктом меню следующее

новое поле для ввода

но это еще не все. Для того, чтоб эту настройку сохранить – нужен дополнительный код. Я знаю, что каждый пункт меню хранится как запись с типом поста nav_menu_item; следовательно, настройка мета данное поста и и для его сохраниния нужно функцию повесить на экшн save_post_nav_menu_item(save_post_{post_type} в общем случаи)

<?php
add_action('save_post_nav_menu_item', 'save_nav_menu_item');

function save_nav_menu_item()
{
    if (isset($_POST['menu-item-thumbnail'])) {
        foreach ($_POST['menu-item-thumbnail'] as $key => $value) {
            add_post_meta($key, '_item_thumbnail', $value);
        }
    }
}

здесь я убрал проверки на возможности пользователя, типы данных и прочее, чтоб не убивать читабельность кода; но ты в своих проектах о них не забывай… Еще одна вещь – все это(настройку, но не меню) можно было бы сделать используя плагины.

Теперь время непосредственно walker-класса. Я не буду делать возможности фильтрации данных и максимально захардкоджу код класса в целях экономии места

<?php
class Walker_Nav_Menu_Thumb extends Walker
{
    public $tree_type = array( 'post_type', 'taxonomy', 'custom' );

    public $db_fields = array(
        'parent' => 'menu_item_parent',
        'id'     => 'db_id',
    );

    public function start_lvl(&$output, $depth = 0, $args = null)
    {
        $classes = join(' ', ['sub-menu', 'depth' . $depth]);
        $output .= '<ul class="' . $classes . '">';
    }

    public function end_lvl(&$output, $depth = 0, $args = null)
    {
        $output .= "</ul>";
    }

    public function start_el(&$output, $item, $depth = 0, $args = null, $id = 0)
    {
        $url = ! empty($item->url) ? $item->url : '';
        $link = $this->has_children ? $item->title : '<a href="' . $url . '">' . $item->title . '</a>';
        $img = get_post_meta($item->ID, '_item_thumbnail', 1) ? '<img src="' . wp_get_attachment_url(get_post_meta($item->id, '_item_thumbnail', 1)) . '"/>' : '';
        $output .= '<li class="menu-item">' . $img . $link;
    }

    public function end_el(&$output, $item, $depth = 0, $args = null)
    {
        $output .= "</li>";
    }
}

Вызов меню, с постройкой ранее указанной разметки, будет выглядеть так

<?php
wp_nav_menu([
	'theme_location' => 'primary',
	'container' => 0,
	'menu_class' => 'main-menu',
	'walker' => new Walker_Nav_Menu_Thumb
]);

Ты наверное заметил, что я “убил” в своем классе часть аргументов функции строителя, для публичных проектов так не делай… никогда.

Заключение

Рассмотрел способ создания кастомного меню. Также был рассмотрен базовый класс, который создает и меню; для примера, наведу код, коим можно сделать такие же изменения в коде

<?php
add_filter('nav_menu_submenu_css_class', 'my_nav_menu_submenu_css_class', 10, 3);
function filter_function_name_8769($classes, $args, $depth)
{
    $classes[] = 'depth' . $depth;

    return $classes;
}

add_filter('nav_menu_item_args', 'my_nav_menu_item_args', 10, 2);
function my_nav_menu_item_args($args, $item)
{
    if ($id = get_post_meta($item->ID, '_item_thumbnail', 1)) {
        $args['before'] = '<img src="' . wp_get_attachment_url($id) . '"/>';
    }

    return $args;
}

add_filter('nav_menu_link_attributes', 'my_nav_menu_link_attributes', 10, 4);
function my_nav_menu_link_attributes($atts, $item, $args, $depth)
{
    $atts = ['href' => in_array('menu-item-has-children', $item->classes) ? '' : $atts['href']];

    return $atts;
}

add_filter('nav_menu_css_class', 'my_nav_menu_css_class', 10, 4);
function my_nav_menu_css_class($classes)
{
    $classes[] = 'menu-item';

    return $classes;
}

как при кастомном классе, но используя базовый. Кстати, только заметил, что полного сходства добиться невозможно.

Источники

Создаем свой тип записи. Метадата, роли пользователей, таксономии

Из “коробки” вордпресс имеет 2 типа записей: посты и страницы. Не всегда этого достаточно… Расскажу, как добавить кастомный тип постов, таксономии к нему и метаданные. А также, создадим свои роли пользователей для операций с постами этого типа.

Содержание

Регистрируем тип и таксономию

Следуя традиции из кодекса вордпресс, зарегистрируем тип записи book и категории для нее book_cat. Для этого достаточно следующего кода

<?php
add_action('init', 'register_post_types');
function register_post_types()
{
    // регистрируем тип записи
    register_post_type('book');
    // регистрируем таксономию для типа записи
    register_taxonomy('book_cat', 'book');
}

По-поводу регистрации первой функции – все ясно-понятно – аргумент это слаг типа постов; по второй функции – первый аргумент это слаг таксономии, второй – к какому типу записей ее прикрепить, если таких типов несколько – укажи массив всех. В документации сказано, что второй аргумент при регистрации таксономии – это экраны, где выводятся данные таксономии, но, по-моему, мое определение ближе к сути.

Итак, данным выше кодом мы зарегистрировали тип постов, но смысл?.. все, что он(код) делает – создает запись о том, что такой тип существует; единственное, что ты можешь с ним сделать – получить его в вызове функции get_post_types()(ну и, соответственно, для таксономии get_taxonomies()).

Наполняем смыслами. Пункт админ-меню, форма создания/редактирования

Смыслы в процессе регистрации как типов так и таксономий, создают второй и третий аргументы функций, соответственно.

Для начала, проявим эти пункты в меню администратора – для этого допишем наш код до следующего состояния

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

<?php
add_action('init', 'register_post_types');
function register_post_types()
{
    // массив для типа записей
    $typeArray = [
      'label' => 'Book',
      'show_ui' => true,
      'show_in_menu' => true
    ];
    // массив для таксономий
    $taxArray = [
      'label' => 'Genres'
    ];
    // регистрируем тип записи
    register_post_type('book', $typeArray);
    // регистрируем таксономию для типа записи
    register_taxonomy('book_cat', 'book', $taxArray);
}
вид в меню админки при разных show_in_menu
1 – show_in_menu => ‘index.php’; 2 – show_in_menu => true

рассмотрим типы и таксономии отдельно…

Теперь о странице создания/редактировании поста. По умолчанию, будут доступны поля задания заголовка и поле редактора TinyMCE для контента. Чтобы добавить стандартные метабоксы, в массив $typeArray, в ключ supports впишите массив с идетификаторами всех необходимых меетабоксов: title, editor, author, thumbnail, excerpt, custom-fields, comments, revisions, page-attributes, post-formats. Для того, чтоб работал page-attributes нужно включить вложенность постов, т.е. hierarchical присвоить true.

С thumbnail и post-formats тоже есть своя особенность; их поддержку нужно включить следующим кодом

<?php
add_action('after_setup_theme', 'book_support');
function book_support()
{
    add_theme_support('post-thumbnails', ['book']);
    add_theme_support('post-formats', [ 'aside', 'gallery' ]);
}

Еще, малость не забыл, все тексты в меню, форме постов и в фронте сайта задаются в массиве labels… ну, если дефолтные названия не нравятся.

Дальнейшие настройки типов

Следующее, что я предлагаю включить – так это отображение записей моего типа на странице создания меню. Чтоб это сделать, достаточно в массив $typeArray вписать ключ show_in_nav_menus со значением true.

book nav menu

Кстати, как ты видишь, наша таксономия Genres была туда добавлена сразу же, при ее регистрации.

Затем, предлагаю включить посты этого типа в WP REST API; для этого ключу show_in_rest также нужно присвоить значение true. Как ты заметишь, это действие, также, включит редактор Гутенберга. Сам слаг в АПИ будет равен слагу типа поста, однако, его можно изменить в параметре rest_base. По умолчанию, обслуживать АПИ-запросы к этим постам будет WP_REST_Posts_Controller, но параметром rest_controller_class можно изменить(прочти “WP REST API(дефолтное) — взаимодействие с WP сайтом“).

И, последнее, о настройках типов постов, связанное с админкой – установление прав на создание/редактирование постов. По умолчанию, права на сии действия ровны правам на эти действия с записями(post). Но также, при регистрации типа постов есть возможность задавать свои права на эти действия. Для установления своих прав в capability_type достаточно поставить массив из своих слагов(для единственного и множественного чисел – для примера – book books). При этом будут сгенерированы права: если map_meta_cap false(по умолчанию) то создадутся основные(publish_books, edit_books, edit_others_books и read_private_books), но если true – будут созданы и основные и метаправа(delete_published_books, edit_others_books и т.д.).

Также, массив прав можно задать иначе: capability_type поставить в false И в по ключу capabilities создать массив, в котором переназначить слаги существующим возможностям. И теперь, чтобы воспользоваться новыми правами, установим плагин редактирования ролей(к примеру, User Role Editor). С помощью этих плагинов обновим права администратора и создадим новую роль, которой присвоим права на этот тип записей(ну или дадим их существующей роли). Можно, конечно, сделать это кодом – но зачем, если это единоразовое редактирование настроек в таблице БД, после чего плагин следует выкинуть.

И последняя настройка в админке(если твой тип должен использовать дефолтные таксономии) – это ключу taxonomies передать массив со слагами таксономий.

Настройки типа записей для фронта сайта

Во фронте сайта настроек не так уж и много; прежде, чем что-то делать – нужно разрешить публичный доступ к этому типу: ключу publicly_queryable присвоить true. Второе – это конечно же – включение архива записей. Для этого ключу has_archive присваиваем true, после чего обычным циклом в шаблоне темы archive-book.php можно вывести все записи этого типа. Также, в этом параметре можно указать слаг для архива в место true, при этом шаблон отображения страницы тот же. Сами статьи можно просматривать уже после разрешения публичного доступа, который был дан ранее.

Третье – включим результаты поиска на сайте по статьям этого типа – присвоим exclude_from_search 0. Ну вот, пожалуй, все настройки типа записи.

Настройка кастомных таксономий

По аналогии с типом записей – рассмотрим админку, а потом фронт; в админке можно настроить иерархичность таксономии: ключ hierarchical в true(по умолчание) древовидность включена, false – выключена. Cледующее – настроить вид метабокса для отображения таксономии у ключа meta_box_cb назначить функцию отрисовки. Из коробки есть две такие post_categories_meta_box  и post_tags_meta_box 

1 – meta_box_cb => ‘post_categories_meta_box ‘; 2 – meta_box_cb => ‘post_tags_meta_box ‘

После отображения в форме, будем настраивать отображение в админ-меню. Если тип записи в меню как отдельный пункт то таксономии отображаются как подпункты; их отображение можно скрыть поставив public false. Если же, тип записи, к которой принадлежит таксономия, отображается как подпункт в админ-меню – отобразить страницу таксономии настройкой массива не удастся.

Настройка WP REST API и настройка архивной страницы идентичны настройке в типах постов(вплоть до названия ключей).

Относительно прав для таксономий – их также можно настроить. По ключу capabilities задать массив из 4-ех значений:

      'capabilities' => [
        'manage_terms' => 'manage_genres',
        'edit_terms' => 'manage_genres',
        'delete_terms' => 'manage_genres',
        'assign_terms' => 'edit_books'
      ]

после этого, все новые роли нужно добавить в пул ролей с помощью тех же плагинов.

Постмета

Постмета и метадата – одно и тоже – то, что ты увидишь в метабоксе custom fields. Собственно, мету можно создавать и через него, но удобнее это делать через свои метабоксы.

Метабоксы можно создавать используя как плагин ACF(забивая на программирование) так и кодом. Рассмотрим их созданиие написание скрипта…

Для начала, зарегистрируем наш метабокс

<?php
add_action('add_meta_boxes', 'book_site_metabox');
function book_site_metabox()
{
    add_meta_box('book_url', 'Site', 'book_site_metabox_html', 'book');
}
// рендеринг метабокса
function book_site_metabox_html($post)
{
    echo '<input type="url" name="site_url" value="' . esc_url(get_post_meta($post->ID, 'site_url', 1)) . '"/>';
    wp_nonce_field('site_nonce', 'book_site');
}

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

<?php
add_action('save_post_book', 'save_post_book');
function save_post_book($post_id)
{
    if (isset($_POST['book_site']) && wp_verify_nonce($_POST['book_site'], 'site_nonce') && current_user_can('edit_books')) {
        update_post_meta($post_id, 'site_url', esc_url_raw($_POST['site_url']));
    }
}

Заключение

Рассмотрены основные настройки для создания кастомных типов постов. В процесе написания этой статьи был создан следующий, полностью рабочий, код

<?php
// plugin name: book
add_action('init', 'register_post_types');
function register_post_types()
{
    // массив для типа записей
    $typeArray = [
      'label' => 'Book',
      'show_ui' => true,
      'show_in_menu' => 'index.php',
      'show_in_nav_menus' => true,
      'show_in_rest' => true,
      'supports' => ['title','thumbnail','post-formats'],
      'map_meta_cap' => true,
      'capability_type' => 'book',
      'has_archive' => 'books',
      'publicly_queryable' => true,
      'exclude_from_search' => 0
    ];
    // массив для таксономий
    $taxArray = [
      'label' => 'Genres',
      'hierarchical' => false,
      'meta_box_cb' => 'post_tags_meta_box',
      'capabilities' => [
        'manage_terms' => 'manage_genres',
        'edit_terms' => 'manage_genres',
        'delete_terms' => 'manage_genres',
        'assign_terms' => 'edit_books'
      ]
    ];
    // регистрируем тип записи
    register_post_type('book', $typeArray);
    // регистрируем таксономию для типа записи
    register_taxonomy('book_cat', 'book', $taxArray);
}

add_action('after_setup_theme', 'book_support');
function book_support()
{
    add_theme_support('post-thumbnails', ['book']);
    add_theme_support('post-formats', [ 'aside', 'gallery' ]);
}

add_action('add_meta_boxes', 'book_site_metabox');
function book_site_metabox()
{
    add_meta_box('book_url', 'Site', 'book_site_metabox_html', 'book');
}

function book_site_metabox_html($post)
{
    echo '<input type="url" name="site_url" value="' . esc_url(get_post_meta($post->ID, 'site_url', 1)) . '"/>';
    wp_nonce_field('site_nonce', 'book_site');
}

add_action('save_post_book', 'save_post_book');
function save_post_book($post_id)
{
    if (isset($_POST['book_site']) && wp_verify_nonce($_POST['book_site'], 'site_nonce') && current_user_can('edit_books')) {
        update_post_meta($post_id, 'site_url', esc_url_raw($_POST['site_url']));
    }
}

Не забудь создать необходимые права, прежде, чем опробовать. Также, тип записей можно создавать плагинами типа CPT UI.

Источники

Краткий гайд по WordPress

В данной статье попытаюсь рассказать об особенностях WordPress, тонкостях расширения данной системы. Статья направлена, большей мерой, на улучшение понимания движка; и да, она не будет содержать никакого кода. В общем, незря это – “Краткий гайд по WordPress”…

Содержание

WordPress – что это?

WordPress – очень гибкая, с открытым исходным кодом, CMS(система управления контентом) написанная на PHP. Можно много чего о ней(системе) писать(если хочешь – глянь википедию), но раз ты это читаешь – значит ты интересуешься ней с точки зрения разработки, и, скорее всего – ты начинающий разработчик; хотя… может и опытному будет кое-что интересно…

WordPress расширяется плагинами – место для создания дополнительного или расширения существующих функций в веб-приложении. Здесь я не ошибочно назвал это веб-приложением, т.к. сайт – странички, видимые в браузере; со стороны сервера они генерируются приложением построенном на да-движке. В принципе, сейчас единицы сайтов – чисто сайты – даже лэндинги строят на движках.

Хранение информации в WordPress

Прежде, чем рассказывать об плагинах и темах, хотел бы поговорить о хранении информации. Вся информация делится на основную и ее мету(это правило не касается только инфы о настройках сайта). Мета-информация – информация о другой информации, или данные, относящиеся к дополнительной информации о содержимом или объекте – как говорит нам википедия.

Таблицы с основными данными не содержат в названии “meta_”, и наоборот – метаданные содержат.

При разработке своих плагинов(если те будут хранить или создавать свои таблицы) хорошим тоном будет сохранять подобную логику и, соответствующую архитектуру.

О темах WordPress

Тема в вордпрессе – это всего лишь набор шаблонов страниц. В теме подключаются стили, скрипты; декларируется поддержка некоторых стандартных возможностей, а также, регистрируются виджет-зоны и меню.

 гайд по WordPress ваяние темы

Немного о ваянии тем. Есть два пути сознания темы: перейти по пути wp-content/themes/, создать там папку {yout-theme-name}. И второй путь, описаный в настольной книге вордпресс разработчика, и по-этому, я считаю, более верный; иди на сайт UNDERSCORES, введи название своей темы и генерируй! Ты получишь шаблон темы, но не беспокойся – это всего лишь глыба мрамора, с которой тебе предстоит вытесать свою Венеру Милосскую; просто открой нужный шпблон страницы и начинай править ее!

И еще немного о темах: если тема, для корректной работы, нуждается в плагинах – то в тему подключают TGM PA класс, в котором задаются ссылки на плагины.

О плагинах WordPress

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

Глубокое знание WordPress, в основном, нужно для создания плагинов, а также нужны знания PHP, классов, функций WordPress, его хуков и порядка их срабатывания. О всем этом я расскажу в параграфах ниже…

Да, мало не забыл… если плагин требует наличия другого плагина – подключи TGM PA класс, о котором я упоминал ранее.

Функции WordPress

Все функции(функции – это не методы классов, если что…) ворпресса можно разделить четыре типа: функции “достань-вставь” что-то в БД(базу данных), функции построения какого-нибудь элемента(к примеру, меню), функции обработки строк и функции, делающие что-то в системе(регистрируют или добавляют). Статьи о регистраторах в движке:

Касательно функций-строителей – о них нужно отдельно о каждой. Они строят меню, пагинации постов и комментариев, само дерево комментариев и его форму. Строители:

Функции обаботки строки используются для обработки строк до вставки в БД или при выведении строки с БД на экран. О классах(их методах) и административных функциях стоит говорить отдельно, поскольку, они, большей мерой, касаются админки.

Хуки WordPress

Хуки – это специально сделанные “лазейки” для расширения и изменения параметров функций; логически(именно логически, т.к. технически они идентичны) они поделены на действия и фильтры. Логично, что фильтры получают переменные, их преобразуют и возращают для дальнейшей работы функции. Действия же, ничего не возращают, а просто совершают заданный кусочек кода.

В общем, они реализованы как функции одна из которых ставит имя функции в массив с ключом хука; вторая же – извлекает эти имена и вызывает соответсвующие функции.

Заключение

Рассмотрены поверхностные моменты разработки в вордпрессе; по поводу хуков в коде немного есть в статье “WP REST API(кастомное) — взаимодействие с WP сайтом

Источники

WP REST API(кастомное) — взаимодействие с WP сайтом.

В прошлой статье мы обсудили стандартное WP REST API, принцип чтения о нем информации и использования. В этой части рассмотрим создание и расширение существующего программного интерфейса.

Содержание

Вступление. WP REST API к кастомному типу записи

Предположим, есть задача создать тип записи. Рассмотрим код выполнения этой задачи, приведенный в официальной документации

<?php
add_action( 'init', 'codex_book_init' );
/**
 * Register a book post type.
 *
 * @link http://codex.wordpress.org/Function_Reference/register_post_type
 */
function codex_book_init() {
	$labels = array(
		'name'               => _x( 'Books', 'post type general name', 'your-plugin-textdomain' ),
		'singular_name'      => _x( 'Book', 'post type singular name', 'your-plugin-textdomain' ),
		'menu_name'          => _x( 'Books', 'admin menu', 'your-plugin-textdomain' ),
		'name_admin_bar'     => _x( 'Book', 'add new on admin bar', 'your-plugin-textdomain' ),
		'add_new'            => _x( 'Add New', 'book', 'your-plugin-textdomain' ),
		'add_new_item'       => __( 'Add New Book', 'your-plugin-textdomain' ),
		'new_item'           => __( 'New Book', 'your-plugin-textdomain' ),
		'edit_item'          => __( 'Edit Book', 'your-plugin-textdomain' ),
		'view_item'          => __( 'View Book', 'your-plugin-textdomain' ),
		'all_items'          => __( 'All Books', 'your-plugin-textdomain' ),
		'search_items'       => __( 'Search Books', 'your-plugin-textdomain' ),
		'parent_item_colon'  => __( 'Parent Books:', 'your-plugin-textdomain' ),
		'not_found'          => __( 'No books found.', 'your-plugin-textdomain' ),
		'not_found_in_trash' => __( 'No books found in Trash.', 'your-plugin-textdomain' )
	);

	$args = array(
		'labels'             => $labels,
		'description'        => __( 'Description.', 'your-plugin-textdomain' ),
		'public'             => true,
		'publicly_queryable' => true,
		'show_ui'            => true,
		'show_in_menu'       => true,
		'query_var'          => true,
		'rewrite'            => array( 'slug' => 'book' ),
		'capability_type'    => 'post',
		'has_archive'        => true,
		'hierarchical'       => false,
		'menu_position'      => null,
		'supports'           => array( 'title', 'editor', 'author', 'thumbnail', 'excerpt', 'comments' )
	);

	register_post_type( 'book', $args );
}

Результатом выполнения этого кода будет пункт «Books» и новый тип записи «book» на сайте. Но данные о записях данного типа будут не доступные по АПИ, для этого нужно изменить массив аргументов

<?php
	$args = array(
		'labels'             => $labels,
		'description'        => __( 'Description.', 'your-plugin-textdomain' ),
		'public'             => true,
		'publicly_queryable' => true,
		'show_ui'            => true,
		'show_in_menu'       => true,
		'query_var'          => true,
		'rewrite'            => array( 'slug' => 'book' ),
		'capability_type'    => 'post',
		'has_archive'        => true,
		'hierarchical'       => false,
		'menu_position'      => null,
		'supports'           => array( 'title', 'editor', 'author', 'thumbnail', 'excerpt', 'comments' ),
        'show_in_rest'       => true,// включает отображение апи
        'rest_base'          => 'book',// путь для апи, по-умолчанию, равно типу записи
        'rest_controller_class' => 'WP_REST_Posts_Controller'// класс, строящий апи, по-умолчанию "WP_REST_Posts_Controller"
	);

Данный код создаст стандартный «вордпрессовский » API. Кстати, плюсом к включению АПИ в типе поста будет также включатся редактор Guttenberg в админке.

При этом автоматически будет сгенерированная схема.

Создадим WP REST API к какому-нибудь контенту

На самом деле, этот путь можно использовать и для АПИ типов постов, но зачем?.. ведь разработчики предусмотрели эту возможность, и я за то, чтоб максимально использовать все, что усмотрено разрабами.

Но тем не менее, рассмотрим этот способ. Создадим эндпоинт-функцию и прикрепим к ней маршрут

<?php
function custom_rest_route( $get ) {
    return $get['message'];
}
function rest_callback() {
    register_rest_route( 'custom/v1', '/custom/(?P<message>w+)', array(
        'methods' => 'GET',
        'callback' => 'custom_rest_route'
    ));
}
add_action( 'rest_api_init', 'rest_callback');

Здесь «(?Pw+)» — обычное регулярное выражение. В данном случаи, перейдя по пути http://example.com/wp-json/custom/v1/custom/hello увидим hello на экране. Этот маршрут, также, появиться в схеме.

Этот способ можно использовать для API любой сложности, однако, согласно рекомендациям разработчиков — это способ для простейших случаев. Для более сложных случаев будет правильнее создавать класс, расширяющий WP_REST_Controller.

Расширяем WP_REST_Controller

Прежде, чем расширять класс, нужно знать его методы(это касается любого расширяемого класса). Класс WP_REST_Controller имеет более 25 методов, однако, для создания на его базе своего интерфейса достаточно знать 5:

  • register_routes — регистрация маршрутов(их может быть много);
  • get_items, get_item, create_item, update_item, delete_item — методы, отвечающие на запросы.

Я не буду ничего усложнять и просто перепишу созданное ранее в виде класса

<?php
function rest_callback() {
    $route = new Custom_REST_Controller();
    return $route->register_routes();
}
add_action( 'rest_api_init', 'rest_callback');

class Custom_REST_Controller extends WP_REST_Controller {
    function register_routes() {
        register_rest_route( 'custom/v1', '/custom/(?P<message>d+)', array(
            'methods' => WP_REST_Server::READABLE,
            'callback' => array( $this, 'get_item' )
        ));
    }
    function get_item( $request ) {
        return new WP_REST_Response( $get['message'], 200 );
    }
}

Поскольку мой пример только выводит надпись — я использую только get_item(). Вообще, это минимальный минимум для создания маршрута и эндпоинта.

Редактирование эндпоинтов и схемы. Фильтры

Редактирование результатов работы функции, согласно философии wordpress, происходит по средству фильтров. Данное утверждение касается абсолютно всех функций этого движка.

Работают фильтры так: есть функция

<?php
function some_func( $args ) {
    // do something
    $args = apply_filters( 'slug', $args );// filter install
    // do something
}

Если в функции установлен фильтр, то передаваемые аргументы в этом фильтре можно изменить

<?php
function filter_func( $args ) {
    // do something with args
    return $args;
}
add_filter( 'slug', 'filter_func', 10, 1 );

Здесь 10 — приоритет выполнения функции фильтра, 1 — количество принимаемых аргументов. Приоритет может изменятся если функций-фильтров несколько, чем больше это число — тем позже будет срабатывать фильтр. И еще, регистрация фильтра(add_filter) должна происходить раньше, чем вызов функции, которую нужно отфильтровать.

Но хватит теории, изменим программный интерфейс. Для начала, нужно знать слаг фильтра, его можно найти в документации вордпресс.

Возьмем, для примера, функцию-эндпоинт, которая подготавливает присланный запрос к созданию нового пользователя. В ней есть следующий крючок для фильтра

<?php
return apply_filters( 'rest_pre_insert_user', $prepared_user, $request );

значит, чтоб вызвать фильтр к этой функции нужно написать

<?php
add_filter( 'rest_pre_insert_user', 'rest_pre_insert_user_filter', 10, 2 );

В этом случаи функция rest_pre_insert_user_filter() будет принимать 2 аргумента и, после фильтрации, всегда возвращать первый из них.

Для редактирования схемы ответа, аналогично, нужно знать слаг фильтра.

Добавление полей. Экшены

Чисто технически, экшены и фильтры — одно и тоже, но логически разное. Экшен вместо того чтоб изменять данные, дополняет. Допустим, есть функция

<?php
function some_func( $args ) {
    // do something
    do_action( 'slug', $args );//вызов экшена
    // do something
}

аналогично фильтру, нужна экшн-функция и ее привязка именно на этот экшен

<?php
function action_func( $args ) {
    // do something with args
}
add_action( 'slug', 'action_func', 10, 1 );

Экшн-функция ничего не возвращает, в отличии от фильтра. Циферки при add_action имеют такой же смысл как и в add_filter.

Пример добавления дополнительного поля в запросе и схеме АПИ комментариев(взято в документации)

<?php
add_action( 'rest_api_init', function () {
    register_rest_field( 'comment', 'karma', array(
        'get_callback' => function( $comment_arr ) {
            $comment_obj = get_comment( $comment_arr['id'] );
            return (int) $comment_obj->comment_karma;
        },
        'update_callback' => function( $karma, $comment_obj ) {
            $ret = wp_update_comment( array(
                'comment_ID'    => $comment_obj->comment_ID,
                'comment_karma' => $karma
            ) );
            if ( false === $ret ) {
                return new WP_Error(
                  'rest_comment_karma_failed',
                  __( 'Failed to update comment karma.' ),
                  array( 'status' => 500 )
                );
            }
            return true;
        },
        'schema' => array(
            'description' => __( 'Comment karma.' ),
            'type'        => 'integer'
        ),
    ) );
} );

По-умолчанию,цифры равны 10 и 1.

Заключение

В этой статье проведено ознакомление с принципами изменения и дополнения WP REST API. Если нужно только работать с дефолтным АПИ — читайте. Для получения более подробной информации рекомендую прочесть REST API Handbook. Это, так сказать, информация из первых рук, т.е. разработчиков ВП АПИ.

Источники

ReactJS в WordPress. Вариант применения WP REST API

Ранее в статья(здесь и здесь) я говорил о дефолтном WP REST API и о методах его кастомизации. Пришло время поговорить об одном из способов его применения; т.е. в прошлых статьях было «о теории», в этой — «о практике»… о ReactJS в WordPress.

Содержание

ReactJS — что это?

ReactJS — JavaScript-библиотека для создания пользовательских интерфейсов — как определяет официальный сайт ReactJS.

Несмотря на всю сложность и запутанность официальной документации и объяснений «для чего он и с чем его едят» — все просто; может быть, меня обозвут нубом либо дураком, «не въехавшим в тему» — но эта библиотека нужна для одной цели: отрисовать HTML страницы. В отличии от многих js-фреймворков, здесь нету:

  1. Системы событий (отличную от нативных DOM событий);
  2. Работы с AJAX;
  3. Какой либо слой данных;
  4. Promises.

Всё, что делает React, это рисует страницу из полученными данными — по сути, то же, что PHP-файл с HTML-тегами. Возможно ты спросиш — зачем React в вордпрессе? Зачем — я не нашел, мое мнение — это способ снять часть нагрузки с сервера и перенести на комп пользователя; ведь проще отдать браузеру кучку статических файлов и JSON-строку, нежели построенный HTML. Хотя, может это(мое, ранее изложенное, предположение) полная чухня. Еще один способ применения, который я вижу, — это вставка кастомного HTML в места, в которые его нельзя вписать(сгенерированным плагином, к примеру).

ReactJS в WordPress — теория

ReactJS вмонтирован в WP лишь в версии 5 как основа для работы редактора Гутенберг, однако, мы можем его использовать. Работает это(ReactJS в WordPress) следующим образом: движок отдает JSON-строк, JS и CSS файлы, а также HTML страницу. JS скрипт формирует HTML шаблон, который будет вставлен в страницу.

Для включения ReactJS в тему необходимо к JS-файлу, в котором вы будете писать шаблоны, в качестве зависимости(при подключении его функцией wp_enqueue_script()) указать wp-element

<?php
add_action( 'wp_enqueue_scripts', 'react_script' );
function react_script(){
	wp_enqueue_script( 'react-template', get_template_directory_uri() . '/js/react-template.js', array( 'wp-element' ) );
}

При этом будут загружены все компоненты библиотеки и абстрактный слой Element. Данный слой нужен(цитирую настольную книгу вордпресс -разработчика):

  • Во многих приложениях, особенно в тех, которые расширяются великим множеством плагинов, как в случае с WordPress, целесообразно создавать интерфейсы для стороннего кода. Идея заключается в том, что если когда-либо возникнет необходимость изменить или даже заменить базовую реализацию, это можно сделать без катастрофических последствий для зависимого кода, если интерфейс остается неизменным.
  • Он предоставляет механизм для защиты исполнителей, опуская функции с неопределенным будущим ( createClass, PropTypes).
  • Это помогает избежать несовместимости между версиями, гарантируя, что каждый плагин работает с единой централизованной версией кода.

Element представлен в виде wp.element и имеет 2 метода: render() и createElement().

ReactJS в WordPress — практика

Поскольку, в основе ReactJS — можно писать код используя его методы, однако, если использовать wp.element, следующий код

function Title( props ) {
    return React.createElement( 'h1', null,
        props.title
    );
}

ReactDOM.render(
    React.createElement( Title, { title:'Hello World!' } ),
    document.getElementById( 'root' )
);

будет выглядеть следующим образом

function Title( props ) {
    return wp.element.createElement( 'h1', null,
        props.title
    );
}

wp.element.render(
    wp.element.createElement( Title, { title:'Hello World!' } ),
    document.getElementById( 'root' )
);

или, с использованием класса

class Title extends wp.element.Component {
    render() {
        return wp.element.createElement( 'h1', null,
            this.props.title
        );
    }
}

wp.element.render(
    wp.element.createElement( Title, { title:'Hello World!' } ),
    document.getElementById( 'root' )
);

Теперь, поговорим о получении данных, чтоб наш шаблон был многоразового использования. Нужно получить данные в JSON формате — здесь то и понадобятся нам знания с предыдущих статей о WP REST API.

Допустим, нужно вывести данные поста с идентификатором 50. В схеме(как ее найти и прочесть было здесь) находим путь к этим данным и по нему получим эти данные

<?php
$request = new WP_REST_Request('GET', '/wp/v2/posts/50');
$result = rest_do_request($request);

В общем, вот полный PHP скрипт, необходимый для получения данных о посте с идентификатором 50 в шаблон страницы

<?php
add_action('wp_enqueue_scripts', 'child_scripts');
function child_scripts()
{
    $request = new WP_REST_Request('GET', '/wp/v2/posts/50');
    $result = rest_do_request($request);
    wp_enqueue_script('my-react-template', get_stylesheet_directory_uri() . '/react.js', ['wp-element'], '', 1);// подключение файла с js шаблоном
    wp_localize_script('my-react-template', 'data', $result->get_data());// вывод данных в js обьекте data
}

а вот JS скрипт, использующий эти данные(в данном случаи — вывод заголовка поста)

class Title extends wp.element.Component {
    render() {
        return wp.element.createElement( 'h1', null,
            this.props.title
        );
    }
}

wp.element.render(
    wp.element.createElement( Title, { title: data.title.rendered} ),
    document.getElementById( 'root' )
);

Заключение

Мы с вами рассмотрели использование ReactJS в вордпресс, а также, способы получения данных. Конечно, это не все, я не рассмотрел настройку Babel для использования JSX шаблонов; не рассмотрел использование переменной $wp_query для «вытягивания» информации о текущем массиве доступных данных на странице…

Источники

WP REST API(дефолтное) — взаимодействие с WP сайтом.

Эта задача крайне редкая для сайтов на вордпресс. Скажу прямо — в моей практика не было задач(возможно, я нуб или это потому, что апи делают серьезным проектам, а на вордпресс, зачастую, клепают более простые). В любом случаи, я считаю это нужно знать. Ведь это дает возможность, допустим, создать приложение по управлению блогом, не входя в блог(сайт) или тему на ReactJS. В этой статье я расскажу о WP API, которое получается при установке свежего вордпресс версии 5.2.4.

Содержание

API — что это?

API (программный интерфейс приложения, интерфейс прикладного программирования) (англ. application programming interface) — описание способов (набор классов, процедур, функций, структур или констант), которыми одна компьютерная программа может взаимодействовать с другой программой.

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

Используем WP REST API

Для использования АПИ сайта нужно знать пути к точкам входа(Routes & Endpoints). Эту информацию мы можем получить следующим образом

<?php
$url = 'http://example.com/wp-json/';//если ЧПУ ссылки
// не включены замените 'wp-json' на  'rest_route='

// запрос в общем случаи
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );
$result = curl_exec( $ch );

// в случаи, если вы делаете запрос с админки
// или с одного ВП сайта в другой(есть доступ
// к классу WP_REST_Request)
$request = new WP_REST_Request( 'GET', $url );
$result = rest_do_request( $request );

В результате, мы получим JSON-строку, декодировав которую(json_decode) — объект, содержащий всю информацию об АПИ сайта. Конечно, можно и в REST API Handbook посмотреть(там указаны дефолтные пути), но их можно изменять — об этом потом.

Рассмотрим маршрут чтения создания и редактирования поста.

Маршруты и точки входа

Рассмотрим маршрут ‘/wp/v2/posts’. Чтоб получить информацию об этом объекте — перейдем по ключу routes->{‘/wp/v2/posts’}. Вот полный объект содержащийся по этой ссылке(версия вордпресс 5.2.3, плагины отсутствуют)

stdClass Object
(
    [namespace] => wp/v2
    [methods] => Array
        (
            [0] => GET
            [1] => POST
        )

    [endpoints] => Array
        (
            [0] => stdClass Object
                (
                    [methods] => Array
                        (
                            [0] => GET
                        )

                    [args] => stdClass Object
                        (
                            [context] => stdClass Object
                                (
                                    [required] => 
                                    [default] => view
                                    [enum] => Array
                                        (
                                            [0] => view
                                            [1] => embed
                                            [2] => edit
                                        )

                                    [description] => Рамки в которых сделан запрос, определяют поля в ответе.
                                    [type] => string
                                )

                            [page] => stdClass Object
                                (
                                    [required] => 
                                    [default] => 1
                                    [description] => Текущая страница коллекции.
                                    [type] => integer
                                )

                            [per_page] => stdClass Object
                                (
                                    [required] => 
                                    [default] => 10
                                    [description] => Максимальное число объектов возвращаемое в выборке.
                                    [type] => integer
                                )

                            [search] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Ограничить результаты до совпадающих со строкой.
                                    [type] => string
                                )

                            [after] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Ограничить ответ записями опубликованными после заданной ISO8601 совместимой даты. 
                                    [type] => string
                                )

                            [author] => stdClass Object
                                (
                                    [required] => 
                                    [default] => Array
                                        (
                                        )

                                    [description] => Ограничить выборку записями определенных авторов.
                                    [type] => array
                                    [items] => stdClass Object
                                        (
                                            [type] => integer
                                        )

                                )

                            [author_exclude] => stdClass Object
                                (
                                    [required] => 
                                    [default] => Array
                                        (
                                        )

                                    [description] => Убедиться что выборка исключает записи назначенные определенным авторам.
                                    [type] => array
                                    [items] => stdClass Object
                                        (
                                            [type] => integer
                                        )

                                )

                            [before] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Ограничить ответ записями опубликованными до заданной ISO8601 совместимой даты.
                                    [type] => string
                                )

                            [exclude] => stdClass Object
                                (
                                    [required] => 
                                    [default] => Array
                                        (
                                        )

                                    [description] => Убедиться что выборка исключает определенные ID.
                                    [type] => array
                                    [items] => stdClass Object
                                        (
                                            [type] => integer
                                        )

                                )

                            [include] => stdClass Object
                                (
                                    [required] => 
                                    [default] => Array
                                        (
                                        )

                                    [description] => Ограничить выборку до определенных ID.
                                    [type] => array
                                    [items] => stdClass Object
                                        (
                                            [type] => integer
                                        )

                                )

                            [offset] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Сдвиг выборки на определенное число объектов.
                                    [type] => integer
                                )

                            [order] => stdClass Object
                                (
                                    [required] => 
                                    [default] => desc
                                    [enum] => Array
                                        (
                                            [0] => asc
                                            [1] => desc
                                        )

                                    [description] => Упорядочить сортировку атрибута по возрастанию или убыванию.
                                    [type] => string
                                )

                            [orderby] => stdClass Object
                                (
                                    [required] => 
                                    [default] => date
                                    [enum] => Array
                                        (
                                            [0] => author
                                            [1] => date
                                            [2] => id
                                            [3] => include
                                            [4] => modified
                                            [5] => parent
                                            [6] => relevance
                                            [7] => slug
                                            [8] => include_slugs
                                            [9] => title
                                        )

                                    [description] => Сортировать коллекцию по атрибуту объекта.
                                    [type] => string
                                )

                            [slug] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Ограничить выборку до записей с одним или несколькими установленными конкретными ярлыками.
                                    [type] => array
                                    [items] => stdClass Object
                                        (
                                            [type] => string
                                        )

                                )

                            [status] => stdClass Object
                                (
                                    [required] => 
                                    [default] => publish
                                    [description] => Ограничить выборку до записей с одним или несколькими установленными статусами.
                                    [type] => array
                                    [items] => stdClass Object
                                        (
                                            [enum] => Array
                                                (
                                                    [0] => publish
                                                    [1] => future
                                                    [2] => draft
                                                    [3] => pending
                                                    [4] => private
                                                    [5] => trash
                                                    [6] => auto-draft
                                                    [7] => inherit
                                                    [8] => request-pending
                                                    [9] => request-confirmed
                                                    [10] => request-failed
                                                    [11] => request-completed
                                                    [12] => any
                                                )

                                            [type] => string
                                        )

                                )

                            [categories] => stdClass Object
                                (
                                    [required] => 
                                    [default] => Array
                                        (
                                        )

                                    [description] => Ограничить выборку до объектов с установленным указанным элементом в таксономии categories.
                                    [type] => array
                                    [items] => stdClass Object
                                        (
                                            [type] => integer
                                        )

                                )

                            [categories_exclude] => stdClass Object
                                (
                                    [required] => 
                                    [default] => Array
                                        (
                                        )

                                    [description] => Ограничить выборку до всех объектов кроме тех, что имеют указанные элементы назначенные в таксономии categories.
                                    [type] => array
                                    [items] => stdClass Object
                                        (
                                            [type] => integer
                                        )

                                )

                            [tags] => stdClass Object
                                (
                                    [required] => 
                                    [default] => Array
                                        (
                                        )

                                    [description] => Ограничить выборку до объектов с установленным указанным элементом в таксономии tags.
                                    [type] => array
                                    [items] => stdClass Object
                                        (
                                            [type] => integer
                                        )

                                )

                            [tags_exclude] => stdClass Object
                                (
                                    [required] => 
                                    [default] => Array
                                        (
                                        )

                                    [description] => Ограничить выборку до всех объектов кроме тех, что имеют указанные элементы назначенные в таксономии tags.
                                    [type] => array
                                    [items] => stdClass Object
                                        (
                                            [type] => integer
                                        )

                                )

                            [sticky] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Ограничить выборку прилепленными объектами.
                                    [type] => boolean
                                )

                        )

                )

            [1] => stdClass Object
                (
                    [methods] => Array
                        (
                            [0] => POST
                        )

                    [args] => stdClass Object
                        (
                            [date] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Дата публикации объекта, по временной зоне сайта.
                                    [type] => string
                                )

                            [date_gmt] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Время публикации объекта, по GMT.
                                    [type] => string
                                )

                            [slug] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Буквенно-цифровой идентификатор для объекта уникальный для его типа.
                                    [type] => string
                                )

                            [status] => stdClass Object
                                (
                                    [required] => 
                                    [enum] => Array
                                        (
                                            [0] => publish
                                            [1] => future
                                            [2] => draft
                                            [3] => pending
                                            [4] => private
                                        )

                                    [description] => Именованный статус для объекта.
                                    [type] => string
                                )

                            [password] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Пароль для защиты содержания и отрывка.
                                    [type] => string
                                )

                            [title] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Название для объекта.
                                    [type] => object
                                )

                            [content] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Содержимое объекта.
                                    [type] => object
                                )

                            [author] => stdClass Object
                                (
                                    [required] => 
                                    [description] => ID автора объекта.
                                    [type] => integer
                                )

                            [excerpt] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Отрывок объекта.
                                    [type] => object
                                )

                            [featured_media] => stdClass Object
                                (
                                    [required] => 
                                    [description] => ID избранного медиа для объекта.
                                    [type] => integer
                                )

                            [comment_status] => stdClass Object
                                (
                                    [required] => 
                                    [enum] => Array
                                        (
                                            [0] => open
                                            [1] => closed
                                        )

                                    [description] => Открыты ли комментарии для объекта.
                                    [type] => string
                                )

                            [ping_status] => stdClass Object
                                (
                                    [required] => 
                                    [enum] => Array
                                        (
                                            [0] => open
                                            [1] => closed
                                        )

                                    [description] => Принимает ли объект уведомления.
                                    [type] => string
                                )

                            [format] => stdClass Object
                                (
                                    [required] => 
                                    [enum] => Array
                                        (
                                            [0] => standard
                                            [1] => aside
                                            [2] => chat
                                            [3] => gallery
                                            [4] => link
                                            [5] => image
                                            [6] => quote
                                            [7] => status
                                            [8] => video
                                            [9] => audio
                                        )

                                    [description] => Формат для объекта.
                                    [type] => string
                                )

                            [meta] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Мета поля.
                                    [type] => object
                                )

                            [sticky] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Считать ли объект прилепленным или нет.
                                    [type] => boolean
                                )

                            [template] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Файл темы используемый для показа объекта.
                                    [type] => string
                                )

                            [categories] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Элементы назначенные объекту в таксономии category.
                                    [type] => array
                                    [items] => stdClass Object
                                        (
                                            [type] => integer
                                        )

                                )

                            [tags] => stdClass Object
                                (
                                    [required] => 
                                    [description] => Элементы назначенные объекту в таксономии post_tag.
                                    [type] => array
                                    [items] => stdClass Object
                                        (
                                            [type] => integer
                                        )

                                )

                        )

                )

        )

    [_links] => stdClass Object
        (
            [self] => http://wordpress.loc/wp-json/wp/v2/posts
        )

)

Проанализирую данный объект, кстати, аналогично можно прочесть и прочие объекты WP REST API.

Под ключем _links->self содержится абсолютная ссылка для запросов к апи постов этого сайта. methods — массив методов, которыми можно отправить запрос, endpoints — массив, содержащий описание возможных аргументов и методов их отправки; анализ одного из возможных аргументов — например context: required — обязателен ли, default дефолтное значение, enum массив возможных значений, description описание аргумента, type тип переменной, содержащейся в аргументе.

Context — массив возможностей для этого маршрута. В данном маршруте можно просматривать(view), вставлять(embed) и обновлять(edit) пост. Но с обновлением поста не все так просто — в конец маршрута нужно дописать идентификатор поста — а это уже новый маршрут, по этому я не буду это действие рассмартивать.

Объект endpoints содержит два массива потому, что первый описывает запрос на извлечение данных, второй — добавление.

Схема ответа

Знать, как составить запрос и куда его отправлять — это, хоть и большая, но все же часть дела. Другая часть — это обработка ответа, для чего нужно знать его схему. Данный код получает эту схему

<?php
$url = 'http://example.com/wp-json/wp/v2/posts';

// запрос в общем случаи
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );
curl_setopt( $ch, CURLOPT_CUSTOMREQUEST, 'OPTIONS' );
$result = curl_exec( $ch );

// в случаи, если вы делаете запрос с админки
// или с одного ВП сайта в другой(есть доступ
// к классу WP_REST_Request)
$request = new WP_REST_Request( 'OPTIONS', $url );
$result = rest_do_request( $request );

декодировав строку получим объект. В объекте по ключу schema получим схему; она представляет собой ключ в объекте и тип данных, которую принимает переменная.

Запросы и ответы

Получим список постов, в которых есть слово «привет» — произведем обычный поиск, а также добавим условие: чтоб автором постов был автор с id = 1

<?php
$url = 'http://example.com/wp-json/wp/v2/posts';
$args = array(
    'search'  => 'привет',
    'author'  => array( 1 )    
);

// запрос в общем случаи
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url . '?' . http_build_query( $args ) );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );
$result = curl_exec( $ch );

// в случаи, если вы делаете запрос с админки
// или с одного ВП сайта в другой(есть доступ
// к классу WP_REST_Request)
$request = new WP_REST_Request( 'GET', $url );
$request->set_param( 'search', 'привет' );
$request->set_param( 'author', array( 1 ) );
$result = rest_do_request( $request );

Создадим пост с заголовком «АПИ». Для этого нужна аутентификация, которая на данную версию(5.2.3) в ядро ВП не включено. Чтобы создать эту возможность — установите плагин WordPress REST API Authentication(или ему подобные). В плагине(конкретно в этом) есть настройки; я выбрал Basic Auth и вариант Username : Password , по этому мои заголовки в коде такие

<?php
$url = 'http://example.com/wp-json/wp/v2/posts';
$args = array(
    'title'  => 'АПИ',   
);
$headers = array(
    'Authorization:Basic ' .  base64_encode( 'Username : Password' )
);

// запрос в общем случаи
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );
curl_setopt($ch, CURLOPT_POSTFIELDS, $args );
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers );
$result = curl_exec( $ch );

// в случаи, если вы делаете запрос с админки
// или с одного ВП сайта в другой(есть доступ
// к классу WP_REST_Request)
$request = new WP_REST_Request( 'POST', $url );
$request->set_param( 'search', 'привет' );
$request->set_headers( $headers );
$result = rest_do_request( $request );

При успешном создании поста будет отдан объект данных о посте, зашифрованный в JSON-строку. Если же произошла ошибка при создании — вернет информацию об ошибке.

Заключение

Здесь было рассмотрено WordPress REST API «из коробки»(если не учитывать плагин аутентификации, который, я надеюсь, скоро включат в ядро) движка. В одной из следующих статей рассмотрим возможности кастомизации маршрутов, схем и точек входа — в общем — WP API.

Источники