概要

主な機能

ダッシュボードウィジェットを追加するために必要な主なツールは、wp_add_dashboard_widget()関数です。この関数の完全な説明はそのリンクにありますが、以下に簡単な概要を示します。

使用法

  1. wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback, $callback_args );
  • $widget_id: ウィジェットの識別スラッグ。これはCSSクラスおよびウィジェットの配列内のキーとして使用されます。
  • $widget_name: ウィジェットの見出しに表示される名前です。
  • $callback: ウィジェットの実際の内容を表示するために作成する関数の名前です。
  • $control_callback (オプション): ウィジェットオプションフォームの送信を処理し、フォーム要素を表示するために作成する関数の名前です。
  • $callback_args (オプション): コールバック関数の引数のセットです。

アクションフック

関数を実行するには、add_action()を介してアクションwp_dashboard_setupにフックする必要があります。ネットワーク管理ダッシュボードの場合は、フックwp_network_dashboard_setupを使用します。 

  1. /**
  2.  * Add a widget to the dashboard.
  3.  *
  4.  * This function is hooked into the 'wp_dashboard_setup' action below.
  5.  */
  6. function wporg_add_dashboard_widgets() {
  7.     // Add function here
  8. }
  9. add_action( 'wp_dashboard_setup', 'wporg_add_dashboard_widgets' );

ネットワークダッシュボード: 

  1. /**
  2.  * Add a widget to the network dashboard.
  3.  *
  4.  * This function is hooked into the 'wp_network_dashboard_setup' action below.
  5.  */
  6. function wporg_add_network_dashboard_widgets() {
  7.     // Add function here
  8. }
  9. add_action( 'wp_network_dashboard_setup', 'wporg_add_network_dashboard_widgets' );

例

基本的な使用法

  1. /**
  2.  * Add a widget to the dashboard.
  3.  *
  4.  * This function is hooked into the 'wp_dashboard_setup' action below.
  5.  */
  6. function wporg_add_dashboard_widgets() {
  7.     wp_add_dashboard_widget(
  8.         'wporg_dashboard_widget',                          // Widget slug.
  9.         esc_html__( 'Example Dashboard Widget', 'wporg' ), // Title.
  10.         'wporg_dashboard_widget_render'                    // Display function.
  11.     );
  12. }
  13. add_action( 'wp_dashboard_setup', 'wporg_add_dashboard_widgets' );
  15. /**
  16.  * Create the function to output the content of our Dashboard Widget.
  17.  */
  18. function wporg_dashboard_widget_render() {
  19.     // Display whatever you want to show.
  20.     esc_html_e( "Howdy! I'm a great Dashboard Widget.", "wporg" );
  21. }

ウィジェットを上部に強制する

通常、プラグインのユーザーがダッシュボードウィジェットを好きな場所にドラッグして配置できるようにするべきです。現在、デフォルトのウィジェットを事前にソートする簡単なAPIの方法はなく、新しいウィジェットは常にリストの下部に配置されます。APIにソート機能が追加されるまで、この問題を回避するのは少し複雑です。

以下は、デフォルトのウィジェットの前にウィジェットを配置しようとするフック関数の例です。これは、メタボックスの内部配列を手動で変更し（ダッシュボードウィジェットはその一種です）、ウィジェットをリストの上部に配置して最初に表示されるようにします。 

  1. function wporg_add_dashboard_widgets() {
  2.     wp_add_dashboard_widget(
  3.         'wporg_dashboard_widget',
  4.         esc_html__( 'Example Dashboard Widget', 'wporg' ),
  5.         'wporg_dashboard_widget_function'
  6.     );
  8.     // Globalize the metaboxes array, this holds all the widgets for wp-admin.
  9.     global $wp_meta_boxes;
  11.     // Get the regular dashboard widgets array
  12.     // (which already has our new widget but appended at the end).
  13.     $default_dashboard = $wp_meta_boxes['dashboard']['normal']['core'];
  15.     // Backup and delete our new dashboard widget from the end of the array.
  16.     $example_widget_backup = array( 'example_dashboard_widget' => $default_dashboard['example_dashboard_widget'] );
  17.     unset( $default_dashboard['example_dashboard_widget'] );
  19.     // Merge the two arrays together so our widget is at the beginning.
  20.     $sorted_dashboard = array_merge( $example_widget_backup, $default_dashboard );
  22.     // Save the sorted array back into the original metaboxes.
  23.     $wp_meta_boxes['dashboard']['normal']['core'] = $sorted_dashboard;
  24. }
  25. add_action( 'wp_dashboard_setup', 'wporg_add_dashboard_widgets' );

