開発者は、ユーザーが使いやすいプラグインやテーマの開発に努めています。たとえば、EC、予約、ショーケースギャラリーなどは、すべてを1つにまとめてしまおうとしている開発者が多少なりとも存在します。
一方で、残念ながら説明の文章はないがしろにされています。たいていの場合、WordPressのプラグインディレクトリに不十分な文章があるかGitHab上のメモなどで少し触れられている程度です。せいぜい運がよくても、あまり更新されない外部のWebサイト(すぐに消えてしまうかもしれません)で目に付く程度でしかありません。
WordPressには、ダッシュボードのどこからでも利用できるコンテキストヘルプがあります。すでに見たことはあるはずです。ページ右上端に隠れている「ヘルプ」ボタンで切り替えます。
今回は、WordPressコンテキストヘルプの使い方を紹介し、テーマやプラグインの重要な部分をドキュメント化できるようにします。重要な部分とは、たとえば、通常利用される設定やショートコード、その他の機能などです。
WP_Screenの利用
新規のヘルプタブを管理ページに追加するには、WordPressが管理画面をロードする際に参照しているWP_Screenクラスを利用します。
WP_Screenクラスを直接利用するのではなく、get_current_screen()関数を利用してどの管理ページを見ているかを判断します。この関数を利用すると、投稿タイプ、分類、ベースファイルになるかなどの重要な情報がいくつかわかります。
WordPressコンテキストヘルプをすべての管理画面に追加する
ヘルプ画面を追加するのは簡単です。現在、どの管理ページを見ているか分かれば、WP_Screenクラスのadd_help_tabメソッドを呼び出せばいいだけです。
function add_context_menu_help(){
//get the current screen object
$current_screen = get_current_screen();
//content for help tab
$content = '<p>Im a help tab, woo!</p>';
//register our main help tab
$current_screen->add_help_tab( array(
'id' => 'sp_basic_help_tab',
'title' => __('Basic Help Tab'),
'content' => $content
)
);
//register our secondary help tab (with a callback instead of content)
$current_screen->add_help_tab( array(
'id' => 'sp_help_tab_callback',
'title' => __('Help Tab With Callback'),
'callback' => 'display_help_tab'
)
);
}
add_action('admin_head', 'add_context_menu_help');
//function used to display the second help tab
function display_help_tab(){
$content = '<p>This is text from our output function</p>';
echo $content;
}
ヘルプタブを追加するには2つの方法があります。1つは、インラインコンテンツを定義しadd_help_tabメソッドに渡す方法。もう1つは、タブの追加に利用する関数の名称を指定する方法です。どちらの方法でも問題ありません。
タブにid、title、コンテンツを入力すれば良いだけで、あとはWordPressがやってくれます。
コンテキストヘルプの追加を選択
すべてのページのバックエンドからヘルプタブを削除したいわけではなく、必要な場合にだけタブを表示したい場合も多くあります(たとえば、カスタマイズされた投稿の管理画面、または分類用語のリストを閲覧する場合にだけ表示したいなど)。
そういった場合に、get_current_screen()を使って収集した現在の画面のアイテムを利用して、どの画面を閲覧しているかを解析し、タブ追加の対象とするヘルプ画面を選択できます。
たとえば、カスタマイズされた「book」投稿タイプのアイテムを閲覧している場合(bookアイテムの一覧を閲覧している場合など)にだけヘルプタブを追加したい場合を考えてみましょう。
function add_help_screen_to_books(){
//get the current screen object
$current_screen = get_current_screen();
//show only on book listing page
if($current_screen->post_type == 'book' && $current_screen->base == 'edit'){
$content = '';
$content .= '<p>This is a help tab, you can add <strong>whatever</strong> it is you like here, such as instructions </p>';
$current_screen->add_help_tab( array(
'id' => 'sp_book_help_tab',
'title' => __('Book Help Tab'),
'content' => $content
)
);
}
}
add_action('admin_head', 'add_help_screen_to_books');
上記のヘルプタブは、bookコンテンツタイプの管理画面リストを閲覧している場合にのみ表示されます。現在のpost_typeとbase値を見てタブを追加します(baseを見れば、管理編集画面にいることが分かります)。
予備知識—コンテキストヘルプサイドバーの変更
コンテキストヘルプメニューには、もう1つ役立つ機能があります。サイドバーをカスタマイズすれば他の情報も表示できるのです。
ただし、set_help_sidebarを呼び出す順序には注意しましょう。このメソッドは、ヘルプタブを追加してから呼び出す必要があります。そうしないと機能しません。
異なった優先順位でadmin_headフックを使用し、set_help_sidebarを呼び出す前にヘルプタブが登録されている状態にしておくのが簡単な方法です。
思い切って自分独自のカスタマイズしたサイドバーを追加しましょう。(投稿やページまたはブックなどのタイプのいずれかの)投稿を編集する場合にのみ表示されることに注意しましょう。
//adds a sidebar to the help context menu
function add_help_sidebar(){
//get the current screen object
$current_screen = get_current_screen();
//show only on listing / single post type screens
if($current_screen->base == 'edit' || $current_screen->base == 'post'){
$current_screen->add_help_tab( array(
'id' => 'sp_book_sample',
'title' => __('Book Help Tab'),
'content' => '<p>This is a simple help tab, hi </p>'
)
);
//add the help sidebar (outputs a simple list)
$current_screen->set_help_sidebar(
'<ul><li>Here is a list item</li><li>Here is a second item</li><li>Final item</li></ul>'
);
}
}
add_action('admin_head', 'add_help_sidebar');
サイドバーがどう変わったか分かりましたか? 表示したい情報を表示できます。
注意点と役立つヒント
WordPress codexなどのさまざまなオンラインリソースで、関数をload-{name}フックの1つに入れ込むことが推奨されています。たとえば、add_action('load-post.php')を利用して投稿がロードされた場合に、関数を入れ込みます。これは問題ありません。しかし加えて、admin_headアクションに関数を入れ込んでも機能すること、そして関数が各ページにロードされること(関数の利用でヘルプタブを追加するか否かを決めることが可能であること)も分かりました。
これらのコンテキストヘルプ画面では、なんでも利用できます。ショートコードの選択肢(投稿などでVisual Editorが表示される画面上でのみ表示される)の説明を表示したい、または、コンテキストメニューの用途を広げて、最近の投稿やコメントを閲覧するような簡単な機能を追加したいと考えるかもしれません。
まとめ
WordPressコンテキストヘルプメニューはすばらしいものです。使いやすく、ユーザーに情報を提供する方法をカスタマイズできます。このメニューは、WordPress 3.3から導入された機能で、有益な情報を一目で見られます。
今後、テーマまたはプラグインを利用する場合は、これらのセクションにできるだけ多くの関連情報を追加することをぜひ検討しましょう。そうした方が、ユーザーもプラグインレポジトリやサードパーティーのWebサイトで情報を探すよりも楽でしょう。
(原文:Up and Running with WordPress Contextual Help Screens)
[翻訳:中村文也]
[編集:Livit]