ダッシュボードウィジェット API

WordPress 2.7 のリリースで、新しいダッシュボードウィジェット API が導入されました。 管理画面ダッシュボード に新しいウィジェットを追加するのがシンプルになりました。PHP と WordPress プラグイン API の知識が必要ですが、アクションフックやフィルターフックに精通したプラグイン/テーマ作成者なら数分でできるでしょう。これにより、プラグインを一層使いやすくなるでしょう。

目次 1 概要 1.1 関数 1.2 動作 2 用例 2.1 ウィジェットを追加する 2.2 上級: ウィジェットを一番上にする 2.3 上級: ダッシュボードウィジェットを取り除く 2.4 ダッシュボードで RSS フィードを統合する

概要

関数

ダッシュボードの追加に必要な主要なツールは wp_add_dashboard_widget() 関数です。

wp_add_dashboard_widget($widget_id, $widget_name, $callback, $control_callback = null)

• $widget_id - ウィジェットを一意識別するスラッグ。これは css クラス、ウィジェットの配列のキーに使用します。
• $widget_name - ウィジェットのヘッダに表示される名前。
• $callback - ウィジェットのコンテンツを表示するように作成した関数の名前。
• $control_callback - (オプション) ウィジェットオプションフォームの送信を処理し、フォーム要素を表示する関数の名前。

動作

関数を実行するには、適切な動作をフックする必要があります。この場合 'wp_dashboard_setup' です。コアコードは以下の通りです。

do_action( 'wp_dashboard_setup' );

用例

ウィジェットを追加する

ウィジェットのもっとも簡単なアウトラインです。

// ダッシュボードウィジェットにコンテンツを出力する関数を作成する

function example_dashboard_widget_function() {
	// Display whatever it is you want to show
	echo "Hello World, I'm a great Dashboard Widget";
} 

// アクションフックで使用する関数を作成する

function example_add_dashboard_widgets() {
	wp_add_dashboard_widget('example_dashboard_widget', 'Example Dashboard Widget', 'example_dashboard_widget_function');	
} 

// 'wp_dashboard_setup' アクションにフックし、登録する

add_action('wp_dashboard_setup', 'example_add_dashboard_widgets' );

上級: ウィジェットを一番上にする

通常は、プラグインの利用者がドラッグして好きな位置にダッシュボードウィジェットを配置できるようにすべきです。デフォルトウィジェットを予め並べるための簡単な API はありません。新しいウィジェットは一番下に配置されます。API にソートが追加されるまでは、この問題を処理するのは相当複雑です。

あなたのウィジェットをデフォルトよりも前に配置する例を以下に示します。metaboxes (ダッシュボードウィジェットもこの 1 つです) の内部配列を手作業で変更して、あなたのウィジェットをリストの先頭にし、最初に表示されるようにします。

function example_add_dashboard_widgets() {
	wp_add_dashboard_widget('example_dashboard_widget', 'Example Dashboard Widget', 'example_dashboard_widget_function');
	
	// Globalize the metaboxes array, this holds all the widgets for wp-admin

	global $wp_meta_boxes;
	
	// Get the regular dashboard widgets array 
	// (which has our new widget already but at the end)

	$normal_dashboard = $wp_meta_boxes['dashboard']['normal']['core'];
	
	// Backup and delete our new dashbaord widget from the end of the array

	$example_widget_backup = array('example_dashboard_widget' => $normal_dashboard['example_dashboard_widget']);
	unset($normal_dashboard['example_dashboard_widget']);

	// Merge the two arrays together so our widget is at the beginning

	$sorted_dashboard = array_merge($example_widget_backup, $normal_dashboard);

	// Save the sorted array back into the original metaboxes 

	$wp_meta_boxes['dashboard']['normal']['core'] = $sorted_dashboard;
} 

残念ながら、この方法は、ウィジェットを並べ替えたことがない場合にのみ動作します。利用者が並べ替えた場合は、利用者の選好が優先されます。あなたのウィジェットを手作業で一番上に移動する必要があります。

上級: ダッシュボードウィジェットを取り除く

ある場合は、特に複数ユーザーでブログを書く場合等は、インターフェースからウィジェットを取り除くことが役立つかもしれません。各ユーザーは、管理画面上部の "表示オプション" タブでウィジェットを表示しなくすることができます。技術に詳しくないユーザーがたくさんいる場合は、そもそも見せないのが好ましいでしょう。

現在 (2.7.0) は、デフォルトのダッシュボードウィジェットを取り除く簡単な関数はありません。取り除くには、一般 $wp_meta_box 配列からアイテムを手動で unset() する必要があります。ウィジェットを追加するのと似た方法で wp_dashboard_setup で行います。

ダッシュボードのメタボックスの名前です。
主カラム
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_right_now']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_recent_comments']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_incoming_links']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_plugins']

副カラム
$wp_meta_boxes['dashboard']['side']['core']['dashboard_quick_press']
$wp_meta_boxes['dashboard']['side']['core']['dashboard_recent_drafts']
$wp_meta_boxes['dashboard']['side']['core']['dashboard_primary']
$wp_meta_boxes['dashboard']['side']['core']['dashboard_secondary']

主カラムまたは副カラムで名前のリストを表示するには、以下のコードを使用してください(配列の 2 番めで主/副を設定)。:

foreach (array_keys($wp_meta_boxes['dashboard']['normal']['core']) as $name){
		echo ("<p>");
		echo ($name);
		echo("</p>");
		
	}

quickpress と incomming_links ウィジェットを unset して取り除く例です。

// Create the function to use in the action hook

function example_remove_dashboard_widgets() {
	// Globalize the metaboxes array, this holds all the widgets for wp-admin

	global $wp_meta_boxes;

	// Remove the quickpress widget

	unset($wp_meta_boxes['dashboard']['side']['core']['dashboard_quick_press']);

	// Remove the incomming links widget

	unset($wp_meta_boxes['dashboard']['normal']['core']['dashboard_incoming_links']);	
} 

// Hoook into the 'wp_dashboard_setup' action to register our function

add_action('wp_dashboard_setup', 'example_remove_dashboard_widgets' );

ダッシュボードで RSS フィードを統合する

多くのデフォルトダッシュボードウィジェットは WordPress の開発とプラグインについての RSS フィードを統合するように設計されているので、簡単に行うために多くの努力がなされています。完全な例を示すことはしませんが、ウィジェットに RSS を統合する必要がある場合は、/wp-admin/includes/dashboard.php の既存のプラグインがキャッシュ機能を含めてどのように設計されているかを見ることをおすすめします。

最新英語版： WordPress Codex » Dashboard Widgets API （最新版との差分）