残念ながら、これはウィジェットの順序を変更したことがない人にしか機能しません。一度ユーザーが順序を変更すると、既存の設定がこれを上書きし、ウィジェットを上部に移動しなければならなくなります。

デフォルトのダッシュボードウィジェットを削除する

特にマルチユーザーブログでは、インターフェースからウィジェットを完全に削除することが有用な場合があります。各ユーザーは、デフォルトで、上部の画面オプションタブを使用して任意のウィジェットをオフにできますが、技術的でないユーザーが多い場合は、まったく見えない方が良いかもしれません。

ダッシュボードウィジェットを削除するには、remove_meta_box()関数を使用します。必要なパラメータについては、以下の例コードを参照してください。

これがダッシュボードのデフォルトウィジェットの名前です: 

  1. // Main column (left):
  2. // Browser Update Required
  3. $wp_meta_boxes['dashboard']['normal']['high']['dashboard_browser_nag'];
  4. // PHP Update Required
  5. $wp_meta_boxes['dashboard']['normal']['high']['dashboard_php_nag'];
  7. // At a Glance
  8. $wp_meta_boxes['dashboard']['normal']['core']['dashboard_right_now'];
  9. // Right Now
  10. $wp_meta_boxes['dashboard']['normal']['core']['network_dashboard_right_now'];
  11. // Activity
  12. $wp_meta_boxes['dashboard']['normal']['core']['dashboard_activity'];
  13. // Site Health Status
  14. $wp_meta_boxes['dashboard']['normal']['core']['health_check_status'];
  16. // Side Column (right):
  17. // WordPress Events and News
  18. $wp_meta_boxes['dashboard']['side']['core']['dashboard_primary'];
  19. // Quick Draft, Your Recent Drafts
  20. $wp_meta_boxes['dashboard']['side']['core']['dashboard_quick_press'];

以下は、QuickPressウィジェットを削除する関数の例です: 

  1. // Create the function to use in the action hook
  2. function wporg_remove_dashboard_widget() {
  3.     remove_meta_box( 'dashboard_quick_press', 'dashboard', 'side' );
  4. }
  5. // Hook into the 'wp_dashboard_setup' action to register our function
  6. add_action( 'wp_dashboard_setup', 'wporg_remove_dashboard_widget' );

以下の例は、すべてのダッシュボードウィジェットを削除します: 

  1. function wporg_remove_all_dashboard_metaboxes() {
  2.     // Remove Welcome panel
  3.     remove_action( 'welcome_panel', 'wp_welcome_panel' );
  4.     // Remove the rest of the dashboard widgets
  5.     remove_meta_box( 'dashboard_primary', 'dashboard', 'side' );
  6.     remove_meta_box( 'dashboard_quick_press', 'dashboard', 'side' );
  7.     remove_meta_box( 'health_check_status', 'dashboard', 'normal' );
  8.     remove_meta_box( 'dashboard_right_now', 'dashboard', 'normal' );
  9.     remove_meta_box( 'dashboard_activity', 'dashboard', 'normal');
  10. }
  11. add_action( 'wp_dashboard_setup', 'wporg_remove_all_dashboard_metaboxes' );

右側にウィジェットを追加する

この関数では、ウィジェットの配置を選択することはできず、自動的に「コア」に追加されます。これは左側です。しかし、右側に非常に簡単に配置することができます。

add_meta_box()関数をwp_add_dashboard_widgetの代わりに使用できます。単に$post_typeの代わりに「dashboard」を指定します。例えば: 

  1. add_meta_box(
  2.     'dashboard_widget_id',
  3.     esc_html__( 'Dashboard Widget Title', 'wporg' ),
  4.     'dashboard_widget',
  5.     'dashboard',
  6.     'side', 'high'
  7. );

または、ウィジェットを作成した後: 

  1. function wporg_add_dashboard_widget() {
  2.     wp_add_dashboard_widget(
  3.         'wporg_dashboard_widget',
  4.         esc_html__( 'Example Dashboard Widget', 'wporg' ),
  5.         'wporg_dashboard_widget_function'
  6.     );
  8.     // Global the $wp_meta_boxes variable (this will allow us to alter the array).
  9.     global $wp_meta_boxes;
  11.     // Then we make a backup of your widget.
  12.     $wporg_widget = $wp_meta_boxes['dashboard']['normal']['core']['wporg_dashboard_widget'];
  14.     // We then unset that part of the array.
  15.     unset( $wp_meta_boxes['dashboard']['normal']['core']['wporg_dashboard_widget'] );
  17.     // Now we just add your widget back in.
  18.     $wp_meta_boxes['dashboard']['side']['core']['wporg_dashboard_widget'] = $wporg_widget;
  19. }
  20. add_action( 'wp_dashboard_setup', 'wporg_add_dashboard_widget' );

