Codex

Function Reference/register setting

Contents

Description

Register a setting and its sanitization callback.

This is part of the Settings API, which lets you automatically generate wp-admin settings pages by registering your settings and using a few callbacks to control the output.

This function can also be used to register settings that will be shown on the default WP settings pages like media or general. Once the setting is registered you can add it to an existing section with add_settings_field() or create a new section with add_settings_section() and add it to that.

Usage

 <?php register_setting( $option_group, $option_name, $sanitize_callback ); ?> 

Parameters

$option_group
(string) (required) A settings group name. Must exist prior to the register_setting call. This must match the group name in settings_fields()
Default: None
$option_name
(string) (required) The name of an option to sanitize and save.
Default: None
$sanitize_callback
(string) (optional) A callback function that sanitizes the option's value.
Default: None

Return Values

(void) 
This function does not return a value.

Example 

function register_my_setting() {
	register_setting( 'my_options_group', 'my_option_name', 'intval' ); 
} 
add_action( 'admin_init', 'register_my_setting' );

Notes

  • It seems the data is passed trough the sanitize function twice. For example this will give you a string with two exclamation marks: function append_exclamation ($input) { return $input.'!'; }
  • The "Error: options page not found." problem (including a solution and explanation):

The problem then is, that the 'whitelist_options' filter hasn't got the right index for your data. It gets applied on options.php#98 (WP 3.4).

register_settings() adds your data to the global $new_whitelist_options. This then gets merged with the global $whitelist_options inside the option_update_filter() (resp. add_option_whitelist()) callback(s). Those callbacks add your data to the global $new_whitelist_options with the $option_group as index. When you encounter "Error: options page not found." it means your index hasn't been recognized. The misleading thing is that the first argument is used as index and named $options_group, when the actual check in options.php#112 happens against $options_page, which is the $hook_suffix, which you get as @return value from add_submenu_page().

In short, an easy solution is to make $option_group match $option_name.

Change Log

Since: 2.7.0

Source File

register_setting() is located in wp-admin/includes/plugin.php.

Resources

Related

Settings API: register_setting(), unregister_setting(), add_settings_field(), add_settings_section(), add_settings_error(), get_settings_errors(), settings_errors()

See also index of Function Reference and index of Template Tags.
Retrieved from "http://codex.wordpress.org/Function_Reference/register_setting"

Codex Resources