Using Settings Hooks - roberts-sandbox/create-repo GitHub Wiki

WordPress provides a structure for plugins to save, retrieve and modify their options. WordPress also provides means to easily bundle these options together and display interfaces for modifying them. WP-Librarian has its own classes built on top to handle common tasks. But first, as it confused me originally, an overview of how settings work in WordPress.

###Settings, fields and options (oh my!)

If you're wondering why settings and options keep being referred to differently depending on context, it's because they refer to different aspects of plugin configuration. Settings (and its associated terms) refer to the viewing and changing of settings by WordPress users via pages on the Admin Dashboard. Options refer to the fetching, deleting and updating of options by plugins. Settings provide the means for users to interact with options.

The Settings API wasn't always around, so you might see some older plugins using seemingly convoluted means for managing options.

Settings and options have their own selection of functions which are well documented on the WordPress Codex (see: Settings API & Options API), so I'll just skim over how everything works.

####Settings

Settings belong to settings sections, groups of related settings which you can easily display on an admin page. Settings sections handle the form submission and using your appropriate callback to sanitize the setting before updating the option. Settings sections are registered via add_settings_section(). You can add your section to an existing settings page by specifying that page's name as the $page parameter passed to add_settings_section().

####Settings Fields

Fields belong to settings, they are input fields that each setting should have at least one of. It is advised that you bundle related configuration options into arrays of options, as getting an option = a database query. Fields hold callbacks to render the user input fields.

####Options

Options are where settings are saved as $key/$value pairs. You can retrieve an option using get_option($key). All of yo ur plugin's state should be stored via options.

###Using WP-Librarian hooks

To handle settings registration via WP-Librarian, you first need to add your settings to WP-Librarian's list of settings using the wp_lib_plugin_settings hook:


add_filter('wp_lib_plugin_settings', 'add_my_settings');

function add_my_settings(Array $settings) {
	return array_merge($settings, array(
		'my_first_setting'	=> array('field-one-default', 20),
		'my_second_setting'	=> array(2, 'derp')
	));
}

WP-Librarian will now create these two options if they don't exist (after clicking update on the WP-Librarian settings page).

Now, assuming you're adding a new tab to WP-Librarian's settings page, you'll need to do exactly that:


add_filter('wp_lib_settings_tabs', 'add_my_settings_tab', 10, 1);

function add_my_settings_tab($settings_tabs) {
	$settings_tabs['my_tab'] = array('my_settings_section', 'My Tab');
	
	return $settings_tabs;
}

If you now visit WP-Librarian's settings page you'll see a new tab has appeared:

Notice the lack of content. That's because WP-Librarian is instructing WordPress to render the settings section my_settings_section, which currently doesn't exist. As such, lets register the settings section.

As we're using WP-Librarian's class WP_LIB_SETTINGS_SECTION we'll be registering the section, its settings and those settings' fields all at once.


add_action('wp_lib_register_settings', 'my_settings_section');

function my_settings_section() {
	WP_LIB_SETTINGS_SECTION::registerSection(array(
		'name'		=> 'my_settings_section',
		'title'		=> 'My Settings Section',
		'page'		=> 'my_settings_section-options',
		'settings'	=> array(
			array(
				'name'			=> 'my_first_setting',
				'sanitize'		=>
					function($raw) {
						// Use appropriate methods to sanitize your input
						return array(
							sanitize_title($raw[0]),
							min(max((int) abs(trim($raw[1])), 1), 100)
						);
					},
				'fields'		=> array(
					array(
						'name'			=> 'Setting 1 Field 1',
						'field_type'	=> 'textInput',
						'args'			=> array(
							'classes'	=> array('extra-class', 'another-class'),
							'alt'		=> 'An explanation of the settings field'
						)
					),
					array(
						'name'			=> 'Setting 1 Field 2',
						'field_type'	=> 'textInput',
						'args'			=> array(
							'alt'		=> 'An explanation of the settings field'
						)
					)
				)
			),
			array(
				'name'			=> 'my_second_setting',
				'sanitize'		=>
					function($raw) {
						return array(
							wp_lib_sanitize_option_checkbox($raw[0]),
							sanitize_title($raw[1])
						);
					},
				'classes'		=> array('second-settings-class'),
				'fields'		=> array(
					array(
						'name'			=> 'Setting 2 Field 1',
						'field_type'	=> 'checkboxInput',
						'args'			=> array(
							'alt'		=> 'An explanation of the settings field'
						)
					),
					array(
						'name'			=> 'Setting 2 Field 2',
						'field_type'	=> 'textInput',
						'args'			=> array(
							'alt'		=> 'An explanation of the settings field'
						)
					)
				)
			)
		)
	));
}

The code above creates a settings section called my_settings_section that will be displayed on any page that calls my_settings_section-options. The section has two settings, both of which have two fields, which will result in four fields being rendered in the section. By using the build in field types of WP_LIB_SETTINGS_SECTION you don't have to worry about writing your own HTML inputs. Some other points to note:

Class Inheritance: Classes defined at a settings level are added to all of its fields. So the two input fields of the second setting will both have the class second-settings-class.

Titles/Names: The section title will appear at the beginning of the section, the field names will appear to the left of their inputs.

Together, the above code generates this tab with its settings section:

If you got a 114 error (Option does not exist) that's because, as you might expect, these options don't exist yet. When this error occurs WP-Librarian checks the validity of all of its settings, which includes the ones you added earlier. When this happens your options will be created with their default values. As such you should only have to refresh the page and the fields will now display with the default values.

Note that you could have multiple settings sections displaying on one tab.

Using Settings Hooks - roberts-sandbox/create-repo GitHub Wiki

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️