WordPress как на ладони
wordpress jino

wp_add_dashboard_widget() WP 2.7

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

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

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

Хуков нет.

Возвращает

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

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

wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback, $callback_args );
$widget_id(строка) (обязательный)
Идентификатор виджета. Будет использован в CSS классе блока виджета. Станет ключом виджета в массиве виджетов.
$widget_name(строка) (обязательный)
Название виджета. Будет видно в верхней части виджета. Пр.: "Последние комментарии".
$callback(строка) (обязательный)
Название PHP функции, которая будет выводить на экран содержание виджета.
$control_callback(строка)
Название функции которая будет обрабатывать запрос редактирования виджета. В этой функции нужно сохранять настройки виджета и выводить форму настроек.
По умолчанию: null
$callback_args(массив) (обязательный)
Аргументы, которые будут переданы в функцию обратного вызова. callback функция получит объект $post и другие параметры переданные через эту переменную.
По умолчанию: null

Примеры

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

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

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

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

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

#2 Запуск Виджета Консоли

Чтобы правильно запустить (вызвать) функцию, используйте событие, а не вызывайте функцию напрямую, как это принято в PHP:

do_action('wp_dashboard_setup');

#3 Расположение виджета скраю

wp_add_dashboard_widget() не позволяет указать расположение виджета и по умолчанию будет располагать виджет в конец первого столбика (слева). Этот пример показывает как расположить виджет справа.

wp_add_dashboard_widget() работает на основе add_meta_box(), используем 4-й параметр $post_type укажем dashboard:

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

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

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

widget

И также регистрирует страницу настроек виджета:

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.

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

<?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() {
	global $screen;

	// Если это не главная страница админки - прекращаем выполнение функции
	if ( 'dashboard' != $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 add dashboard widget: wp-admin/includes/dashboard.php WP 4.8.2

<?php
function wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback = null, $callback_args = null ) {
	$screen = get_current_screen();
	global $wp_dashboard_control_callbacks;

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

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

	if ( $control_callback && current_user_can( 'edit_dashboard' ) && is_callable( $control_callback ) ) {
		$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' );

	$location = 'normal';
	if ( in_array($widget_id, $side_widgets) )
		$location = 'side';

	$priority = 'core';
	if ( 'dashboard_browser_nag' === $widget_id )
		$priority = 'high';

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

Cвязанные функции

Из метки: metabox (метабоксы)

Еще из раздела: Админ-панель

wp_add_dashboard_widget 4 комментария
  • campusboy1844 cайт: wp-plus.ru

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

    // WordPress News
    wp_add_dashboard_widget( 'dashboard_primary', __( 'WordPress News' ), 'wp_dashboard_primary' );
  • Илья

    Спасибо за статью в целом и за плагин заметок в частности (и за видео). У меня включены отображения ошибок и на странице записи выводится замечание:

    Notice: Trying to get property of non-object in ... on line

    Ругается на этот участок:
    // if ( 'dashboard' != $screen->base ) {
    // return;
    // }

    Я это закомментировал, но наверное правильно было бы это как-то исправить?

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

    Меняем в 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.

    Ответить14 дней назад #

Здравствуйте, !

Ваш комментарий