Create Plugin Options Page Easily: without dealing with WordPress Settings API.

While getting inspiration from the WordPress Plugin Developers talent pool, I believe the following post can help create a custom plugin settings page easily.

Using the techniques discussed in this post, this is what we are going to create:

TLDR;

Download the sample plugin, install it to see it in action or simply explore the code. Pass a config array to the helper class constructor and Boom! your plugin options page with auto-sanitized input is ready to rock.

Why should i use it?

Create plugin options page without the pain of dealing with Settings API
One config array to create everything: admin menu, settings page, sections, fields.
Fields input is auto sanitized
Can be used to make Tabs or Tab-less Settings page
Can be used to add plugin action links
Ability to override sanitization callback
Ability to override fields display callback

How to use?

Complete Details can be found in the Wiki, in the nutshell, follow the steps:

copy the class in plugin vendor folder and require the class in your plugin files (add dependency)
hook into admin_menu and provide a callback function
in the callback function, pass the config array to this helper class object to build your sections and fields.

Its that easy. Here is a simple example code that will create a plugin menu, 2 sections and some fields under these sections.

Available Field Types:

Following Field Types can be added using this Helper Class:

text
url
number
color
textarea
radio
select
checkbox
multicheck
media
file
posts (WP posts and Custom Post Types)
pages (WP pages)
password
html

Lets Create Options Settings Page: Step-by-Step

Create admin_menu hook:

function plugin_menu_using_boo_setting_helper_simple() {
	// Our Code goes here

}

add_action( 'admin_menu', 'plugin_menu_using_boo_setting_helper_simple' );

Require helper class

Next step is to require our helper class.

function plugin_menu_using_boo_setting_helper_simple() {
	// Require Settings Helper Class
	require_once 'vendor/boospot/boo-settings-helper/class-boo-settings-helper.php';

}

Configuration Array

configuration array is the main array that shall be passed to the helper class. Complete configuration details can be found on Settings Configuration Array Wiki Page. It mainly has following 6 components.

$config_array = array(
	'prefix'   => 'plugin_prefix_',   // string to prefix with options id (optional)
	'tabs'     => true,     // true | false  (optional)  ( Default: true )
	'menu'     => array(),  // array of menu configuration
	'sections' => array(),  // array of arrays configuring sections
	'fields'   => array(),  // array of arrays configuring fields. array key same as sections  
	'links'    => array()   // configuration array for links (optional)
);

Lets start building these components

Prefix options ids

We should always prefix anything that goes in global namespace, so we can define our prefix once and it shall be added to all fields automatically

function plugin_menu_using_boo_setting_helper_simple() {
	// Require Settings Helper Class
	require_once 'vendor/boospot/boo-settings-helper/class-boo-settings-helper.php';
	// Create Config Array
	$config_array             = array();
	$config_array['prefix']   = 'plugin_prefix_';

}

Plugin Menu

We can create plugin menu using the menu array property. Complete configuration options for different fields can be found on Menu Configuration Wiki Page.

function plugin_menu_using_boo_setting_helper_simple() {
	// ...
	// ...
	$config_array             = array();
	$config_array['prefix']   = 'plugin_prefix_';
	$config_array['menu']     = array(
		'page_title' => __( 'Plugin Name Settings', 'plugin-name' ),
		'menu_title' => __( 'Plugin Name', 'plugin-name' ),
		'capability' => 'manage_options',
		'slug'       => 'plugin-name',
		'icon'       => 'dashicons-performance',
	);

}

Section for Options pages

Lets create some sections to group our options. The following will create two sections, general and advance. Notice the id for sections. This shall be used to assign fields to specific sections later-on.

function plugin_menu_using_boo_setting_helper_simple() {
	// ...
	// ...
	$config_array['sections'] = array(
		array(
			'id'    => 'general_section',
			'title' => __( 'General Settings', 'plugin-name' ),
			'desc'  => __( 'These are general settings for Plugin Name', 'plugin-name' ),
		),
		array(
			'id'    => 'advance_section',
			'title' => __( 'Advanced Settings', 'plugin-name' ),
			'desc'  => __( 'These are advance settings for Plugin Name', 'plugin-name' )
		)
	);
}

Configure Fields for sections

The following configuration shall create two fields, one for each section. Complete configuration options for different fields can be found on Fields Configuration Wiki Page. Array key defines the section_id where the field is to displayed

function plugin_menu_using_boo_setting_helper_simple() {
	// ...
	// ...
	$config_array['fields']   = array(
		'general_section' => array(
			array(
				'id'                => 'text_field_id_1',
				'label'             => __( 'First Text', 'plugin-name' ),
				'desc'              => __( 'Simple Description', 'plugin-name' ),
				'placeholder'       => __( 'Text Input placeholder', 'plugin-name' ),
				'type'              => 'text',
			)
		),
		'advance_section' => array(
			array(
				'id'                => 'text_field_id_2',
				'label'             => __( 'Another Text Field', 'plugin-name' ),
				'placeholder'       => __( 'Text Input placeholder', 'plugin-name' ),
				'type'              => 'text',
			)
		)
	);
}

Pass $config_array to helper class

Now, we can pass this config array to helper class. and Voila , Your settings page is ready to rock.

function plugin_menu_using_boo_setting_helper_simple() {
	// Require Settings Helper Class
	require_once 'vendor/boospot/boo-settings-helper/class-boo-settings-helper.php';
	// Create Config Array
	$config_array             = array();

	// ...
	// ...
	// ...

	// Pass Config Array to Class Constructor
	$settings_helper = new Boo_Settings_Helper( $config_array );
}

Create Plugin Links ( Bonus! )

You may also create plugin action links by passing the array param link. Details of link config is on the Wiki Page.

function plugin_menu_using_boo_setting_helper_simple() {
	$config_array             = array();
	// ...
	// ...
	// ...
	$config_array['links']    = array(
		'plugin_basename' => plugin_basename( __FILE__ ),
		'action_links'    => array(
			array(
				'type' => 'default',
				'text' => __( 'Configure', 'plugin-name' ),
			),
			array(
				'type' => 'internal',
				'text' => __( 'Gravity Forms', 'plugin-name' ),
				'url'  => 'admin.php?page=gf_edit_forms',
			),
			array(
				'type' => 'external',
				'text' => __( 'Github Repo', 'plugin-name' ),
				'url'  => 'https://github.com/boospot/boo-settings-helper',
			),
		),
	);

	// Pass Config Array to Class Constructor
	$settings_helper = new Boo_Settings_Helper( $config_array );
}

Full Code to create all field types

You may check the Detailed Example to create the settings page with all field types.

Final Thoughts

Using this class has helped me a lot while creating custom plugins for my own sites and clients. For me the benefit of not having to deal with official Settings API is a huge plus 🙂