Add New Buttons Alongside “Screen Options” And “Help”

Continuing from yesterday’s post about adding custom settings to the “Screen Options” panel in WP, I will now show you how to add your own buttons alongside “Screen Options” and “Help”.

But first, here are a few screenshots – to whet your appetite, so to speak.



Want those neat buttons in your plugin? Read on.

Hackety-Hack

The area that holds the “Screen Options” and “Help” links is internally known as “screen meta links”. There is no official API for adding new links to this area. Fortunately, the DOM structure that represents the buttons is relatively simple, so we can attach an extra button with just a few lines of JavaScript.

<script type="text/javascript">
(function($){
	$('#screen-meta-links').append(
		'<div id="my-screen-meta-link-wrap" class="hide-if-no-js screen-meta-toggle">' +
			'<a href="http://example.com/" id="my-screen-meta-link" class="show-settings">Foo</a>' +
		'</div>'
	);
})(jQuery);
</script>

You’ll also need to add some extra CSS to the page to make the new button show up correctly :

<style type="text/css">
#my-screen-meta-link-wrap {
	float: right;
	height: 22px;
	padding: 0;
	margin: 0 6px 0 0;
	font-family: "Lucida Grande", Verdana, Arial, "Bitstream Vera Sans", sans-serif;
	background: #e3e3e3;
	
	border-bottom-left-radius: 3px;
	border-bottom-right-radius: 3px;
	-moz-border-radius-bottomleft: 3px;
	-moz-border-radius-bottomright: 3px;
	-webkit-border-bottom-left-radius: 3px;
	-webkit-border-bottom-right-radius: 3px;
}

#my-screen-meta-link-wrap a.show-settings {
	background-image: none;
	padding:0 6px 0 6px;
}
</style>

These style will make your button look just like the default ones – light-grey background and dark-grey text. You can easily modify the CSS to change your button’s appearance. For example, the green “Upgrade” link pictured in one of the above screenshots has the equivalent of these extra styles applied :

#my-screen-meta-link-wrap {
	background-color: #00C31F; 
}
#my-screen-meta-link-wrap a.show-settings {
	font-weight: bold;
	color: #DEFFD8;
	text-shadow: none;
}
#my-screen-meta-link-wrap a.show-settings:hover {
	color: white;
}

No API? Make one.

Even such a simple hack can get cumbersome if you need to use it more than once or twice. After using it in several plugins, I went ahead and wrote a wrapper script that hides all the JS/CSS machinations behind a simple PHP interface. Here’s an example plugin that employs my custom API :

<?php
/*
Plugin Name: Screen Meta Links Demo
Plugin URI: http://w-shadow.com/
Description: Demonstrates how to add new links alongside the "Screen Options" and "Help" links on Dashboard pages.
Version: 1.0
Author: Janis Elsts
Author URI: http://w-shadow.com/blog/
*/

//Load the custom button API
include 'screen-meta-links.php';

//Simple example. Adds a screen meta link to example.com 
//to the main Dashboard page.
add_screen_meta_link(
	'meta-link-example2',  //Link ID. Should be unique.  
	'Example Link',        //Link text.
	'http://example.com/', //URL
	'index.php'            //Where to show the link. 
);

//Advanced example. Demonstrates how to add one link to 
//several different pages and how to set link attributes.
add_screen_meta_link(
	'meta-link-example2', 
	'Advanced Link', 
	'http://example.com/', 
	//An array of page/screen IDs specifying where to display the link. 
	array(
		'options-general.php', //Settings -> General	
		'post',                //The post editor
		'page',                //The page editor
	), 
	//Additional attributes for the link tag.
	array(
		'target' => '_blank',
		'title' => 'Open "http://example.com/" in a new window'
	)
);

?>

You can download a working example here. The screen-meta-links.php file is included in the archive. Feel free to use it in your own plugins.

Related posts :

13 Responses to “Add New Buttons Alongside “Screen Options” And “Help””

  1. Ethan says:

    Thank you for the code, it’s a real time saver. I love the colors!

    One question for you… how do I get the tab to display on a custom page, say a post or theme options page? I added the file name to the array but it is not showing…

    Again thank you for the script!

  2. White Shadow says:

    For theme options, use the return value of add_theme_page(). I’m not sure what setting would work for “posts” (do you mean the editor or the post listing?). Try “post” or “edit.php”.

  3. So cool! Thanks very much.

  4. andykamto says:

    I was looking for this search, thank you for the code,

  5. Great code mate thanks!

  6. It works great but I wanted to ask if you have any hint on how to include the “theme option page” as one of the pages to show this? I can include theme.php and it shows up under the theme page but not under the options page.

    Thanks mate

  7. White Shadow says:

    Basically, you need to find the “hook name” / “screen ID” of the page and use it instead of “theme.php”.

    If you are the author of the theme, you can get the hook name by calling the undocumented get_plugin_page_hookname() function after you’ve added the menu. Example :

    add_screen_meta_link(
    	'meta-link-example',  
    	'Example Link',        
    	'http://example.com/', 
    	get_plugin_page_hookname('your-menu-slug', 'themes.php')
    );
    

    Alternatively, you can try and figure out the hook name on your own. As far as I know, for a theme options page it will be something like “appearance_page_menu-slug”, where “menu-slug” is the value of the “page” parameter in the page’s URL.

  8. Robin says:

    Just what I was looking for. It there any way for me to turn the link “href” value into a “rel” value instead? I want to use it to open a jquery overlay.

    Thanks.

  9. Robin says:

    Don’t worry I fixed it. Sorry I was expecting it to be harder.

  10. Robin says:

    Ok, another question how would I add an onclick event to it? I need to add this code to an onclick..

    window.open(this.href, \’popupwindow\’, \’width=1030,height=650,scrollbars=yes\’); return false;

  11. Robin says:

    Sorry me again. Last one i swear. Does anyone know how would I make drop down tab like the help button?

  12. White Shadow says:

    I wouldn’t recommend using inline event handlers here. Instead, put the script elsewhere on your admin page and use jQuery to attach the on-click handler:

    jQuery('#my-button-id').click(function(){
        window.open(...);
    });
    

    I don’t think there is any documented way to add new drop down panels. Your best bet would be to reverse-engineer the default panel and copy whatever it does.

  13. math Games says:

    Right here is the perfect bblog for everyone who would like
    to find out abouut this topic. You understand
    a whole lot its almost hard to argue with you (not that I
    eally will need to‚ĶHaHa). You certainly put a brand new spin on a subject that’sbeen
    discussed for decades. Great stuff, just excellent!

Leave a Reply