Основы использования

Meta Box

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

Оглавление:

Создание метабоксов
Параметры метабокса
id (строка)
title (строка) (обязательный)
post_types (строка/массив)
style (строка)
context (строка)
priority (строка)
autosave (true/false)
media_modal (true/false)
fields (массив)
validation (массив)
default_hidden (логический)
Параметры fields (поля)
id (строка) (обязательный)
type (строка) (обязательный)
name (строка)
desc (строка)
label_description (строка)
std (строка)
before (строка)
after (строка)
multiple (логический)
clone (логический)
clone_default (логический)
max_clone (число)
sort_clone (логический)
add_button (строка)
class (строка)
attributes (массив)
Функции получения значений
rwmb_meta( $field_id, $args, $post_id )
rwmb_get_value( $field_id, $args, $post_id )
rwmb_the_value( $field_id, $args, $post_id, $echo )
Шоткод [rwmb_meta meta_key="key"]

Создание метабоксов

Добавление метабоксов происходит на хуке rwmb_meta_boxes, например:

add_filter( 'rwmb_meta_boxes', 'prefix_register_meta_boxes' );
function prefix_register_meta_boxes( $meta_boxes ) {

	$prefix = 'field_prefix_';

	$meta_boxes[] = array(
		'id'         => 'personal',
		'title'      => 'Личная информация',
		'post_types' => 'post',
		'context'    => 'normal',
		'priority'   => 'high',

		'fields' => array(
			array(
				'name'  => 'Как Вас зовут?',
				'desc'  => 'Формат: {Имя} {Фамилия} {Отчество}',
				'id'    => $prefix . 'name',
				'type'  => 'text',
			),
		)
	);

	// Ещё метабоксы
	// $meta_boxes[] = ...

	return $meta_boxes;
}

В результате, на странице редактирования записи появится вот такой бокс:

Параметры метабокса

Каждый метабокс поддерживает следующие параметры:

id(строка)

ID метабокса. Если отсутствует, то будет создан из title, используя функцию sanitize_title().

title(строка) (обязательный)

Заголовок метабокса.

post_types(строка/массив)

Тип или типы постов, для которых отображать метабокс. Если тип поста один, то передавать в виде строки, если несколько - в массиве. Обязательно писать с маленькой буквы, как в slug.
По умолчанию: post

style(строка)

В каком стиле показывать метабокс:

default - в стиле WP - контейнер с белым фоном.
seamless - контейнер без белого фона.
По умолчанию: default

context(строка)

Где будет выведен метабокс. Возможные значения:

normal - под редактором контента. Значение по умолчанию.
advanced - под normal секцией.
side - справа в сайдбаре.
form_top вверху формы редактирования поста, над его заголовком. Добавлено в версии 4.13.0.
after_title - под заголовком поста, ниже ссылки на пост. Добавлено в версии 4.13.0.
after_editor - после редактора контента, но до normal секции, тем самым метабокс как бы прилипает к редактору контента. Добавлено в версии 4.13.0.
before_permalink - перед ссылкой на пост. Добавлено в версии 4.13.0.

priority(строка)

Приоритет блока для показа выше или ниже остальных блоков: high или low.
По умолчанию: default

autosave(true/false)

Сразу сохранять значения полей, без сохранения записи. true - да, false - нет.
По умолчанию: false

media_modal(true/false)

Добавлять или нет метаполя в модальное окно при просмотре или редактировании вложения. Работает, когда в post_types указано attachment.
По умолчанию: false

fields(массив)

Массив описывающий метаполя, которые будет содержать метабокс.

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

array(
	array(
		'id'    => 'name',
		'type'  => 'text',
		'name'  => 'ФИО',
		'desc'  => 'Формат: {Имя} {Фамилия} {Отчество}',
	),
)

id используется как мета ключ (meta_key) под которым будет сохраняться значение в таблице метаполей (wp_postmeta).
type определяет тип поля.
Описание остальных общих параметров поля смотрите ниже, в описании параметров fields.

Используйте подчеркивание _ в начале ID поля, чтобы скрыть поля в дефолтной форме вывода произвольных полей в админке.

validation(массив)

