Shizumi あるクライアント様のWebサイトを制作するにあたり、とあるプラグインが必要になったので、作ってみました。
今回は、そのプラグインを作るにあたりつまずいた点などをまとめてみます。非常に初歩的な部分からのスタートですので、「初めてWordPressプラグインを作るよ！」という方の参考に少しでもなれば幸いです。
今回行った内容は、管理画面へのメニュー追加から始まり、専用データベーステーブルの作成や、その情報の呼び出しなどです。が、あまりに長くなりすぎるので、今回は管理画面へのメニュー追加までです。
WordPressのプラグインをつくる時に必要だった物まとめ -目次-
管理ページが読み込まれるときに処理を実行する
プラグインを作る上で絶対に必要というわけではありませんが、ちょっとでもユーザに設定してもらう項目が有ったり、今回私が作ったものように投稿を行う必要が有る場合など専用のページが必要になることは少なく無いと思います。
その際左側にある、メニューにリンクを追加するのが一般的です。
そのためには必ずフック(Hook)して、管理画面が呼び出されるときに追加処理を行ってもらわなければなりません。
それに必要なのが、次の関数です。
add_action( $hook, $function_to_add[, $priority[, $accepted_args]] );この関数はWordPressで管理されたページを開くときに呼び出されると処理を横入りさせてくれます。
例えばプラグインの管理ページで何かを行う必要があるときは
add_action( 'admin_menu', 'ex_function' );
function ex_function() {
// 略
}このように記述することで、処理を行うことが出来ます。
それでは使い方を詳しく説明します。
第1引数 $hook
フックされるアクションを指定します。
指定する文字列は指定されていますので、詳しくはWordPressCodexのアクションフック一覧を見てください。(英語版はこちら)
ここでは2つの例を紹介します。
- admin_menu
- 管理画面の基本構造が読み込まれた後(ヘッダータグが読み込まれた後くらい)に呼び出し指定された関数の処理を行う。
- admin_enqueue_scripts
- 管理画面を呼び出した時(ヘッダータグを読み込む前)に呼び出し指定された関数の処理を行う。
第2引数 $function_to_add
フックする関数名を指定します。
つまり、ここに指定された関数名の処理を行います。
注意点としてあくまでも指定するのは「関数名」です。
設定する値は文字列である必要が有り”()”がつくことはありません。
上記の例で言うと指定するのは’ex_function’でありex_function()ではない。ということです。
第3引数 $priority
フックした関数が実行される順番を指定します。
小さい数字であれば先に実行され、大きい数字であれば後に実施されます。
仮に同じ数が指定されていた場合は、アクションに追加された順番で実行されます。
初期値は10です。
第4引数 $accepted_args
これはadd_action()関数の補助関数であるdo_action()関数と一緒に使用します。do_action()関数を利用することで、add_action()で呼び出す関数に引数を渡すことが出来ます。$accepted_argsには、この時渡す引数の数を記述します。
初期値は1ですが、渡す引数が無くてもエラーが起きることはありませんので、渡す引数がない場合は指定する必要は無いでしょう。do_action()については機会があれば説明します。(リファレンスはこちら/英語版)
プラグインの管理メニューを追加する
さて、次は実際に管理ページにメニューの追加処理を行いましょう。add_action( 'admin_menu', 'piyo' );で指定したpiyo()関数に記述する部分です。
ここで使うのは次の関数です。
add_menu_page( $page_title, $menu_title, $capability, $menu_slug[, $function[, $icon_url[, $position]]] );
add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug[, $function] );1つづつ説明して行きましょう
add_menu_page()関数
これはトップレベルメニュー(管理画面の「投稿」や「メディア」「リンク」などの部分)の追加に使用します。
例えば、「カスタム投稿」というメニューを追加したい場合は下のようになります。
add_menu_page( 'カスタム投稿画面', 'カスタム投稿', 8, 'custom_post', 'costom_post_page' );
function costom_post_page() {
// 略
}それでは引数の説明です。
第1引数 $page_title
追加したメニューをクリックした時に呼び出されるページのタイトルを指定します。
例の場合では、呼び出されたページのタイトルが「カスタム投稿画面」になります。
第2引数 $menu_title
追加したメニュー部分に表示される文字列を指定します。
例の場合では、「カスタム投稿」というメニューが追加されることになります。
第3引数 $capability
メニューを表示するためのユーザレベルかユーザ権限の種類を指定します。
ユーザレベルやユーザ権限ついては別途詳しい説明が必要になるのですが、日本語ドキュメントどころか、本家のドキュメントでさえ更新されていない状況です。
私も今後、いろいろな実験を行いながら記事作成と日本語ドキュメントへの反映を進めてみようかと思います。
基本的に8を指定することで、管理ページに入れる人には表示されるようになります。
第4引数 $menu_slug
管理ページの名前です。
これは、利用しているWordPressプラグイン全体を通して一意である必要があります。特定のプレフィックスを付けることである程度の競合は防ぐことができるかもしれません。
また、第5引数の$functionを指定しなかった場合、呼び出すPHPファイルを指定する必要があります。
第5引数 $function
追加したメニューをクリックした時に実行される関数名を記述します。
例えば、ここに表示されるhtmlを記述したり、phpのincludeタグを利用して表示するページを呼び出したりすることができます。
この引数も、add_action()関数での$function_to_addと同様に関数の名前を指定する必要があります。
第6引数 $icon_url
追加したメニューの横に付けるアイコンのURLを指定します。
指定しなかった場合はデフォルトのアイコンが設定されます。
第7引数 $position
メニューを追加する位置を指定します。
基本的には最下部に設定されますが、数値を指定することで任意の場所に設定することが出来ます。
詳しい番号は本家リファレンスを見てください。
(投稿日現在残念ながら日本語リファレンスには詳しい内容がありません。)
以上が引数の説明です。クラスで管理している場合は設定方法が変わるなどが有りますので、細かい部分が知りたい方は本家リファレンスを御覧ください。
add_submenu_page()関数
こちらはサブメニュー(管理画面の投稿をマウスオーバーした時に表示される「投稿一覧」や「新規追加」など)の追加に使用します。
例えば、「カスタム記事」というメニューの下に「カスタム記事一覧」というサブメニューを追加する場合以下のようになります。
add_submenu_page( 'custom_post', 'カスタム記事一覧画面', 'カスタム記事一覧', 8, 'custom_post_list', 'costom_post_list_page' );
function costom_post_list_page() {
// 略
}それでは、簡単な引数の説明です。と言っても、第1引数以外は、add_menu_page() 関数と同じような内容です。
第1引数 $parent_slug
親メニューのスラッグを入力します。
例の場合では、「カスタム記事」メニューを作成した時に指定した、'custom_post'というスラッグを指定していますので、「カスタム記事」のサブメニューであると設定されます。
もちろん基本メニューのサブメニューにすることも可能で、例えば「投稿」メニューのサブメニューに設定したい場合は、'edit.php'を指定します。
基本メニューに関しては、URLのxxx.php部分を指定すれば基本的には、設定を行うことが出来ます。
詳しくは、リファレンスをご確認ください。(日本語/英語)
第2引数 $page_title
add_menu_page()関数同様、追加したメニューをクリックした時に呼び出されるページのタイトルを指定します。
例の場合では、呼び出されたページのタイトルが「カスタム記事一覧画面」になります。
第3引数 $menu_title
こちらもadd_menu_page()関数同様、追加したメニュー部分に表示される文字列を指定します。
例の場合では、「カスタム記事一覧」というメニューが追加されることになります。
第4引数 $capability
メニューを表示するためのユーザレベルかユーザ権限の種類を指定します。
これも、add_menu_page()関数同様に8を指定すれば良いと思われます。
第5引数 $menu_slug
呼び出す管理ページの名前です。
これは、利用しているWordPressプラグイン全体を通して一意である必要があります。特定のプレフィックスを付けることである程度の競合は防ぐことができるかもしれません。
これまた、add_menu_page()関数同様第6引数の$functionを指定しなかった場合、呼び出すPHPファイルを指定する必要があります。
第6引数 $function
最後もadd_menu_page()関数同様です。
追加したメニューをクリックした時に実行される関数名を記述します。
例えば、ここに表示されるhtmlを記述したり、phpのincludeタグを利用して表示するページを呼び出したりすることができます。
以上が基本的な引数の説明です。
詳しい内容は日本語リファレンスや本家リファレンスを御覧ください。
また、基本メニューを見て頂くとわかると思うのですが、例えば「投稿」をクリックしページ遷移すると、サブメニューの「投稿一覧」が選択された状態になっていることがわかると思います。
仮に、カスタム投稿ページと、投稿一覧ページの2ページを持つプラグインを作成した場合、
add_menu_page( 'カスタム投稿画面', 'カスタム投稿', 8, 'custom_post', 'costom_post_page' );
add_submenu_page( 'custom_post', 'カスタム記事一覧画面', 'カスタム記事一覧', 8, 'custom_post_list', 'costom_post_list_page' );と指定すると、メニューのカスタム投稿をクリックすると「カスタム投稿画面」に、サブメニューのカスタム記事一覧をクリックすると「カスタム記事一覧画面」に遷移するという状態になります。
これでももちろん良いのですが、使い勝手はイマイチ良くありませんし基本メニューとの統一性もありません。
そこで、
add_menu_page( 'カスタム投稿画面', 'カスタム投稿管理', 8, 'custom_post', 'costom_post_page' );
add_submenu_page( 'custom_post', 'カスタム投稿画面', 'カスタム投稿', 8, 'custom_post', 'costom_post_page' );
add_submenu_page( 'custom_post', 'カスタム記事一覧画面', 'カスタム記事一覧', 8, 'custom_post_list', 'costom_post_list_page' );このように指定します。
すると、「カスタム投稿管理」というメニューに「カスタム投稿」と「カスタム記事一覧」という2つのサブメニューが作成されるようになります。
もちろん「カスタム投稿管理」メニューをクリックした場合とサブメニューの「カスタム投稿」をクリックした場合、どちらも遷移するページは同じです。
(※もっと違和感をなくすには、一覧ページを表示するようにしたほうが良いかもしれません。)
まとめ
そもそも、この作業をする前にプラグインファイルを作成する必要があるのですが、それすらまだ書いてもいません。
そういったことも含め、今回書いていない物とか、少しずつまとめていこうかと思います。
ぼちぼち書いていこうかと思うので、こういう時どうするのー？ということが有りましたらコメント等でご連絡いただけたら次の記事になるかも知れません。