WordPress.org

Создание страниц настройки

Languages: English • 日本語 • Русский • (Add your language)

Contents 1 Введение 2 Opening the Page 3 Тег формы 4 Магия nonce 5 Form Table 6 Поле action 7 Поле page_options 8 Закрываем теги 9 See It All Together 10 Wordpress 2.7 and Newer 10.1 settings_fields Function 10.2 Register Settings 10.3 See It All Together 10.3.1 Pitfalls

Введение

Создавать собственные панели настроек в WordPress относительно легко.

Для начала, чтобы создать элемент меню и новую страницу, посмотрите статью «Добавление административных меню».

Если придерживаться этой структуры, 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.

Opening the Page

You can either put the code for your options page in your plugin php file, or you can create a second file called options.php, for example, and include it using the php include function - http://www.w3schools.com/PHP/php_includes.asp

If you'd like to match the look and feel of existing WordPress options pages, open with the following:

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

Тег формы

Когда у вас появилась страница, нужно создать HTML-форму. Используйте этот код:

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

Магия nonce

После открытия тега формы вставьте следующий PHP-код:

<?php wp_nonce_field('update-options'); ?>

Он добавит два скрытых поля, позволяющих автоматически проверять, что пользователь может обновлять настройки, и перенаправлять его обратно на нужную страницу (поскольку форма отсылает результат на другую страницу).

(This is not needed if the version 2.7 function settings_fields is used.)

Form Table

Most options pages use a table with the class "form-table" to display their options. To match the look and feel of these pages, create a new table:

<table class="form-table">

Используйте поля с теми же названиями, какие вы хотите дать создаваемым настройкам (которые будут храниться в таблице options), например:

<tr valign="top">
<th scope="row">New Option Name</th>
<td><input type="text" name="new_option_name" value="<?php echo get_option('new_option_name'); ?>" /></td>
</tr>

A closer look at the <input> element:

<input type="text" name="new_option_name" value="<?php echo get_option('new_option_name'); ?>" />

Обратите внимание, что благодаря использованию функции get_option() в качестве значения поля, оно автоматически обновится, когда настройки будут сохранены.

Once you have added all your options rows, close the table:

</table>

Поле action

Теперь создайте скрытое поле под названием «action» со значением «update».

<input type="hidden" name="action" value="update" />

(This is not needed if the version 2.7 function settings_fields is used.)

Поле page_options

В заключение, создайте скрытое поле под названием «page_options», содержащее разделённый запятыми список всех настроек, которые нужно записать при сохранении.

<input type="hidden" name="page_options" value="new_option_name,some_other_option,option_etc" />

(This is not needed if the version 2.7 functions settings_fields and register_setting are used.)

Закрываем теги

Затем, очевидно, следует закрыть тег формы. Если хотите, можно добавить ещё одну кнопку «Обновить настройки» — в WordPress так принято.

<p class="submit">
<input type="submit" class="button-primary" value="<?php _e('Save Changes') ?>" />
</p>
</form>
</div>

Обратите внимание на использование функции _e() для перевода текста. Подробности — в статье «Локализация WordPress».

See It All Together

<div class="wrap">
<h2>Your Plugin Name</h2>

<form method="post" action="options.php">
<?php wp_nonce_field('update-options'); ?>

<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 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 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 get_option('option_etc'); ?>" /></td>
</tr>

</table>

<input type="hidden" name="action" value="update" />
<input type="hidden" name="page_options" value="new_option_name,some_other_option,option_etc" />

<p class="submit">
<input type="submit" class="button-primary" value="<?php _e('Save Changes') ?>" />
</p>

</form>
</div>

Wordpress 2.7 and Newer

Here is the new API functions to be used 3.0.

This function will create the options page.

Add sub menu page to the options main menu. This function takes a capability which will be used to determine whether or not a page is included in the menu. The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

page_title

The text to be displayed in the title tags of the page when the menu is selected

menu_title

The text to be used for the menu

capability

The capability required for this menu to be displayed to the user.

menu_slug

The slug name to refer to this menu by (should be unique for this menu)

function

The function to be called to output the content for this page.

settings_fields Function

The setting fields will know which settings your options page will handle.

Somewhere within the form add this function

settings_fields( 'myoption-group' );

where myoption-group is the same name used in the register_setting function.

This function replaces the nonce magic, action field, and page_options field mentioned above.

Register Settings

The register_setting and 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.

The register_setting function should be called in an admin_init action, which runs before every admin page and in particular, options.php, which receives this form.

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.

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

Then you create a new function that registers each option.

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' );
}

The name of myoption-group doesn't matter but it has to match the name used in the settings_fields function above.

See It All Together

The below example uses the new Settings API to create and save your plugin options

<?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' ); ?>
    <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 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 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 get_option('option_etc'); ?>" /></td>
        </tr>
    </table>
    
    <p class="submit">
    <input type="submit" class="button-primary" value="<?php _e('Save Changes') ?>" />
    </p>

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

Pitfalls

The Settings name, the second parameter in the register_setting() function, MUST match the name of the option being updated in the database!
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.

• Home Page
• WordPress Lessons
• Getting Started
• Working with WordPress
• Design and Layout
• Advanced Topics
• Troubleshooting
• Developer Docs
• About WordPress

Codex Resources

• Community portal
• Current events
• Recent changes
• Random page
• Help