Meta Box умеет проверять введенное в поле значение. Такую проверку можно использовать, чтобы, например, сделать поле обязательным, проверить длину пароля, проверить формат номера телефона и т.д.

Чтобы включить проверку (валидацию), нужно добавить параметр validation, который в свою очередь имеет еще два параметра:

rules - правила проверок каждого поля. Правила для каждого поля описываются в виде вложенного массива.
messages - тексты сообщений об ошибках. Тот же формат, что и rules.

Для примера, давайте добавим два правила проверки для поля field_id: обязательное его заполнение и минимальная длина ввода 7 знаков.

'validation' => array(
	'rules'  => array(
		'field_id' => array(
			'required'  => true,
			'minlength' => 7,
			// другие правила
		),
		// правила для других полей
	),
	// сообщения об ошибках для проверок required и minlength
	'messages' => array(
		'field_id' => array(
			'required'  => 'Пароль обязателен!',
			'minlength' => 'Пароль должен быть не менее 7 символов.',
		),
		// сообщения для других полей
	)
),

Модуль валидации работает с помощью jQuery плагина jQuery Validation Plugin. Плагин поставляется в комплекте с полезным набором методов проверки и API для написания собственных методов. Сообщения об ошибках по умолчанию на английском языке, но имеют перевод на русский (и еще 36 других языков).

Список всех возможных правил проверки:

Название	Описание
required	Обязательно поле.
minlength	Минимальное количество символов для ввода.
maxlength	Максимальное количество символов для ввода.
rangelength	Заданный диапазон количества символов. Массив.
min	Минимальное значение.
max	Максимальное значение.
range	Заданный диапазон значений. Массив.
email	Проверка на email.
url	Проверка на ссылку.
date	Проверка на дату.
dateISO	Проверка даты в формате ISO.
number	Проверка на десятичное число.
digits	Требует только цифры.
creditcard	Требует номер кредитной карты.
equalTo	Требует, чтобы элемент был таким же, как другой. Значение должно быть идентификатором другого поля.
remote	Запрашивает удаленные данные для проверки поля на валидность. Значением может быть ссылка на ресурс, куда будет послан запрос для получения данных валидации, или же объект с кастомизированными настройками запроса, смотрите jQuery.ajax. Запрос к серверу осуществляется через `jQuery.ajax` и получает ключ-значение (имя поля и его значение) в виде GET параметров. Ответ возвращается в виде JSON и должен быть `true`, если значение поля валидно, иначе `false`, `undefined` или `null`.

Подробнее о параметрах читайте в документации jQuery Validation Plugin.

default_hidden(логический)

По умолчанию метабокс скрыт (true) или нет (false). Отображение метабокса можно переключить, используя флажок в "Настройка экрана" (в верхнем правом углу).

Если юзер не новый и у него уже есть данные о том какие метабоксы показываются, а какие скрываются (т.е. он хотя бы раз за все время пользования сайтом выставлял галочку в настройках экрана), то эта опция не будет иметь никакого эффекта...
По умолчанию: false

Параметры `fields` (поля)

Ниже описаны общие параметры для всех типов полей. Однако у каждого поля могут быть свои индивидуальные параметры - они описаны на отдельной странице.

id(строка) (обязательный)

ID поля. Должен быть уникальным. Используется как meta_key при сохранении в базу данных. Хорошая практика - использовать только цифры, буквы и символы подчеркивания.

type(строка) (обязательный)

Тип поля (текстовое, галерея и т.д.). Список типов:

