• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

「設定ページの作成」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(原文更新のため)
(はじめに: 表記ゆれ)
 
(2人の利用者による、間の3版が非表示)
1行目: 1行目:
<span style="color:red">This article is in transition to meet [[Settings API]], which was introduced in [[Version 2.7]]. For information prior to 2.7 see [http://codex.wordpress.org/index.php?title=Creating_Options_Pages&oldid=97268 this revision.]</span>
+
<span style="color:red">この記事は、 [[Version 2.7]] で導入された [[Settings API]] に合わせて更新されています。2.7 より古いバージョンの場合は [http://wpdocs.sourceforge.jp/wiki/index.php?title=%E8%A8%AD%E5%AE%9A%E3%83%9A%E3%83%BC%E3%82%B8%E3%81%AE%E4%BD%9C%E6%88%90&oldid=2797 履歴] をごらんください。</span>
  
== Introduction ==
+
== はじめに ==
  
Creating custom options panels in WordPress is relatively easy.
+
WordPressにカスタムの設定画面を作ることは比較的簡単です。
  
First, to create the menu item and the new page, see [[Adding Administration Menus]].
+
メニューアイテムと新しいページを作るには、まず[[Adding Administration Menus | 管理メニューの追加]]を見てください。
  
So long as you stick to this structure, WordPress will handle all of the option creation, update, saving, and redirection for you. It will check permissions, and do all that other magic behind the scenes.
+
この構造に従う限りは、WordPressがあなたの代わりに作成、更新、保存、リダイレクトといった設定を行ってくれます。パーミッションをチェックし、裏側で起きているすべてを魔法のように執り行うのです。
  
Several new functions were added in WordPress 2.7. These new functions are optional in WordPress 2.7 but will be required in the future. They are required for WordPress MU 2.7. See [[Migrating Plugins and Themes to 2.7]] and [[Settings API]] for more information.
+
WordPress 2.7 でいくつかの関数が追加されました。WordPress 2.7 時点では、これらの関数を使うかどうかは任意選択ですが、将来必須になるでしょう。WordPress MU 2.7 では必須です。詳細は [[Migrating Plugins and Themes to 2.7]] [[Settings API]] をごらんください。
  
This article only covers the markup of the Settings page itself. For more information regarding how to add the Settings page, refer to [[Administration Menus]]
+
この記事は、設定ページのマークアップのみを説明しています。設定ページの追懐については、[[Administration Menus | 管理メニュー]]をごらんください。
  
== Where to Save the Code ==
+
== コードの保存先 ==
  
You can either put the code for your options page in your plugin php file (or, for Themes, in functions.php), or you can create a second file called options.php, for example, and include it using the php include function - http://php.net/manual/en/function.include.php
+
オプションページのコードは、プラグインの PHP ファイル (テーマの場合は functions.php) 内に置くか、options.php のようなファイルを作成し、php の include 関数 - http://php.net/manual/en/function.include.php を使うことができます。
  
== Opening the Page ==
+
== ページの開始 ==
  
If you'd like to match the look and feel of existing WordPress options pages, open with the following:
+
既存の WordPress オプションページの見た目に合わせたい場合、以下のように開始します。
 
  &lt;div class="wrap">
 
  &lt;div class="wrap">
 
  &lt;h2>Your Plugin Page Title</h2>
 
  &lt;h2>Your Plugin Page Title</h2>
  
== Form Tag ==
+
== Form タグ ==
 +
 
 +
ページを作ったら、HTMLフォームを作る必要があります。このコードを使ってください:
  
Once you have your page, you need to create an HTML form. Use this code:
 
 
  <form method="post" action="options.php">  
 
  <form method="post" action="options.php">  
  
  
=== settings_fields Function ===
+
=== settings_fields 関数 ===
  
The setting fields will know which settings your options page will handle.
+
setting fields が、オプションページの設定を上手く処理してくれます。
  
After the opening form tag, add this function
+
開始 form タグの後、以下の関数を追加します。
  
 
  settings_fields( 'myoption-group' );
 
  settings_fields( 'myoption-group' );
  
where <tt>myoption-group</tt> is the same name used in the [[Function Reference/register_setting|register_setting]] function.
+
ここで <tt>myoption-group</tt> [[関数リファレンス/register_setting|register_setting]] 関数で使用した名前と同じにします。
  
This function '''replaces''' the '''nonce magic''', '''action field''', and '''page_options field''' required prior to Version 2.7.
+
Version 2.7 以前では、'''nonce magic''', '''action field''', そして '''page_options field''' が必須でしたが、この関数が面倒みてくれます。
  
=== do_settings_fields Function ===
+
=== do_settings_fields 関数 ===
  
After the settings_fields() call, add this function
+
settings_fields() を呼び出した後、以下の関数を追加します。
  
 
  do_settings_sections( 'myoption-group' );
 
  do_settings_sections( 'myoption-group' );
  
This function '''replaces''' the form-field markup in the form itself.
+
この関数は、フォームのマークアップ自体を面倒みてくれます。
 +
 
 +
== 終了タグ ==
  
== Closing Tags ==
+
それでは、その他の設定を入力して、formタグを閉じましょう。WordPressのデフォルトである"設定を更新"ボタンを使うこともできます。
  
Then obviously close the form tag after your other options, and if you like, include another "Update Options" button, this is the WordPress default.
 
 
  <?php submit_button(); ?>
 
  <?php submit_button(); ?>
 
  </form>
 
  </form>
 
  </div>
 
  </div>
  
You can personalize the button created by [[Function_Reference/submit_button|submit_button]] function.
+
[[関数リファレンス/submit_button|submit_button]] 関数でボタンを作成することができます。
  
Note the use of the _e() function to handle translation of the text, see [[Localizing WordPress]] for more info.
+
テキストを翻訳対応にするためには、_e()関数を使うようにしてください。詳しくは [[Localizing WordPress | WordPress の翻訳]]を参照してください。
  
 
=== Register Settings ===
 
=== Register Settings ===
  
The [[Function Reference/register setting|register_setting]] and [[Function Reference/unregister setting|unregister_setting]] functions add and remove options from a whitelist of allowed options that the form is able to save. They can also name a sanitize callback function as a security measure to check each option's value.
+
[[関数リファレンス/register setting|register_setting]] 関数と [[関数リファレンス/unregister setting|unregister_setting]] 関数は、フォームが保存できるオプションのホワイトリストにオプションを追加/削除します。セキュリティのために、各オプションの値をチェックするコールバック関数を指定できます。
  
The register_setting function should be called in an [[Plugin API/Action Reference#Administrative Actions|admin_init]] action, which runs before every admin page and in particular, <tt>options.php</tt>, which receives this form.
+
register_setting 関数は [[Plugin API/Action Reference#Administrative Actions|admin_init]] アクションフックで呼び出されるべきです。このフックは他の管理ページよりも先に呼び出され、このフォームを受け取る <tt>options.php</tt> よりも先に呼び出されます。
  
Your plugin probably has a section with an add_action that adds a new menu item to the administration menus. This line will be in the same section to add an action to admin_init.
+
あなたのプラグインには、新しいメニューを追加する add_action セクションがあるかもしれません。This line will be in the same section to add an action to admin_init.
  
 
<pre>
 
<pre>
77行目: 79行目:
 
</pre>
 
</pre>
  
Then you create a new function that registers each option.
+
それから各オプションを登録する関数を作成します。
  
 
<pre>
 
<pre>
87行目: 89行目:
 
</pre>
 
</pre>
  
The name of <tt>myoption-group</tt> doesn't matter but it has to match the name used in the settings_fields function above.
+
<tt>myoption-group</tt> の名前はなんでも良いですが、上述の settings_fields 関数で使用する名前と同じにしてください。
  
 +
=== すべてを纏める ===
 +
注意: 例のいくつかは(とくに do_settings は) 古い書き方かもしれません。 [http://ottopress.com/2009/wordpress-settings-api-tutorial/ View Otto's tutorial here for better examples of workable code].  ほかにも [http://planetozh.com/blog/about/ ozh] による [http://planetozh.com/blog/2009/05/handling-plugins-options-in-wordpress-28-with-register_setting/ article] があります。
  
 
+
オプションページにアイコンを追加するには以下のコード [3.4.2 以降で使用可能] を用いてください。アイコンはテーマフォルダの "images" フォルダ内にあります。
=== See It All Together ===
+
Please note: Some of the code in this example (particularly do_settings) is deprecated. [http://ottopress.com/2009/wordpress-settings-api-tutorial/ View Otto's tutorial here for better examples of workable code].  In addition, there's another [http://planetozh.com/blog/2009/05/handling-plugins-options-in-wordpress-28-with-register_setting/ article] available by [http://planetozh.com/blog/about/ ozh].
+
 
+
To add icon to for your options page use the following code [this will work on version 3.4.2 and later] In following example, icon is stored in "images" folder in theme directory.
+
  
 
<pre><?php add_menu_page('BAW Plugin Settings', 'BAW Settings', 'administrator', __FILE__, 'baw_settings_page', get_stylesheet_directory_uri('stylesheet_directory')."/images/media-button-other.gif"); ?></pre>
 
<pre><?php add_menu_page('BAW Plugin Settings', 'BAW Settings', 'administrator', __FILE__, 'baw_settings_page', get_stylesheet_directory_uri('stylesheet_directory')."/images/media-button-other.gif"); ?></pre>
  
The below example uses the new Settings API to create and save your plugin options
+
Settings API を使用してプラグインのオプションを作成/保存する例です。
 
<pre>
 
<pre>
 
<?php
 
<?php
132行目: 132行目:
 
         <tr valign="top">
 
         <tr valign="top">
 
         <th scope="row">New Option Name</th>
 
         <th scope="row">New Option Name</th>
         <td><input type="text" name="new_option_name" value="<?php echo get_option('new_option_name'); ?>" /></td>
+
         <td><input type="text" name="new_option_name" value="<?php echo esc_attr( get_option('new_option_name') ); ?>" /></td>
 
         </tr>
 
         </tr>
 
          
 
          
 
         <tr valign="top">
 
         <tr valign="top">
 
         <th scope="row">Some Other Option</th>
 
         <th scope="row">Some Other Option</th>
         <td><input type="text" name="some_other_option" value="<?php echo get_option('some_other_option'); ?>" /></td>
+
         <td><input type="text" name="some_other_option" value="<?php echo esc_attr( get_option('some_other_option') ); ?>" /></td>
 
         </tr>
 
         </tr>
 
          
 
          
 
         <tr valign="top">
 
         <tr valign="top">
 
         <th scope="row">Options, Etc.</th>
 
         <th scope="row">Options, Etc.</th>
         <td><input type="text" name="option_etc" value="<?php echo get_option('option_etc'); ?>" /></td>
+
         <td><input type="text" name="option_etc" value="<?php echo esc_attr( get_option('option_etc') ); ?>" /></td>
 
         </tr>
 
         </tr>
 
     </table>
 
     </table>
153行目: 153行目:
 
</pre>
 
</pre>
  
==== Example #2 ====
+
==== #2 ====
  
This example works on WP 3.5.1.  Much simpler and simply works.  This is an updated version of [http://ottopress.com/2009/wordpress-settings-api-tutorial/ Otto's tutorial].
+
この例は WP 3.5.1 で動作します。より簡単なコードです。 [http://ottopress.com/2009/wordpress-settings-api-tutorial/ Otto's tutorial] を新しくしたものです。
  
 
<pre>
 
<pre>
300行目: 300行目:
 
</pre>
 
</pre>
  
This will create something like this:
+
以下のようなページを作成します。
  
[[File:creating-options-pages-ex-2b.png]]
+
[[Image:creating-options-pages-ex-2b.png]]
  
==== Pitfalls ====
+
==== 落とし穴 ====
The '''Settings''' name, the second parameter in the ''register_setting()'' function, MUST match the name of the option being updated in the database!
+
''register_setting()'' 関数の第二引数の「設定」名は、データベースで更新されるオプション名と同じでなけれななりません。
 
<br />
 
<br />
For example, say you have '''add_option( 'foo_bar', 'isfoo' )''', you MUST use '''foo_bar''' as the second parameter for the '''register_setting()''' function.  Otherwise WordPress does not know which setting it is suppose to update and it will fail to update.
+
たとえば '''add_option( 'foo_bar', 'isfoo' )''' を使う場合、'''register_setting()''' 関数の第二引数は'''foo_bar''' でなければなりません。そうしないと、WordPress はどのオプションを更新してよいのか分からなくなります。
  
To show the menu in '''Multisite''' network screen, it would be a matter of doing:<br />
+
To show the menu in '''Multisite''' screen, it would be a matter of doing:<br />
 
<tt>add_action( is_multisite() ? 'network_admin_menu' : 'admin_menu', 'callback_function' );</tt><br />
 
<tt>add_action( is_multisite() ? 'network_admin_menu' : 'admin_menu', 'callback_function' );</tt><br />
 
But the form save action leads to a 404 page: <tt>/wp-admin/network/options.php</tt>.<br />
 
But the form save action leads to a 404 page: <tt>/wp-admin/network/options.php</tt>.<br />
 
To solve it, use the solution in [http://wordpress.stackexchange.com/a/72503 this WordPress Answers post], or alternatively the one in [http://code.hyperspatial.com/1250/save-plugin-options-multisite-3-1/ this blog post].
 
To solve it, use the solution in [http://wordpress.stackexchange.com/a/72503 this WordPress Answers post], or alternatively the one in [http://code.hyperspatial.com/1250/save-plugin-options-multisite-3-1/ this blog post].
[[Category:Plugins]]
+
 
[[Category:WordPress Development]]
+
{{原文|Creating_Options_Pages|145513}}<!--  08:03, 11 August 2014 Ounziw 版 -->
[[Category:Advanced Topics]]
+
[[Category:プラグイン]]
 +
[[Category:WordPress の開発]]
 +
[[Category:上級トピック]]

2015年8月15日 (土) 17:45時点における最新版

この記事は、 Version 2.7 で導入された Settings API に合わせて更新されています。2.7 より古いバージョンの場合は 履歴 をごらんください。

はじめに

WordPressにカスタムの設定画面を作ることは比較的簡単です。

メニューアイテムと新しいページを作るには、まず 管理メニューの追加を見てください。

この構造に従う限りは、WordPressがあなたの代わりに作成、更新、保存、リダイレクトといった設定を行ってくれます。パーミッションをチェックし、裏側で起きているすべてを魔法のように執り行うのです。

WordPress 2.7 でいくつかの関数が追加されました。WordPress 2.7 時点では、これらの関数を使うかどうかは任意選択ですが、将来必須になるでしょう。WordPress MU 2.7 では必須です。詳細は Migrating Plugins and Themes to 2.7Settings API をごらんください。

この記事は、設定ページのマークアップのみを説明しています。設定ページの追懐については、 管理メニューをごらんください。

コードの保存先

オプションページのコードは、プラグインの PHP ファイル (テーマの場合は functions.php) 内に置くか、options.php のようなファイルを作成し、php の include 関数 - http://php.net/manual/en/function.include.php を使うことができます。

ページの開始

既存の WordPress オプションページの見た目に合わせたい場合、以下のように開始します。

<div class="wrap">
<h2>Your Plugin Page Title</h2>

Form タグ

ページを作ったら、HTMLフォームを作る必要があります。このコードを使ってください:

<form method="post" action="options.php"> 


settings_fields 関数

setting fields が、オプションページの設定を上手く処理してくれます。

開始 form タグの後、以下の関数を追加します。

settings_fields( 'myoption-group' );

ここで myoption-groupregister_setting 関数で使用した名前と同じにします。

Version 2.7 以前では、nonce magic, action field, そして page_options field が必須でしたが、この関数が面倒みてくれます。

do_settings_fields 関数

settings_fields() を呼び出した後、以下の関数を追加します。

do_settings_sections( 'myoption-group' );

この関数は、フォームのマークアップ自体を面倒みてくれます。

終了タグ

それでは、その他の設定を入力して、formタグを閉じましょう。WordPressのデフォルトである"設定を更新"ボタンを使うこともできます。

<?php submit_button(); ?>
</form>
</div>

submit_button 関数でボタンを作成することができます。

テキストを翻訳対応にするためには、_e()関数を使うようにしてください。詳しくは WordPress の翻訳を参照してください。

Register Settings

register_setting 関数と unregister_setting 関数は、フォームが保存できるオプションのホワイトリストにオプションを追加/削除します。セキュリティのために、各オプションの値をチェックするコールバック関数を指定できます。

register_setting 関数は admin_init アクションフックで呼び出されるべきです。このフックは他の管理ページよりも先に呼び出され、このフォームを受け取る options.php よりも先に呼び出されます。

あなたのプラグインには、新しいメニューを追加する add_action セクションがあるかもしれません。This line will be in the same section to add an action to admin_init.

if ( is_admin() ){ // admin actions
  add_action( 'admin_menu', 'add_mymenu' );
  add_action( 'admin_init', 'register_mysettings' );
} else {
  // non-admin enqueues, actions, and filters
}

それから各オプションを登録する関数を作成します。

function register_mysettings() { // whitelist options
  register_setting( 'myoption-group', 'new_option_name' );
  register_setting( 'myoption-group', 'some_other_option' );
  register_setting( 'myoption-group', 'option_etc' );
}

myoption-group の名前はなんでも良いですが、上述の settings_fields 関数で使用する名前と同じにしてください。

すべてを纏める

注意: 例のいくつかは(とくに do_settings は) 古い書き方かもしれません。 View Otto's tutorial here for better examples of workable code. ほかにも ozh による article があります。

オプションページにアイコンを追加するには以下のコード [3.4.2 以降で使用可能] を用いてください。アイコンはテーマフォルダの "images" フォルダ内にあります。

<?php add_menu_page('BAW Plugin Settings', 'BAW Settings', 'administrator', __FILE__, 'baw_settings_page', get_stylesheet_directory_uri('stylesheet_directory')."/images/media-button-other.gif"); ?>

Settings API を使用してプラグインのオプションを作成/保存する例です。

<?php
// create custom plugin settings menu
add_action('admin_menu', 'baw_create_menu');

function baw_create_menu() {

	//create new top-level menu
	add_menu_page('BAW Plugin Settings', 'BAW Settings', 'administrator', __FILE__, 'baw_settings_page',plugins_url('/images/icon.png', __FILE__));

	//call register settings function
	add_action( 'admin_init', 'register_mysettings' );
}


function register_mysettings() {
	//register our settings
	register_setting( 'baw-settings-group', 'new_option_name' );
	register_setting( 'baw-settings-group', 'some_other_option' );
	register_setting( 'baw-settings-group', 'option_etc' );
}

function baw_settings_page() {
?>
<div class="wrap">
<h2>Your Plugin Name</h2>

<form method="post" action="options.php">
    <?php settings_fields( 'baw-settings-group' ); ?>
    <?php do_settings_sections( 'baw-settings-group' ); ?>
    <table class="form-table">
        <tr valign="top">
        <th scope="row">New Option Name</th>
        <td><input type="text" name="new_option_name" value="<?php echo esc_attr( get_option('new_option_name') ); ?>" /></td>
        </tr>
         
        <tr valign="top">
        <th scope="row">Some Other Option</th>
        <td><input type="text" name="some_other_option" value="<?php echo esc_attr( get_option('some_other_option') ); ?>" /></td>
        </tr>
        
        <tr valign="top">
        <th scope="row">Options, Etc.</th>
        <td><input type="text" name="option_etc" value="<?php echo esc_attr( get_option('option_etc') ); ?>" /></td>
        </tr>
    </table>
    
    <?php submit_button(); ?>

</form>
</div>
<?php } ?>

例 #2

この例は WP 3.5.1 で動作します。より簡単なコードです。 Otto's tutorial を新しくしたものです。

<?php
class MySettingsPage
{
    /**
     * Holds the values to be used in the fields callbacks
     */
    private $options;

    /**
     * Start up
     */
    public function __construct()
    {
        add_action( 'admin_menu', array( $this, 'add_plugin_page' ) );
        add_action( 'admin_init', array( $this, 'page_init' ) );
    }

    /**
     * Add options page
     */
    public function add_plugin_page()
    {
        // This page will be under "Settings"
        add_options_page(
            'Settings Admin', 
            'My Settings', 
            'manage_options', 
            'my-setting-admin', 
            array( $this, 'create_admin_page' )
        );
    }

    /**
     * Options page callback
     */
    public function create_admin_page()
    {
        // Set class property
        $this->options = get_option( 'my_option_name' );
        ?>
        <div class="wrap">
            <?php screen_icon(); ?>
            <h2>My Settings</h2>           
            <form method="post" action="options.php">
            <?php
                // This prints out all hidden setting fields
                settings_fields( 'my_option_group' );   
                do_settings_sections( 'my-setting-admin' );
                submit_button(); 
            ?>
            </form>
        </div>
        <?php
    }

    /**
     * Register and add settings
     */
    public function page_init()
    {        
        register_setting(
            'my_option_group', // Option group
            'my_option_name', // Option name
            array( $this, 'sanitize' ) // Sanitize
        );

        add_settings_section(
            'setting_section_id', // ID
            'My Custom Settings', // Title
            array( $this, 'print_section_info' ), // Callback
            'my-setting-admin' // Page
        );  

        add_settings_field(
            'id_number', // ID
            'ID Number', // Title 
            array( $this, 'id_number_callback' ), // Callback
            'my-setting-admin', // Page
            'setting_section_id' // Section           
        );      

        add_settings_field(
            'title', 
            'Title', 
            array( $this, 'title_callback' ), 
            'my-setting-admin', 
            'setting_section_id'
        );      
    }

    /**
     * Sanitize each setting field as needed
     *
     * @param array $input Contains all settings fields as array keys
     */
    public function sanitize( $input )
    {
        $new_input = array();
        if( isset( $input['id_number'] ) )
            $new_input['id_number'] = absint( $input['id_number'] );

        if( isset( $input['title'] ) )
            $new_input['title'] = sanitize_text_field( $input['title'] );

        return $new_input;
    }

    /** 
     * Print the Section text
     */
    public function print_section_info()
    {
        print 'Enter your settings below:';
    }

    /** 
     * Get the settings option array and print one of its values
     */
    public function id_number_callback()
    {
        printf(
            '<input type="text" id="id_number" name="my_option_name[id_number]" value="%s" />',
            isset( $this->options['id_number'] ) ? esc_attr( $this->options['id_number']) : ''
        );
    }

    /** 
     * Get the settings option array and print one of its values
     */
    public function title_callback()
    {
        printf(
            '<input type="text" id="title" name="my_option_name[title]" value="%s" />',
            isset( $this->options['title'] ) ? esc_attr( $this->options['title']) : ''
        );
    }
}

if( is_admin() )
    $my_settings_page = new MySettingsPage();

以下のようなページを作成します。

creating-options-pages-ex-2b.png

落とし穴

register_setting() 関数の第二引数の「設定」名は、データベースで更新されるオプション名と同じでなけれななりません。
たとえば add_option( 'foo_bar', 'isfoo' ) を使う場合、register_setting() 関数の第二引数はfoo_bar でなければなりません。そうしないと、WordPress はどのオプションを更新してよいのか分からなくなります。

To show the menu in Multisite screen, it would be a matter of doing:
add_action( is_multisite() ? 'network_admin_menu' : 'admin_menu', 'callback_function' );
But the form save action leads to a 404 page: /wp-admin/network/options.php.
To solve it, use the solution in this WordPress Answers post, or alternatively the one in this blog post.

最新英語版: WordPress Codex » Creating_Options_Pages最新版との差分