W-Shadow.com

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.