Тип поля	Описание
autocomplete	Текстовое поле с функцией автозаполнения.
background	Устанавливает настройки фона. Добавлено в версии 4.13.0.
button	Кнопка. Обычно используется для каких-либо действий на основе JavaScript.
button_group	Выбор одного или нескольких вариантов, нажав кнопку (кнопки) из группы. Добавлено в версии 4.13.0.
checkbox	Флажок (галочка).
checkbox_list	Список флажков (галочек).
color	Выбор цвета.
custom_html	Произвольный HTML контент.
date	Выбор даты.
datetime	Выбор даты и времени.
divider	Горизонтальная линия.
fieldset_text	Группа текстовых полей.
file	Выбор файла (или файлов) с жёсткого диска с использованием дефолтного оформления браузера, как `<input type="file" />`.
file_advanced	Выбор файла (или файлов) из медиабиблиотеки с помощью всплывающего окна WordPress.
file_input	Добавление файла через URL или выбор из медиабиблиотеки.
file_upload	Загрузка файла через перетаскивание его в специальную область.
heading	Заголовок.
hidden	Скрытое текстовое поле.
image	Такое же как `file`, только для изображений.
image_advanced	Такое же как `file_advanced`, только для изображений.
image_select	Такое же как `radio` + `select`, вместо радиокнопок используются изображения.
image_upload plupload_image	Такое же как `file_upload`, только для изображений.
key_value	Добавляет группу с неограниченным количеством пар ключ-значение. Своего рода клонируемое поле.
map	Карта Google.
number	Поле для ввода цифровых значений, HTML5 поле `type="number"`.
oembed	Вставка медиа элементов с сайтов, типа Youtube, Vimeo и других поддерживаемых WordPress.
password	Поле для ввода пароля.
post	Выпадающий список с постами, имеется поиск.
radio	Радиокнопка.
range	Ползунок HTML5.
select	Выпадающий список.
select_advanced	Красивый выпадающий список с использованием библиотеки select2.
single_image	Выбор или загрузка одного изображения через всплывающее окно WordPress. Добавлено в версии 4.13.0.
slider	Ползунок jQuery UI.
switch	Переключатель в стиле iOS. Добавлено в версии 4.13.0.
taxonomy	Выпадающий список с терминами выбранной таксономии. Не сохраняет ничего в метаданные. Дублирует функционал метабоксов "Рубрики" или "Метки", то есть устанавливает посту термины.
taxonomy_advanced	Такое же, как `taxonomy`, но сохраняет ID выбранных терминов через запятую виде строки. Не устанавливает посту термины.
text	Текстовое поле.
text_list	Группа из текстовых полей. Похоже на `fieldset_text`.
textarea	Текстовая область.
time	Выбор времени.
user	Выпадающий список с пользователями сайта, имеется поиск.
video	Загружает или позволяет выбрать видео из медиабиблиотеки с помощью всплывающего окна WordPress.
wysiwyg	Визуальный редактор WordPress.

name(строка)

Заголовок поля. Если оставить пустым, то поле ввода станет по ширине 100%.

desc(строка)

Описание поля, отображается под ним.

label_description(строка)

Описание заголовка (name), отображается под ним.

std(строка)

Значение поля по умолчанию.

before(строка)

Пользовательский html код, выводится до html поля.

after(строка)

Пользовательский html код, выводится после html поля.

multiple(логический)

Имеет ли поле несколько значений? Например, как это может делать поле select.
По умолчанию: false

clone(логический)

Является ли поле повторяемым, можно ли его клонировать.

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

Чтобы сделать поле повторяемым, нужно включить параметр - 'clone' => true. После этого под полем появится кнопка + (Add Clone):

$meta_boxes[] = array(
	'id'         => 'clients',
	'title'      => 'Информация о клиентах',
	'post_types' => 'post',

	'fields' => array(
		array(
			'name'       => 'Имя клиента',
			'id'         => 'fio',
			'type'       => 'text',
			// параметры клонируемого поля
			'clone'         => true,         // повторяемое поле
			'sort_clone'    => true,         // Можно ли сортировать клоны?
			'clone_default' => true,         // Клонировать значение по умолчанию?
			'add_button'    => '+ добавить', // Текст кнопки добавления клона.
			'max_clone'     => 10,           // Максимальное количество клонов. Число.
		),
	),
);

По умолчанию: false

clone_default(логический)

При clone = true. Копировать значение по умолчанию повторяемых полей?
По умолчанию: false

max_clone(число)

При clone = true. Максимальное число повторений поля.
По умолчанию: 0 (без ограничений)

sort_clone(логический)

При clone = true. Возможность перетаскивать и тем самым менять сортировку у повторяющихся полей.
По умолчанию: false

add_button(строка)

При clone = true. Текст кнопки повторяемого поля.
По умолчанию: + Add more

class(строка)

