Introduction

This is the second in our series of articles on constructing plugins/extensions specifically for Simple:Press. If you need a refresher you can find the first article here: Hello World!

In this article we will take a look at how you can add settings to the Simple:Forum admin area that your plugins can use.

Almost all plugins need to be able to create settings that users can toggle to control the behavior of plugins. Simple:Press has a robust infrastructure for creating, displaying and accessing settings. So lets go ahead and take a look at how that is all put together!

General Process Overview

To create or update settings you need to hook into WordPress action hooks as well as Simple:Press action hooks. Below show the three core hooks that are used.

add_action('init', 'sp_settings_localization');  # allow strings to be translated

add_action('sph_options_global_right_panel', 'sp_settings_admin_options'); # hook into the forum - global settings panel display in order to add our stuff

add_action('sph_option_global_save', 'sp_settings_admin_save_options'); # hook into saving of the forum - global settings so we can save our stuff

The first hook is your classic WordPress 'init' hook and is used to add some translation strings specific to this plugin.  It creates a locale for the plugin so any strings we add on the admin form can be translated.

The second hook is fired by SP when it finishes rendering
the right hand side of the Global Settings form so that plugins can add
anything else to the form.  There is a
corresponding left half hook, but we have chosen to add the setting to the
right side – an arbitrary decision.

The third hook is fired by SP when the user clicks on the Update Global Options button to save the settings on the form.  SP will save its settings, then fire this hook so plugins can add any sanitization, validating and saving of the settings it added to the form.

As you might expect, each of the three hooks has a corresponding callback function that will get called when the hook is fired. This is where we will put our code for rendering our options and saving our options.

Callback For The Translation Hook

# plugin function for hooking in for translating our strings
function sp_settings_localization() {
	sp_plugin_localisation('sp-settings');
}

Callback For Adding Settings Fields

# lets add our new settings to the existing setting admin panel
function sp_settings_admin_options() {
	$settings = SP()->options->get('settings');

	spa_paint_open_panel();
		spa_paint_open_fieldset(__('New Settings', 'sp-settings'), false);
		spa_paint_input(__('Some integer number setting', 'sp-settings'), 'settingsnum', $settings['settingsnum']);
		spa_paint_checkbox(__('Another enabled or disabled option', 'sp-settings'), 'settingsflag', $settings['settingsflag']);
		spa_paint_close_fieldset();
	spa_paint_close_panel();
}

There are a few important things to note with the above code. First, that we are obtaining the array of existing settings using the call to sp()->options->get and storing that array in the $settings variable.

Second, we have some Simple:Press primitives that control displaying the settings fields on the screen including container and tab primitives. These all start with spa_paint_. You can find the full set in the simple-pressadminlibraryspa-tab-support.php file.

Notice that there are matching open_panel and closing_panel statements as well as matching open_fieldset and close_field set statements. These all wrap around the actual field definitions. Internally these are simply outputting divs with special class and styles.

Finally, you'll notice that each spa_paint_ statement that actually paints a setting field is taking a value from the $settings array. This is the default value that will be displayed. For brand new fields, this value is likely to be blank until the first time settings are saved on your new screen.

Callback For Saving Settings

# when the settings panel is saved, we have to save our new settings
function sp_settings_admin_save_options() {
	check_admin_referer('forum-adminform_global', 'forum-adminform_global');

	$settings = SP()->options->get('settings');
	$settings['settingsnum'] = SP()->filters->integer($_POST['settingsnum']); # make sure its an integer
    $settings['settingsflag'] = isset($_POST['settingsflag']); # only boolean
	SP()->options->update('settings', $settings);
}

The first line of this call-back verifies that the screen being processed is indeed our settings form. After that, we retrieve the existing settings array and assign it to the $settings variable.

From there, we read the data from the $_POST variables, making sure to sanitize each value before saving to our database with an SP()->options-update function call.

Wrapup

Now you know how to create and set options on our Simple:Press screen. And you can retrieve / read the options using the SP()->OPTIONS function calls.

In our next article we will cover the creation of full component setting screens. These are the settings you find under FORUM->COMPONENTS and are generally more expansive than just one or two items.