wp_add_dashboard_widget() │ WP 2.7.0

Добавляет виджет (регистрирует метабокс) в консоль (основная страница админ-панели сайта, мультисайта).

Функция должна вызываться во время событий:

wp_dashboard_setup — добавить виджет в консоль сайта (блога).
wp_network_dashboard_setup (multisite) — добавить виджет в консоль сети сайтов.
wp_user_dashboard_widgets (multisite) — добавить виджеты в консоль юзера. см is_user_admin().

Т.е. в WordPress для запуска виджетов созданных (зарегистрированных) этой функцией используются события:

do_action( 'wp_dashboard_setup' );         // консоль
do_action( 'wp_network_dashboard_setup' ); // консоль сети сайтов
do_action( 'wp_user_dashboard_widgets' );  // консоль юзера

Смотрите также: удаление виджетов из консоли.

Работает на основе: add_meta_box()

Хуков нет.

Возвращает

null. Ничего не возвращает, а добавляет метабокс.

Использование

wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback, $callback_args );

$widget_id(строка) (обязательный): Идентификатор виджета. Будет использован в CSS классе блока виджета. Станет ключом виджета в массиве виджетов.
$widget_name(строка) (обязательный): Название виджета. Будет видно в верхней части виджета. Пр.: "Последние комментарии".
$callback(callable) (обязательный): Название PHP функции, которая будет выводить на экран содержание виджета.
$control_callback(callable): Название функции, которая будет обрабатывать запрос редактирования виджета. В этой функции нужно одновременно сохранять настройки виджета и выводить HTML форму настроек.
По умолчанию: null
$callback_args(массив): Аргументы, которые будут переданы в функцию обратного вызова. callback функция получит объект $post и другие данные переданные через этот параметр.
По умолчанию: null
$context(массив) (WP 5.6): Контекст экрана, где должен отображаться виджет: normal, side, column3, column4.
По умолчанию: 'normal'
$priority(массив) (WP 5.6): Приоритет отображение в контексте: high, core, default, low.
По умолчанию: 'core'

Примеры

#1 Добавление виджета в консоль

Это демонстративный пример добавления виджета на страницу админ-панели:

// Регистрация виджета консоли
add_action( 'wp_dashboard_setup', 'add_dashboard_widgets' );

// Используется в хуке
function add_dashboard_widgets() {
	wp_add_dashboard_widget( 'my_dashboard_widget', 'Метабокс в консоли', 'my_dashboard_widget_function' );
}

// Выводит контент
function my_dashboard_widget_function( $post, $callback_args ) {
	echo 'Всем привет! Это мой первый виджет!';
}

#2 Добавление виджета в консоль сети мультисайт

Чтобы добавить виджет в консоль управления сетью, нужно вызывать функцию на хуке wp_network_dashboard_setup.

// Добавление виджета в консоль сети мультисайт
add_action( 'wp_network_dashboard_setup', function() {
	wp_add_dashboard_widget( 'my_dashboard_widget', 'Метабокс в консоли multisite', 'my_dashboard_widget_function' );
} );

function my_dashboard_widget_function( $post, $callback_args ) {
	echo 'Привет от виджета консоли сети сайтов!';
}

#3 Изменение расположения виджета

Эта функция не позволяет указать расположение виджета и по умолчанию будет располагать виджет в конец первого столбика (слева). Так как функция работает на базе функции add_meta_box(), мы можем использовать её напрямую, в ней можно указать место расположения виджета (в какую колонку его нужно добавить). Технически все виджеты добавляются в глобальный массив $wp_meta_boxes, меняя расположение виджетов в нем можно изменить их реальное расположение. Однако надо помнить, то расположение виджетов запоминается в опции юзера при их перетаскивании, а это в свою очередь может влиять на итоговое расположение элементов массива $wp_meta_boxes.

Разместим виджет в правом столбце, указав четвертый параметр "$post_type " для функции add_meta_box().

add_meta_box( 'id', 'Dashboard Widget Title', 'dash_widget', 'dashboard', 'side', 'high' );

Для сети сайтов (multisite) в 4-м параметре нужно указать dashboard-network:

add_meta_box( 'id', 'Network Dashboard Widget Title', 'widget_output_func', 'dashboard-network', 'normal', 'high' );

#4 Использование параметра `$control_callback`

С помощью $control_callback мы можем настраивать виджет. Код ниже регистрирует такой виджет:

Который имеет такой раздел настроек:

add_action( 'wp_dashboard_setup', 'prefix_add_dashboard_widget' );
function prefix_add_dashboard_widget() {

	wp_add_dashboard_widget(
		'my_dashboard_widget',
		'Основная страница в консоли',
		'prefix_dashboard_widget',
		'prefix_dashboard_widget_handle'
	);
}

