How to create a plugin options/settings page in wordpress

Categories: WordPress, WordPress Plugins, WP Plugins Tutorials - Tags: , ,
How to create a plugin options/settings page in wordpress 3.75/5 12 votes

Today you guys will learn how to create a wordpress plugin options or settings page. After having a good idea how this is done, you will easily be able to add an options page for your favourite plugins.

We will be following a simple plugin to demonstrate this tutorial.

Lets get started…

Assumptions

I assume that you have an idea on how a wordpress plugin can be created. If you are new to wordpress plugins, you can follow this post: Creating WordPress Plugins the great way.

Lets start

For demonstration purpose of the options page, we will create a single field option containing your favourite quote and append it to the post content.

1. Plugin signature and structure

Create a folder in your wp-content->plugins directory and name it ‘kk-plugin-options’.

In this new folder, create a new php file and name it ‘index.php’.

<?php

/*
    Plugin Name: kk Plugin Options Demonstration
    Plugin URI: http://wakeusup.com
    Description: Understanding WordPress Plugin Options/Settings.
    Version: 0.1
    Author: Kamal Khan
    Author URI: http://wakeusup.com
*/
?>

2. Check vs other plugins

We proceed if and only if the class name does not exist i.e. it has not already been taken by any other plugin etc.

<?php

/*
    Plugin Name: kk Plugin Options Demonstration
    Plugin URI: http://wakeusup.com
    Description: Understanding WordPress Plugin Options/Settings.
    Version: 0.1
    Author: Kamal Khan
    Author URI: http://wakeusup.com
*/
if(!class_exists('kkPluginOptions')) :
// DEFINE PLUGIN ID
define('KKPLUGINOPTIONS_ID', 'kk-plugin-options');
// DEFINE PLUGIN NICK
define('KKPLUGINOPTIONS_NICK', 'kk Plugin Options');
endif;
?>

So, we have defined 2 globals, one contains the plugin id and the other contains the plugin nick.

3. The Class

The following is the class we need

<?php

/*
    Plugin Name: kk Plugin Options Demonstration
    Plugin URI: http://wakeusup.com
    Description: Understanding WordPress Plugin Options/Settings.
    Version: 0.1
    Author: Kamal Khan
    Author URI: http://wakeusup.com
*/
if(!class_exists('kkPluginOptions')) :
// DEFINE PLUGIN ID
define('KKPLUGINOPTIONS_ID', 'kk-plugin-options');
// DEFINE PLUGIN NICK
define('KKPLUGINOPTIONS_NICK', 'kk Plugin Options');
    class kkPluginOptions
    {
		/** function/method
		* Usage: return absolute file path
		* Arg(1): string
		* Return: string
		*/
		public static function file_path($file)
		{
			return ABSPATH.'wp-content/plugins/'.str_replace(basename( __FILE__),"",plugin_basename(__FILE__)).$file;
		}
		/** function/method
		* Usage: hooking the plugin options/settings
		* Arg(0): null
		* Return: void
		*/
		public static function register()
		{
			register_setting(KKPLUGINOPTIONS_ID.'_options', 'kkpo_quote');
		}
		/** function/method
		* Usage: hooking (registering) the plugin menu
		* Arg(0): null
		* Return: void
		*/
		public static function menu()
		{
			// Create menu tab
			add_options_page(KKPLUGINOPTIONS_NICK.' Plugin Options', KKPLUGINOPTIONS_NICK, 'manage_options', KKPLUGINOPTIONS_ID.'_options', array('kkPluginOptions', 'options_page'));
		}
		/** function/method
		* Usage: show options/settings form page
		* Arg(0): null
		* Return: void
		*/
		public static function options_page()
		{
			if (!current_user_can('manage_options'))
			{
				wp_die( __('You do not have sufficient permissions to access this page.') );
			}

			$plugin_id = KKPLUGINOPTIONS_ID;
			// display options page
			include(self::file_path('options.php'));
		}
		/** function/method
		* Usage: filtering the content
		* Arg(1): string
		* Return: string
		*/
		public static function content_with_quote($content)
		{
			$quote = '<p><blockquote>' . get_option('kkpo_quote') . '</blockquote></p>';
			return $content . $quote;
		}
    }

endif;
?>

A lot of code? Nothing to worry about, let me explain:

file_path

Method:  string file_path(string)

What: Gets a file as string which is relative to this plugin directory and returns the absolute path.

Why: We will need to include the options.php file (file to be created yet). Hence we will send the relative path of the file and get the absolute path and will include the file which will contain the options form.

register

Method:  void register()

What: Responsible to register the setting field names we need.

Why: This method will be hooked to ‘admin_init’ which will register the setting fields we define inside.

menu

Method:  void menu()

What: Responsible to add an options menu tab.

Why: This method will be hooked to ‘admin_menu’ so that an options menu tab appears under the settings menu.

options_page

