On Monday, I explained how to add help tabs to your plugin administration pages. Today I’m going to explain how to add the screen options tab to those same pages. If you aren’t familiar with what the screen options tab looks like, here are some screen shots:
As you can see from the images above, WordPress uses this options panel to allow users to hide or show dashboard metaboxes. Don’t worry if you don’t need this functionality for your plugin, you can use the screen options tab for any type of plugin settings.
The first thing we need to do is create a function that will contain the screen option registration code. In this example, I’ve named this function ‘register_my_option’:
[php]
function register_my_option(){
}
[/php]
Now that I have a function to hold my code, I need to hook it into WordPress using the add_action() function. This page at WordPress.org lists all of the hooks available, in the order in which they are carried out. For registering screen options, we have to use a hook that happens after “current_screen”. I’ve decided to use ‘admin_head’.
[php]
function register_my_option(){
}
add_action(‘admin_head’, ‘register_my_option’);
[/php]
This function will allow us to register our screen options panel. However, unlike when registering help tabs, we have to do a little bit of extra work to add our own HTML to the screen options panel. To do this, we have to use the WordPress “add_filter()” function. When we call add_filter() the first value required is what we want to filter; in this case we use ‘screen_layout_columns’. The second option required by add_filter() is the name of a function which will be called to modify what is shown by ‘screen_layout_columns’. In the example below, we call the function named ‘display_my_option’ which will output the HTML we want to appear in the screen options panel.
[php]
function register_my_option(){
$screen = get_current_screen(); //Initiate the $screen variable.
add_filter(‘screen_layout_columns’, ‘display_my_option’); //Add our custom HTML to the screen options panel.
$screen->add_option(‘my_option’, ”); //Register our new screen options tab.
}
add_action(‘admin_head’, ‘register_my_option’);
[/php]
Now that we have added our filter and screen option tab, we need to create the HTML for the options panel. Since we named the display function: ‘display_my_option’ above, we’ll be sure to use that same for our function.
[php]
function display_my_option(){
?>
<form name=”my_option_form” method=”post”>
<input type=”hidden” name=”my_option_submit” value=”1″>
Your Name: <input type=”text” name=”text_name”><br/>
Your Email: <input type=”text” name=”text_email”><br/>
<input type=”submit” value=”Submit”>
</form>
<?php
}
[/php]
So far we’ve registered our screen options tab and created a very simple HTML form for the option panel. Now we need to process the values we get from the form when the user clicks on the “Submit” button. To do this, we’ll create a function to do our saving and then hook it into the WordPress page load by using the add_action() function.
[php]
function save_my_option(){
//Since we’re going to be hooking this into WordPress’s page load, the first thing we need to do is make sure our form has been submitted.
//The easiest way to do this is to check for the “hidden” value that we added to the beginning of our HTML form.
if(isset($_POST[‘my_option_submit’]) AND $_POST[‘my_option_submit’] == 1){
//We’d do our saving or processing here.
}
}
add_action(‘admin_init’, ‘save_my_option’);
[/php]
Finally, let’s throw all of that together:
[php]
function register_my_option(){
$screen = get_current_screen(); //Initiate the $screen variable.
add_filter(‘screen_layout_columns’, ‘display_my_option’); //Add our custom HTML to the screen options panel.
$screen->add_option(‘my_option’, ”); //Register our new screen options tab.
}
add_action(‘admin_head’, ‘register_my_option’);
function display_my_option(){
?>
<form name=”my_option_form” method=”post”>
<input type=”hidden” name=”my_option_submit” value=”1″>
Your Name: <input type=”text” name=”text_name”><br/>
Your Email: <input type=”text” name=”text_email”><br/>
<input type=”submit” value=”Submit”>
</form>
<?php
}
function save_my_option(){
//Since we’re going to be hooking this into WordPress’s page load, the first thing we need to do is make sure our form has been submitted.
//The easiest way to do this is to check for the “hidden” value that we added to the beginning of our HTML form.
if(isset($_POST[‘my_option_submit’]) AND $_POST[‘my_option_submit’] == 1){
//We’d do our saving or processing here.
}
}
add_action(‘admin_init’, ‘save_my_option’);
[/php]
And, that’s all there is to it! If it works out right, your screen tab should look like this:
Please note that it’s best practice to always include a security field, like a nonce (number used once), whenever processing data gathered from your users. We haven’t included that in this tutorial, but we’ll cover how to do that on Friday.
Nirjhar Lo says
A thanks comment is the least one can do for this very useful guide. It helped my live plugin development.
Tough one must mention that, it is ‘wp_loaded’ hook is more useful rather than ‘admin_init’, to apply results in WordPress admin menu immediately.
Thank you.