function prefix_dashboard_widget() {

	// получим сохраненые данные
	if( !$widget_options = get_option( 'my_dashboard_widget_options' ) )
		$widget_options = array( );

	// вывод виджета
	$output = sprintf(
		'<h2 style="text-align:right">%s</h2>',
		__( 'Настройте виджет ☝' )
	);

	// проверим есть ли сохраненные данные
	$saved_feature_post = isset( $widget_options['feature_post'] )
		? $widget_options['feature_post'] : false;

	// произвольные контент сохраненный функцией, изменяет вывод
	if( $saved_feature_post ) {

		$post = get_post( $saved_feature_post );

		if( $post ) {
			$content = do_shortcode( html_entity_decode( $post->post_content ) );
			$output = "<h2>{$post->post_title}</h2><p>{$content}</p>";
		}
	}
	echo "<div class='feature_post_class_wrap'>
		<label style='background:#ccc;'>$output</label>
	</div>
	";
}

function prefix_dashboard_widget_handle(){

	// получим сохраненные данные
	if( !$widget_options = get_option( 'my_dashboard_widget_options' ) )
		$widget_options = array( );

	// обновление
	if( 'POST' == $_SERVER['REQUEST_METHOD'] && isset( $_POST['my_dashboard_widget_options'] ) ) {

		// проверка
		$widget_options['feature_post'] = absint( $_POST['my_dashboard_widget_options']['feature_post'] );
		// сохранение данных
		update_option( 'my_dashboard_widget_options', $widget_options );
	}

	// значения по умолчанию
	if( !isset( $widget_options['feature_post'] ) )
		$widget_options['feature_post'] = '';

	echo "<p><strong>Доступные страницы</strong></p>
	<div class='feature_post_class_wrap'>
		<label>Заголовок</label>";

	wp_dropdown_pages( array(
		'post_type'        => 'page',
		'selected'         => $widget_options['feature_post'],
		'name'             => 'my_dashboard_widget_options[feature_post]',
		'id'               => 'feature_post',
		'show_option_none' => '- выберете -'
	) );
	echo "</div>";
}

#5 Пример создания виджета для создания заметок

Пример добавляет виджет, который сохраняет заметки в опцию WP. Работает на AJAX.

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

Для WP до 5.6

<?php
/**
 * Plugin Name: Ajax WordPress Lessons
 * Description: Выводит на главной страницы админки виджет с заметками.
 * Plugin URI: https://github.com/campusboy87/lessons-ajax-wordpress
 * Author: Обучающий YouTube канал "WP-PLUS"
 * Author URI: https://www.youtube.com/c/wpplus
 */

// Регистрация виджета "Мои заметки"
add_action( 'wp_dashboard_setup', 'my_notes_dashboard_widget' );
function my_notes_dashboard_widget() {
	// Регистрируем виджет только для администраторов сайта
	if ( current_user_can( 'activate_plugins' ) ) {
		wp_add_dashboard_widget( 'my_notes', 'Мои заметки', 'my_notes_form' );
	}
}

// Отображение виджета "Мои заметки"
function my_notes_form() {
	?>

	<form>
		<textarea><?php echo esc_textarea( get_option( 'my_notes_content' ) ); ?></textarea>
		<button type="reset" class="clear button button-secondary">Очистить</button>
		<?php submit_button( null, 'primary', null, false ); ?>
	</form>

	<?php
}

// Сохранение текста заметки с помощью Ajax
add_action( 'wp_ajax_my_notes', 'my_notes_ajax_save' );
function my_notes_ajax_save() {
	check_ajax_referer( 'my_notes_nonce', 'security' );

	if ( ! isset( $_POST['my_notes_content'] ) || ! current_user_can( 'activate_plugins' ) ) {
		return;
	}

	// Получаем и чистим данные
	$notes_content = sanitize_textarea_field( wp_unslash( $_POST['my_notes_content'] ) );

	// Обновляем данные
	$status = update_option( 'my_notes_content', $notes_content, false );

	if ( $status ) {
		wp_send_json_success( [
			'message' => 'Заметка сохранена',
		] );
	} else {
		wp_send_json_error( [
			'message' => 'Заметка не изменилась',
		] );
	}

}

