Languages: English • Русский • (Add your language)
API консоли (добавленное в WordPress в версии 2.7) позволяет очень просто добавлять новые виджеты в административную консоль. Для этого необходимо знание PHP и API плагинов WordPress, но авторы тем и плагинов, знакомые с хуками и фильтрами, разберутся с данным API за несколько минут, а ваши плагины от этого станут ещё более полезными.
Главным инструментом, необходимым для добавления виджетов на консоль, является функция wp_add_dashboard_widget(). Вы можете найти исчерпывающее описание этой функции по ссылке выше, или же прочитать краткое описание ниже.
Использование:
wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback = null )
Для запуска функции вам необходимо подключиться к действию 'wp_dashboard_setup' через функцию add_action(). Для консоли сетевого администрирования вам нужно использовать действие 'wp_network_dashboard_setup'.
Это пример очень простого виджета консоли. Этот код может быть размещён в одном из файлов вашего плагина, либо же в файле functions.php вашей темы.
/**
* Добавляет виджет в консоль.
*
* Эта функция подключается к действию 'wp_dashboard_setup'.
*/
function example_add_dashboard_widgets() {
wp_add_dashboard_widget(
'example_dashboard_widget', // Идентификатор виджета.
'Пример виджета консоли', // Заголовок виджета.
'example_dashboard_widget_function' // Функция отображения.
);
}
add_action('wp_dashboard_setup', 'example_add_dashboard_widgets');
/**
* Функция для вывода содержимого нашего виджета.
*/
function example_dashboard_widget_function() {
// Отображаем то, что мы хотим увидеть.
echo "Привет, мир! Я классный виджет консоли";
}
Как правило, вы должны просто позволить пользователям вашего плагина разместить ваш виджет где они хотят путём перетаскивания. В настоящее время в API нет лёгкого способа предварительной сортировки виджетов по умолчанию, что означает, что ваш новый виджет всегда будет находиться внизу списка. Пока функция сортировки не добавлена в API, обойти эту проблему непросто.
Ниже приведён пример подключаемой функции, которая пытается поместить ваш виджет перед уже существующими. Она делает это, вручную изменяя внутренний массив метабоксов (в котором виджеты консоли являются одним из типов) и помещает ваш виджет наверх списка, так что он будет показываться первым.
function example_add_dashboard_widgets() {
wp_add_dashboard_widget('example_dashboard_widget', 'Пример виджета консоли', 'example_dashboard_widget_function');
// Объявляем глобальный массив метабоксов, содержащий все виджеты административной понели WordPress
global $wp_meta_boxes;
// Получаем нормальный массив виджетов консоли
// (который уже содержит наш виджет в самом конце)
$normal_dashboard = $wp_meta_boxes['dashboard']['normal']['core'];
// Сохраняем старую версию массива и удаляем наш виджет из конца массива
$example_widget_backup = array('example_dashboard_widget' => $normal_dashboard['example_dashboard_widget']);
unset($normal_dashboard['example_dashboard_widget']);
// Объединяем два массива вместе таким образом, что наш виджет оказывается в начале
$sorted_dashboard = array_merge($example_widget_backup, $normal_dashboard);
// Сохраняем отсортированный массив обратно в метабокс
$wp_meta_boxes['dashboard']['normal']['core'] = $sorted_dashboard;
}
К сожалению, это работает только для людей, которые никогда не перераспределяют свои виджеты. Как только пользователь сделает это, его существующие настройки перезапишут эти и им придётся переместить виджет в начало вручную, что бы он остался там.
В некоторых случаях, особенно на многопользовательских блогах, может быть полезно полностью удалить виджеты из интерфейса. Каждый пользователь может, по умолчанию, выключить любой виджет используя вкладку Параметры экрана в верхней части страницы, но если у вас есть много неопытных пользователей, для них может быть проще вообще не видеть виджетов.
Для удаления виджетов консоли, используйте функцию remove_meta_box(). Смотрите пример кода ниже для понимания того, какие параметры ей следует передать.
Вот имена виджетов по умолчанию в консоли:
// Главный столбец (левый): $wp_meta_boxes['dashboard']['normal']['high']['dashboard_browser_nag'] $wp_meta_boxes['dashboard']['normal']['core']['dashboard_right_now'] $wp_meta_boxes['dashboard']['normal']['core']['dashboard_activity'] // Боковой столбец (правый): $wp_meta_boxes['dashboard']['side']['core']['dashboard_quick_press'] $wp_meta_boxes['dashboard']['side']['core']['dashboard_primary']
Вот пример функции, удаляющей виджет QuickPress.
// Создаём функцию для использования в действии
function example_remove_dashboard_widget() {
remove_meta_box('dashboard_quick_press', 'dashboard', 'side');
}
// Прикрепляем нашу функцию к действию 'wp_dashboard_setup'
add_action('wp_dashboard_setup', 'example_remove_dashboard_widget');
Функция не позволяет вам выбирать, где вы хотите расместить ваш виджет и автоматически добавляет его в "core", которое находится с левой стороны. Однако, вы можете очень просто поместить его на правую сторону.
Вы можете использовать функцию add_meta_box() вместо функции wp_add_dashboard_widget. Просто определите фактический параметр функции $post_type как 'dashboard'. Например:
add_meta_box('id', 'Заголовок виджета консоли', 'dash_widget', 'dashboard', 'side', 'high');
Либо, после создания виджета вы можете сделать это:
// Объявим глобальную переменную $wp_meta_boxes (котороя позволит нам изменить массив).
global $wp_meta_boxes;
// Сохраним старую версию нашего виджета.
$my_widget = $wp_meta_boxes['dashboard']['normal']['core']['{здесь_id_виджета}'];
// Уберём виджет из массива.
unset($wp_meta_boxes['dashboard']['normal']['core']['{здесь_id_виджета}']);
// Затем просто добавим его в массив опять (но уже на другой стороне).
$wp_meta_boxes['dashboard']['side']['core']['{здесь_id_виджета}'] = $my_widget;
Если вам нужно агрегировать RSS в вашем виджете, вы можете взглянуть, как существующий плагины устанавливаю кэширование в /wp-admin/includes/dashboard.php.
WordPress не предоставляет встроенного способа для получения параметров определённого виджета. По умолчанию, вы должны использовать функцию get_option('dashboard_widget_options') для получения всех параметров всех виджетов с последующей ручной фильтрацией массива с результатами. Этот раздел рассматривает функции, которые могут быть очень просто добавлены к теме или к плагину и которые помогают получить или установить параметры виджета.
Эта функция возвращает все параметры всех виджетов, либо только параметры определённого виджета.
/**
* Возвращает все параметры всех виджетов, либо только параметры для определённого виджета, если он указан.
*
* @param string $widget_id Необязательный. Если указан, будут возвращены параметры только этого виджета.
* @return array Ассоциативный массив
*/
public static function get_dashboard_widget_options($widget_id='')
{
// Достаём ВСЕ параметры всех виджетов из базы данных...
$opts = get_option('dashboard_widget_options');
// Если виджет не указан, возвращаем всё
if (empty($widget_id)) {
return $opts;
}
// Если указан виджет и он существует, возвращаем его
if (isset($opts[$widget_id])) {
return $opts[$widget_id];
}
// Что-то пошло не так...
return false;
}
Если вам необходимо получить только один параметр (например, для вывода в теме), следующая функция позволит это просто осуществить.
Этот пример использует предыдущий пример функции из раздела «Получение параметров виджета».
/**
* Возвращает один определённый параметр для определённого виджета.
* @param $widget_id
* @param $option
* @param null $default
*
* @return string
*/
public static function get_dashboard_widget_option($widget_id, $option, $default=NULL) {
$opts = get_dashboard_widget_options($widget_id);
// Если параметров у виджета нет, возвращаем false
if (!$opts) {
return false;
}
// В противном случае возвращаем параметр, либо используем значение по умолчанию
if (isset($opts[$option]) && !empty($opts[$option])) {
return $opts[$option];
} else {
return isset($default) ? $default : false;
}
}
Эта функция может использоваться для простого обновления всех параметров виджета. Она также может использоваться для неразрушающего добавления параметра к виджету. Просто установите аргумент $add_option в true и функция НЕ будет перезаписывать существующие параметры (но добавит любой недостающий).
/**
* Сохраняет массив параметров для простого виджета консоли в базу данных.
* Также может использоваться для определения значений по умолчанию для виджета.
*
* @param string $widget_id Название обновляемого виджета
* @param array $args Ассоциативный массив с сохраняемыми параметрами.
* @param bool $add_only Установите в <tt>true</tt>, если вы не хотите перезаписывать существующие параметры.
*/
public static function update_dashboard_widget_options($widget_id, $args=array(), $add_only=false)
{
// Достаём ВСЕ параметры всех виджетов из базы данных...
$opts = get_option('dashboard_widget_options');
// Получаем параметры нашего виджета, либо устанавливаем пустой массив
$w_opts = isset($opts[$widget_id]) ? $opts[$widget_id] : array();
if ($add_only) {
// Обновляем только отсутствующие параметры (существующие перезапишутся своими же значениями)
$opts[$widget_id] = array_merge($args, $w_opts);
} else {
// Объединяем новые параметры с существующими и добавляем их обратно в массив параметров виджетов
$opts[$widget_id] = array_merge($w_opts, $args);
}
// Сохраняем параметры всех виджетов обратно в базу данных
return update_option('dashboard_widget_options', $opts);
}