ダッシュボードでのRSSフィードの集約

ウィジェットでRSSを集約する必要がある場合は、/wp-admin/includes/dashboard.phpでキャッシュを使用して既存のプラグインがどのように設定されているかを確認してください。

ウィジェットオプション

WordPressは特定のウィジェットのオプションを取得するための組み込みの方法を提供していません。デフォルトでは、get_option( 'dashboard_widget_options' )を使用してすべてのウィジェットオプションを取得し、返された配列を手動でフィルタリングする必要があります。このセクションでは、ウィジェットオプションの取得と設定を支援するために、テーマやプラグインに簡単に追加できるいくつかの関数を紹介します。

ウィジェットオプションの取得

この関数は、すべてのウィジェットオプション、または指定されたウィジェットのオプションのみを取得します: 

  1. /**
  2.  * Gets all widget options, or only options for a specified widget if a widget id is provided.
  3.  *
  4.  * @param string $widget_id Optional. If provided, will only get options for that widget.
  5.  * @return array An associative array
  6.  */
  7. function wporg_get_dashboard_widget_options( $widget_id = '' ) {
  8.    // Fetch ALL dashboard widget options from the db
  9.    $options = get_option( 'dashboard_widget_options' );
  11.    // If no widget is specified, return everything
  12.    if ( empty( $widget_id ) ) {
  13.    return $options;
  14.    }
  16.    // If we request a widget and it exists, return it
  17.    if ( isset( $options[$widget_id] ) ) {
  18.    return $options[$widget_id];
  19.    }
  21.    // Something went wrong...
  22.    return false;
  23. }

単一ウィジェットオプションの取得

単一のオプション（テーマに出力するため）を簡単に取得したい場合、以下の関数がそれを容易にします。

この例は、前のウィジェットオプションの取得の例関数と一緒に使用する必要があります。 

  1. /**
  2.  * Gets one specific option for the specified widget.
  3.  *
  4.  * @param  string $widget_id Widget ID.
  5.  * @param  string $option    Widget option.
  6.  * @param  string $default   Default option.
  7.  *
  8.  * @return string            Returns single widget option.
  9.  */
  10. function wporg_get_dashboard_widget_option( $widget_id, $option, $default = NULL ) {
  11.     $options = wporg_get_dashboard_widget_options( $widget_id );
  13.     // If widget options don't exist, return false.
  14.     if ( ! $options ) {
  15.         return false;
  16.     }
  18.     // Otherwise fetch the option or use default
  19.     if ( isset( $options[$option] ) && ! empty( $options[$option] ) ) {
  20.         return $options[$option];
  21.     } else {
  22.         return ( isset( $default ) ) ? $default : false;
  23.     }
  24. }

ウィジェットオプションの更新

この関数は、ウィジェットのすべてのオプションを簡単に更新するために使用できます。また、ウィジェットオプションを非破壊的に追加するためにも使用できます。$add_option引数をtrueに設定するだけで、既存のオプションを上書きしません（不足しているものは追加されます）。 

  1. /**
  2.  * Saves an array of options for a single dashboard widget to the database.
  3.  * Can also be used to define default values for a widget.
  4.  *
  5.  * @param string $widget_id  The name of the widget being updated
  6.  * @param array $args        An associative array of options being saved.
  7.  * @param bool $add_only     Set to true if you don't want to override any existing options.
  8.  */
  9. function update_dashboard_widget_options( $widget_id , $args = array(), $add_only = false ) {
  10.     // Fetch ALL dashboard widget options from the db...
  11.     $options = get_option( 'dashboard_widget_options' );
  13.     // Get just our widget's options, or set empty array.
  14.     $widget_options = ( isset( $options[$widget_id] ) ) ? $options[$widget_id] : array();
  16.     if ( $add_only ) {
  17.         // Flesh out any missing options (existing ones overwrite new ones).
  18.         $options[$widget_id] = array_merge( $args, $widget_options );
  19.     } else {
  20.         // Merge new options with existing ones, and add it back to the widgets array.
  21.         $options[$widget_id] = array_merge( $widget_options, $args );
  22.     }
  24.     // Save the entire widgets array back to the db.
  25.     return update_option( 'dashboard_widget_options', $options );
  26. }

関連情報

例のダッシュボードウィジェットを参照して、さらに多くの例を確認してください。