// Индивидуальные стили и JS скрипт для ajax сохранения из виджета "Мои заметки"
add_action( 'admin_print_scripts', 'my_notes_scripts', 999 );
function my_notes_scripts(){

	// Если это не главная страница админки - прекращаем выполнение функции
	if ( 'dashboard' != get_current_screen()->base ) {
		return;
	}
	?>
	<style>
		#my_notes textarea {
			width: 100%;
			min-height: 100px;
			margin-bottom: 5px;
		}
	</style>

	<script>
		jQuery(document).ready(function ($) {
			var $boxNotes = $('#my_notes');
			var boxTitle = $('h2 span', $boxNotes).text();

			// Очистка поля с заметками и изменение заголовка виджета на дефолтный
			$('.clear', $boxNotes).click(function () {
				$('textarea', $boxNotes).text('');
				$('h2 span', $boxNotes)
					.text('Поле очищено. Не забудьте сохранить результат!')
					.css('color', 'orangered');
			});

			// Отправка формы
			$('form', $boxNotes).submit(function (e) {
				e.preventDefault();

				// Анимация
				$boxNotes.animate({opacity: 0.5}, 300);

				// Ajax запрос
				var request = $.post(
					ajaxurl,
					{
						action: 'my_notes',
						my_notes_content: $('textarea', $boxNotes).val(),
						security: '<?php echo wp_create_nonce( "my_notes_nonce" ); ?>'
					}
				);

				// Обработка успешного запроса
				request.done(function (response) {
					var $title = $('h2 span', $boxNotes).text(response.data.message);
					if (response.success) {
						$title.css('color', 'green');
					} else {
						$title.css('color', 'orangered');
					}
				});

				// Обработка запроса с ошибкой
				request.fail(function () {
					$('h2 span', $boxNotes)
						.text('Непредвиденная ошибка!')
						.css('color', 'red');
				});

				// Обработка запроса при обоих случаях
				request.always(function () {
					$boxNotes.animate(
						{opacity: 1},
						300,
						'',
						function () {
							setTimeout(function () {
								$('h2 span', $boxNotes)
									.text(boxTitle)
									.attr('style', '');
							}, 2000);
						});
				});

			});
		});
	</script>
	<?php
}

Для WP с 5.6

<?php
/**
 * Plugin Name: Ajax WordPress Lessons
 * Description: Выводит на главной страницы админки виджет с заметками.
 * Plugin URI: https://github.com/campusboy87/lessons-ajax-wordpress
 * Author: Обучающий YouTube канал "WP-PLUS"
 * Author URI: https://www.youtube.com/c/wpplus
 */

// Регистрация виджета "Мои заметки"
add_action( 'wp_dashboard_setup', 'my_notes_dashboard_widget' );
function my_notes_dashboard_widget() {
	// Регистрируем виджет только для администраторов сайта
	if ( current_user_can( 'activate_plugins' ) ) {
		wp_add_dashboard_widget( 'my_notes', 'Мои заметки', 'my_notes_form' );
	}
}

// Отображение виджета "Мои заметки"
function my_notes_form() {
	?>

	<form>
		<textarea><?php echo esc_textarea( get_option( 'my_notes_content' ) ); ?></textarea>
		<button type="reset" class="clear button button-secondary">Очистить</button>
		<?php submit_button( null, 'primary', null, false ); ?>
	</form>

	<?php
}

// Сохранение текста заметки с помощью Ajax
add_action( 'wp_ajax_my_notes', 'my_notes_ajax_save' );
function my_notes_ajax_save() {
	check_ajax_referer( 'my_notes_nonce', 'security' );

	if ( ! isset( $_POST['my_notes_content'] ) || ! current_user_can( 'activate_plugins' ) ) {
		return;
	}

	// Получаем и чистим данные
	$notes_content = sanitize_textarea_field( wp_unslash( $_POST['my_notes_content'] ) );

	// Обновляем данные
	$status = update_option( 'my_notes_content', $notes_content, false );

	if ( $status ) {
		wp_send_json_success( [
			'message' => 'Заметка сохранена',
		] );
	} else {
		wp_send_json_error( [
			'message' => 'Заметка не изменилась',
		] );
	}

}