Method:  void options_page()

What: Responsible to display the options page with the form.

Why: This method is being hooked in the menu() method so that it can display the form. It also checks whether the user has permissions to change settings and then includes the options.php file.

content_with_quote

Method:  string content_with_quote(string)

What: This method modifies the content and returns it.

Why: We hook this method so that it can append a quote of users choice to the content.

4. Final index.php code (hooking it up)

At the end, we create the neccessary hooks

<?php

/*
    Plugin Name: kk Plugin Options Demonstration
    Plugin URI: http://wakeusup.com
    Description: Understanding WordPress Plugin Options/Settings.
    Version: 0.1
    Author: Kamal Khan
    Author URI: http://wakeusup.com
*/
if(!class_exists('kkPluginOptions')) :
// DEFINE PLUGIN ID
define('KKPLUGINOPTIONS_ID', 'kk-plugin-options');
// DEFINE PLUGIN NICK
define('KKPLUGINOPTIONS_NICK', 'kk Plugin Options');
    class kkPluginOptions
    {
		/** function/method
		* Usage: return absolute file path
		* Arg(1): string
		* Return: string
		*/
		public static function file_path($file)
		{
			return ABSPATH.'wp-content/plugins/'.str_replace(basename( __FILE__),"",plugin_basename(__FILE__)).$file;
		}
		/** function/method
		* Usage: hooking the plugin options/settings
		* Arg(0): null
		* Return: void
		*/
		public static function register()
		{
			register_setting(KKPLUGINOPTIONS_ID.'_options', 'kkpo_quote');
		}
		/** function/method
		* Usage: hooking (registering) the plugin menu
		* Arg(0): null
		* Return: void
		*/
		public static function menu()
		{
			// Create menu tab
			add_options_page(KKPLUGINOPTIONS_NICK.' Plugin Options', KKPLUGINOPTIONS_NICK, 'manage_options', KKPLUGINOPTIONS_ID.'_options', array('kkPluginOptions', 'options_page'));
		}
		/** function/method
		* Usage: show options/settings form page
		* Arg(0): null
		* Return: void
		*/
		public static function options_page()
		{
			if (!current_user_can('manage_options'))
			{
				wp_die( __('You do not have sufficient permissions to access this page.') );
			}

			$plugin_id = KKPLUGINOPTIONS_ID;
			// display options page
			include(self::file_path('options.php'));
		}
		/** function/method
		* Usage: filtering the content
		* Arg(1): string
		* Return: string
		*/
		public static function content_with_quote($content)
		{
			$quote = '<p><blockquote>' . get_option('kkpo_quote') . '</blockquote></p>';
			return $content . $quote;
		}
    }
    if ( is_admin() )
	{
		add_action('admin_init', array('kkPluginOptions', 'register'));
		add_action('admin_menu', array('kkPluginOptions', 'menu'));
	}
	add_filter('the_content', array('kkPluginOptions', 'content_with_quote'));

endif;
?>

4. The options.php file

The last thing is to create the options.php file. Create this file in the same directory and write the following code:

<div class="wrap">

    <?php screen_icon(); ?>

	<form action="options.php" method="post" id="<?php echo $plugin_id; ?>_options_form" name="<?php echo $plugin_id; ?>_options_form">

	<?php settings_fields($plugin_id.'_options'); ?>

    <h2>kk Plugin Options &raquo; Settings</h2>
    <table class="widefat">
		<thead>
		   <tr>
			 <th><input type="submit" name="submit" value="Save Settings" class="button-primary" style="padding:8px;" /></th>
		   </tr>
		</thead>
		<tfoot>
		   <tr>
			 <th><input type="submit" name="submit" value="Save Settings" class="button-primary" style="padding:8px;" /></th>
		   </tr>
		</tfoot>
		<tbody>
		   <tr>
			 <td style="padding:25px;font-family:Verdana, Geneva, sans-serif;color:#666;">
                 <label for="kkpo_quote">
                     <p>Your favourite quote?</p>
                     <p><input type="text" name="kkpo_quote" value="<?php echo get_option('kkpo_quote'); ?>" /></p>
                 </label>
             </td>
		   </tr>
		</tbody>
	</table>

	</form>

</div>

Still Confused? Download the plugin

kk-plugin-options.zip

5 Responses to How to create a plugin options/settings page in wordpress

  1. Reply Greg says:

    Found this helpful, but also – what about sanitation and validation?

    This method doesn’t look like it stores the option in an array. I also see you’re not using add_settings_section or
    add_settings_field, can you touch on that at all?

    Cheers

  2. Reply Josh says:

    I got the back-end working, but how do I display the quote on the front-end?

    Thanks,
    Josh

  3. Reply Pablo says:

    This is awesome!! Thanks for making the plugin example available for download.

  4. Reply Pablo says:

    What does “the plugin nick” mean?

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

© 2014 Copyright - wakeusup