wp_add_dashboard_widget() │ WP 2.7.0

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

// Регистрация виджета консоли
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 'Всем привет! Это мой первый виджет!';
}

Чтобы добавить виджет в консоль управления сетью, нужно вызывать функцию на хуке 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 'Привет от виджета консоли сети сайтов!';
}

Эта функция не позволяет указать расположение виджета и по умолчанию будет располагать виджет в конец первого столбика (слева). Так как функция работает на базе функции 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' );

С помощью $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>";
}

Пример добавляет виджет, который сохраняет заметки в опцию 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
}

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