wp_add_dashboard_widget() │ WP 2.7.0

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

Функція має викликатися під час подій:

wp_dashboard_setup – додати віджет в консоль сайту (блогу).
wp_network_dashboard_setup (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 ми можемо налаштовувати віджет. Код нижче реєструє такий віджет:

Який має такий розділ налаштувань:

widge2t2

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.

Код стане в нагоді, коли потрібно просто зберегти текст, введений у поле текстуобласті. Прямо в дашборді тут, на місці. Наприклад, написав собі на згадку, що потрібно зробити, виправити і т.д., натиснув кнопку зберегти, і воно висить собі. Зробив, стер, написав інше, зберіг – висить інше.

Для 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	`$context` and $ `priority` parameters були added.

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

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 );
}

wp_add_dashboard_widget() │ WP 2.7.0

Повертає

Використання

Приклади

#1 Додавання віджету в консоль

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

#3 Зміна розташування віджету

#4 Використання параметра $control_callback

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

нотатки

список змін

Код wp_add_dashboard_widget() wp add dashboard widget WP 6.0.2

Зв’язані функції

metabox (метабокси віджети)

Адмін панель

Залишити відповідь Скасувати коментар

#4 Використання параметра `$control_callback`

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