Пользовательский CSS класс.

attributes(массив)

Позволяет добавлять полям произвольные атрибуты для HTML тега, например data-* чтобы потом использовать его в в javasript.

Атрибуты доступны почти всем типам полей: text, url, email, checkbox, radio, date, time, datetime и т.д.

Параметр должен содержать массив в виде 'key' => 'value', где key - сам атрибут, а value его значение.

array(
	'id'   => 'name',
	'name' => 'Name',
	'type' => 'text',
	'attributes' => array(
		'disabled'  => true,
		'minlength' => 10,
		// Пример добавления атрибута `data-*`:
		'data-option1'  => 'value1',
		'data-option2'  => json_encode( array( 'key1'=>'value1', 'key2'=>'value2' ) ),
	),
),

class, disabled, required, readonly, maxlength и pattern - это общие атрибуты, которые зарегистрированы глобально, поэтому их можно указывать не внутри параметра attributes, а прямо в параметрах поля. Например:

array(
	'id'   => 'name',
	'name' => 'Name',
	'type' => 'text',
	// упрощенная установка напрямую, без обертки в 'attributes'
	'disabled'  => true,
	'required'  => true,
	'readonly'  => true,
	'maxlength' => true,
	'pattern'   => true,
),

По умолчанию: array()

Функции получения значений

В плагине предусмотрены несколько вспомогательных функций для получения данных метаполей:

rwmb_meta( $field_id, $args, $post_id ): Получает значение указанного поля. Обертка для двух следующих функций rwmb_get_value() и rwmb_the_value().
rwmb_get_value( $field_id, $args, $post_id ): Получает значение указанного поля. Тоже что и rwmb_meta().
rwmb_the_value( $field_id, $args, $post_id, $echo ): Выводит значение поля на экран. В отличии от rwmb_get_value() все выводит на экран в читаемом виде, и если, например, попытаться вывести значения checkbox list, то мы получим названия полей, а не их значения.

$field_id(строка) (обязательный)
ID поля. Указывается в параметре id при регистрации поля.
$args(строка/массив)
Дополнительные аргументы для некоторых типов полей (изображение, файл и т.д.). Можно указать в виде массива или строки в формате: param1=value1&param2=value2.
По умолчанию: array()
$post_id(число/null)
ID поста, метаполе которого надо получить. Если нет, используется текущий ID поста.
По умолчанию: null

Код всех трех функций

/**
 * Get post meta.
 *
 * @param string   $key     Meta key. Required.
 * @param array    $args    Array of arguments. Optional.
 * @param int|null $post_id Post ID. null for current post. Optional.
 *
 * @return mixed
 */
function rwmb_meta( $key, $args = array(), $post_id = null ) {
	$args  = wp_parse_args( $args );
	$field = rwmb_get_field_data( $key, $args, $post_id );
	/*
	 * If field is not found, which can caused by registering meta boxes for the backend only or conditional registration.
	 * Then fallback to the old method to retrieve meta (which uses get_post_meta() as the latest fallback).
	 */
	if ( false === $field ) {
		return apply_filters( 'rwmb_meta', rwmb_meta_legacy( $key, $args, $post_id ) );
	}
	$meta = in_array( $field['type'], array( 'oembed', 'map' ), true ) ?
		rwmb_the_value( $key, $args, $post_id, false ) :
		rwmb_get_value( $key, $args, $post_id );
	return apply_filters( 'rwmb_meta', $meta, $key, $args, $post_id );
}

/**
 * Get post meta.
 *
 * @param string   $key     Meta key. Required.
 * @param array    $args    Array of arguments. Optional.
 * @param int|null $post_id Post ID. null for current post. Optional.
 *
 * @return mixed
 */
function rwmb_meta( $key, $args = array(), $post_id = null ) {
	$args  = wp_parse_args( $args );
	$field = rwmb_get_field_data( $key, $args, $post_id );
	/*
	 * If field is not found, which can caused by registering meta boxes for the backend only or conditional registration.
	 * Then fallback to the old method to retrieve meta (which uses get_post_meta() as the latest fallback).
	 */
	if ( false === $field ) {
		return apply_filters( 'rwmb_meta', rwmb_meta_legacy( $key, $args, $post_id ) );
	}
	$meta = in_array( $field['type'], array( 'oembed', 'map' ), true ) ?
		rwmb_the_value( $key, $args, $post_id, false ) :
		rwmb_get_value( $key, $args, $post_id );
	return apply_filters( 'rwmb_meta', $meta, $key, $args, $post_id );
}

