Навигационное меню в 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 );
	}

	/**
	 * Ends the element output, if needed.
	 *
	 * @since 3.0.0
	 *
	 * @see Walker::end_el()
	 *
	 * @param string   $output Used to append additional content (passed by reference).
	 * @param WP_Post  $item   Page data object. Not used.
	 * @param int      $depth  Depth of page. Not Used.
	 * @param stdClass $args   An object of wp_nav_menu() arguments.
	 */
	public function end_el( &$output, $item, $depth = 0, $args = null ) {
		if ( isset( $args->item_spacing ) && 'discard' === $args->item_spacing ) {
			$t = '';
			$n = '';
		} else {
			$t = "\t";
			$n = "\n";
		}
		$output .= "</li>{$n}";
	}

}

И еще… мало не забыл… немного о методах. Для строительства скелета, есть 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>\ц+)', array(
        'methods' => 'GET',
        'callback' => 'custom_rest_route'
    ));
}
add_action( 'rest_api_init', 'rest_callback');

Здесь «(?P\w+)» — обычное регулярное выражение. В данном случаи, перейдя по пути 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.

Источники

Файлы переводов WordPress. Расширения файлов MO, PO и POT

В прошлой статье была рассмотрена мультиязычность, где я упомянул о принципе «Translate-ready». Кодирование, придерживаясь данного принципа, всего лишь дает возможность перевода строк. Сами же строки перевода — это отдельные файлы — файлы переводов WordPress — создание которых мы сегодня и рассмотрим.

Содержание

Процесс создания файлов перевода

Файлы переводов WordPress — файлы, которые использует вордпресс для создания переводов и новых файлов переводов. WP использует для переводов схему GNU GetText Framework. Для начала, нужно создать POT-шаблон текстовых строк. По-сути, это просто объект из всех, использованных в теме/плагине, текстовых строк внутри функций переводов описанных ранее.

Далее, используя файл POT, а также, переводы строк, составляется PO-файл. Он также есть объектом строк, но уже со строками перевода. В заключении, с PO-файла компилируется МО-файл, который и использует вордпресс.

POT и PO файлы при открытии будут понятны человеку, МО-файл — это машинный код. Все эти файлы составляются программами, среди которых я рассмотрю программу POedit и вордпресс плагин Loco Translate.

Делаем переводы в POedit

В ПРО версии есть пункт «создать перевод WordPress», но и в свободной версии создать его возможно. Первым делом, нужно создать шаблон переводов POT.

Для этого совершите следующие действия:

  • пункт «Файл» выберем «Создать»;
  • в открывшемся окне выберем язык и «ОК»;
  • пункт «Каталог > Свойства» заполним ознакомительную информацию на табе «Свойства перевода». На «Ключевые слова исходных файлов» плюсом добавляем поля, в которые вписываем языковые функции WP. Жмем «ОК»:
  • «Файл > Сохранить как» сохраняем файл в папку languages(стандарт) папки темы/плагина. При этом обязательно изменив название файла на то, как называется ваша тема, расширение при этом нужно изменить с po на pot;
  • кликнуть по «Извлечь из исходного кода»;
  • в открывшемся окне выбрать таб «Папки с исходными файлами»;
  • в окне «Папки», под базовым путем, поместить путь к папке с темой/плагином о жмякнуть «ОК».

Все, шаблон у вас сформирован, время переводить. Для этого просто выбирайте строку из списка и внизу экрана программы вписывайте строку перевода. После окончания перевода строк просто нажмите «Сохранить» и ваш файл перевода PO будет автоматически скомпилирован в MO.

Плагин Loco Translate

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

LocoTranslate logo  Файлы переводов WordPress

После выбора объекта перевода нужно кликнуть «Создать шаблон», после чего будут просканированы все файлы и сформируется POT. Далее, кликнем «Новый язык», где выберем слаг языка и информацию об авторе. Нажмем «Начать перевод» и, так как и в POedit, будем выбирать строки и вписывать перевод. По-окончанию, сохраним, при этом будут сгенерированы РО и МО файлы. Вот и весь процесс перевода плагином.

Заключение

Рассмотрены 2 способа создания переводов программой и плагином. По-сути, они делают одно и то же, но в программе есть возможность дать информацию о составителе. В общем, если есть рабочий сайт — лучше использовать плагин, имхо.

Источники