// Индивидуальные стили и JS скрипт для ajax сохранения из виджета "Мои заметки"
add_action( 'admin_print_scripts', 'my_notes_scripts', 999 );
function my_notes_scripts() {

	// Если это не главная страница админки - прекращаем выполнение функции
	if ( 'dashboard' != get_current_screen()->base ) {
		return;
	}
	?>
	<style>
		#my_notes textarea {
			width: 100%;
			min-height: 100px;
			margin-bottom: 5px;
		}
	</style>

	<script>
		jQuery(document).ready(function ($) {
			var $boxNotes = $('#my_notes');
			var $titleBox = $('h2', $boxNotes)
			var titleDefault = $titleBox.text();

			// Очистка поля с заметками и изменение заголовка виджета на дефолтный
			$('.clear', $boxNotes).click(function () {
				$('textarea', $boxNotes).text('');
				$titleBox
					.text('Поле очищено. Не забудьте сохранить результат!')
					.css('color', 'orangered');
			});

			// Отправка формы
			$('form', $boxNotes).submit(function (e) {
				e.preventDefault();

				// Анимация
				$boxNotes.animate({opacity: 0.5}, 300);

				// Ajax запрос
				var request = $.post(
					ajaxurl,
					{
						action: 'my_notes',
						my_notes_content: $('textarea', $boxNotes).val(),
						security: '<?php echo wp_create_nonce( "my_notes_nonce" ); ?>'
					}
				);

				// Обработка успешного запроса
				request.done(function (response) {
					$titleBox.text(response.data.message);

					if (response.success) {
						$titleBox.css('color', 'green');
					} else {
						$titleBox.css('color', 'orangered');
					}
				});

				// Обработка запроса с ошибкой
				request.fail(function () {
					$titleBox
						.text('Непредвиденная ошибка!')
						.css('color', 'red');
				});

				// Обработка запроса при обоих случаях
				request.always(function () {
					$boxNotes.animate(
						{opacity: 1},
						300,
						'',
						function () {
							setTimeout(function () {
								$titleBox
									.text(titleDefault)
									.attr('style', '');
							}, 2000);
						});
				});

			});
		});
	</script>
	<?php
}

Получим такой виджет:

Заметки

Global. callable[]. $wp_dashboard_control_callbacks

Список изменений

С версии 2.7.0	Введена.
С версии 5.6.0	The `$context` and `$priority` parameters were added.

Код `wp_add_dashboard_widget() wp add dashboard widget` ^{WP 6.7.1}

wp-admin/includes/dashboard.php

function wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback = null, $callback_args = null, $context = 'normal', $priority = 'core' ) {
	global $wp_dashboard_control_callbacks;

	$screen = get_current_screen();

	$private_callback_args = array( '__widget_basename' => $widget_name );

	if ( is_null( $callback_args ) ) {
		$callback_args = $private_callback_args;
	} elseif ( is_array( $callback_args ) ) {
		$callback_args = array_merge( $callback_args, $private_callback_args );
	}

	if ( $control_callback && is_callable( $control_callback ) && current_user_can( 'edit_dashboard' ) ) {
		$wp_dashboard_control_callbacks[ $widget_id ] = $control_callback;

		if ( isset( $_GET['edit'] ) && $widget_id === $_GET['edit'] ) {
			list($url)    = explode( '#', add_query_arg( 'edit', false ), 2 );
			$widget_name .= ' <span class="postbox-title-action"><a href="' . esc_url( $url ) . '">' . __( 'Cancel' ) . '</a></span>';
			$callback     = '_wp_dashboard_control_callback';
		} else {
			list($url)    = explode( '#', add_query_arg( 'edit', $widget_id ), 2 );
			$widget_name .= ' <span class="postbox-title-action"><a href="' . esc_url( "$url#$widget_id" ) . '" class="edit-box open-box">' . __( 'Configure' ) . '</a></span>';
		}
	}

	$side_widgets = array( 'dashboard_quick_press', 'dashboard_primary' );

	if ( in_array( $widget_id, $side_widgets, true ) ) {
		$context = 'side';
	}

	$high_priority_widgets = array( 'dashboard_browser_nag', 'dashboard_php_nag' );

	if ( in_array( $widget_id, $high_priority_widgets, true ) ) {
		$priority = 'high';
	}

	if ( empty( $context ) ) {
		$context = 'normal';
	}

	if ( empty( $priority ) ) {
		$priority = 'core';
	}

	add_meta_box( $widget_id, $widget_name, $callback, $screen, $context, $priority, $callback_args );
}

campusboy 4931 www.youtube.com/c/wpplus

А как удалить виджет из админки? К примеру вот этот:

// WordPress News
wp_add_dashboard_widget( 'dashboard_primary', __( 'WordPress News' ), 'wp_dashboard_primary' );

8 лет назад #

campusboy 4931 www.youtube.com/c/wpplus

Я нашёл ответ тут, но как-то странно, что просто ячейки массива удаляются и всё.

0

8 лет назад #
- Kama 9788
  
  Да странно, но так нормально и быстро работает... Глобальные переменные
  
  0
  
  8 лет назад #

Илья

Спасибо за статью в целом и за плагин заметок в частности (и за видео).

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

Меняем в 2х местах вывод для пользователей от 5 уровня (обычно это редакторы).
current_user_can( 'activate_plugins' ) на current_user_can( 'level_5' ).

А если надо изменить позицию на правую сторону, то вместо:

wp_add_dashboard_widget( 'my_notes', 'Общие заметки', 'my_notes_form' );

Ставим:

add_meta_box( 'my_notes', 'Общие заметки', 'my_notes_form', 'dashboard', 'side', 'low' );

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

7.2 года назад #