/**
 * Display the value of a field
 *
 * @param  string   $field_id Field ID. Required.
 * @param  array    $args     Additional arguments. Rarely used. See specific fields for details.
 * @param  int|null $post_id  Post ID. null for current post. Optional.
 * @param  bool     $echo     Display field meta value? Default `true` which works in almost all cases. We use `false` for  the [rwmb_meta] shortcode.
 *
 * @return string
 */
function rwmb_the_value( $field_id, $args = array(), $post_id = null, $echo = true ) {
	$args  = wp_parse_args( $args );
	$field = rwmb_get_field_data( $field_id, $args, $post_id );
	if ( ! $field ) {
		return '';
	}
	$output = RWMB_Field::call( 'the_value', $field, $args, $post_id );
	/*
	 * Allow developers to change the returned value of field.
	 * For version < 4.8.2, the filter name was 'rwmb_get_field'.
	 *
	 * @param mixed    $value   Field HTML output.
	 * @param array    $field   Field parameters.
	 * @param array    $args    Additional arguments. Rarely used. See specific fields for details.
	 * @param int|null $post_id Post ID. null for current post. Optional.
	 */
	$output = apply_filters( 'rwmb_the_value', $output, $field, $args, $post_id );
	if ( $echo ) {
		echo $output; // WPCS: XSS OK.
	}
	return $output;
}

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

Получение или вывод значений полей

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

#1 Получение и вывод единственного значения

Допустим у нас есть поле с id my_date, и это простое текстовое поле: не multiple и не повторяемое. Тогда следующий код выведет конкретное значение поля в виде строки:

$value = rwmb_meta( 'my_date' );
echo $value;

#2 Получение и вывод поля с несколькими значениями

Допустим у нас есть поле типа checkbox_list в котором хранятся интересы - это multiple поле, поэтому оно вернет массив данных:

$interests = rwmb_meta( 'interests' );
foreach ( $interests as $interest ) {
	echo $interest;
}

Заметки для разработчиков

Если поле имеет одно значение, то rwmb_meta() возвращает его как есть, если поле имеет тип multiple или clone - возвращается массив.
В зависимости от типа поля, возвращаемые данные могут иметь разную структуру. Смотрите описание поля, чтобы правильно обработать его значение.
Очень часто rwmb_meta() можно заменить функцией get_post_meta() для получения значения поля, так как она является лишь оберткой для get_post_meta() с некоторыми дополнениями, чтобы соответствовать тому, как плагин сохраняет метаднанные в базе данных.
Для некоторых полей rwmb_meta() добавляет дополнительные данные к возвращаемому значению (например, информацию об изображении), чтобы упростить работу разработчиков.

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

Ошибка PHP: функция неопределенна

Если в теме или плагине используется функция rwmb_meta(), и возникла ситуация, когда Meta Box был отключен, php выдаст ошибку «Неопределенная функция rwmb_meta ...», а сайт перестанет работать...

Чтобы избежать подобных фатальных ошибок, добавьте в тему или плагин "заглушку":

if ( ! function_exists( 'rwmb_meta' ) ) {
	function rwmb_meta(){
		return false;
	}
}

Шоткод `[rwmb_meta meta_key="key"]`

Meta Box поддерживает вывод значения поля через шоткод. Это помогает вывести значение поля в контенте поста или виджета без редактирования файлов темы.

[rwmb_meta meta_key="field_id" post_id="15" ...]

Атрибуты шоткода

meta_key(обязательный)
Ключ поля (ID).
post_id
ID поста. Если не передан, будет использован ID текущего поста.
param
Если передать другие атрибуты шоткоду, то эти атрибуты будут переданы функции rwmb_the_value() в качестве второго параметра $args. Шоткод работает на базе rwmb_the_value() - с теми же параметрами.