WordPress Plugin Help Panels with WP_Screen – Features and Limits

by David • November 25, 2011 • Notes • 4 Comments

With version 3.3 (currently at beta 4), WordPress has introduced the WP_Screen API for adding rich help screens to your plugin’s admin page(s). This is still a very new API so, even though some options functions exist, you won’t be making crazy customizations or replacing meta boxes just yet.

Update: version 3.3 is current at RC 2 and, while there have been many internal improvements, the API still works as described below.

Creating an admin page and WP_Screen instance

Creating an admin page for your plugin hasn’t changed, but it’s more important than ever to save the handle of your admin page.

 
	/**
	 * Save the handle to your admin page - you'll need it to create a WP_Screen object
	 */
	$this->admin_page = add_options_page( 
		__('WP_Screen Test','my-plugin'), 
		__('WP_Screen Test','my-plugin'), 
		'manage_options', 
		'wp_screen_test', 
		array(&$this, 'test_page') 
	);
 
	/** Use this hook to catch your admin page's loading */
	add_action("load-{$this->admin_page}",array(&$this,'create_help_screen'));
 
public function create_help_screen() {
 
	/** 
	 * Create the WP_Screen object against your admin page handle
	 * This ensures we're working with the right admin page
	 */
	$this->admin_screen = WP_Screen::get($this->admin_page);

Working with WP_Screen – Tabs and the Sidebar

The main feature of the new Help tab system is the ability to divide your help menu into separate sections without a lot of effort.

For each help tab you want to create, call the add_help_tab method to build it. You can specify the content of the help tab inline, or use a callback to generate it.

 
	/**
	 * Inline tab content
	 */
	$this->admin_screen->add_help_tab(
		array(
			'title'    => 'Help',
			'id'       => 'help_tab',
			'content'  => '<p>This is my content.</p>',
			'callback' => false
		)
	);
 
	/**
	 * Content generated by callback
	 * The callback fires when tab is rendered - args: WP_Screen object, current tab
	 */
	$this->admin_screen->add_help_tab(
		array(
			'title'    => 'Info on this Page',
			'id'       => 'page_info',
			'content'  => '',
			'callback' => create_function('','echo "<p>This is my generated content.</p>";')
		)
	);

The sidebar is a much nicer way to display the list of links we’ve often put at the bottom of the help panel. It’s displayed regardless of which tab is selected.

 
	$this->admin_screen->set_help_sidebar(
		'<p>This is my help sidebar content.</p>'
	);

WP_Screen and Options

WP_Screen excels at handling help pages. Unfortunately, the only options it seems to recognize with the add_option method are the built-in per_page and layout_columns. Anything else simply isn’t displayed.

 
	$this->admin_screen->add_option( 
		'per_page', 
		array(
			'label' => 'Entries per page', 
			'default' => 20, 
			'option' => 'edit_per_page'
		) 
	);
 
	$this->admin_screen->add_option( 
		'layout_columns', 
		array(
			'default' => 3, 
			'max' => 5
		) 
	);
 
	/**
	 * This option will NOT show up
	 */
	$this->admin_screen->add_option( 
		'invisible_option', 
		array(
			'label'	=> 'I am a custom option',
			'default' => 'wow', 
			'max' => 5
		) 
	);

But you can use a metabox to at least get a custom checkbox generated.

 
	/**
	 * Old-style metaboxes still work for creating custom checkboxes in the option panel
	 * This is a little hack-y, but it works
	 */
	add_meta_box(
		'my_meta_id',
		'My Metabox',
		array(&$this,'create_my_metabox'),
		$this->admin_page
	);
}

And here’s the complete skeleton:

 
<?php
/*
Plugin Name: WP 3.3 WP_Screen Test
Version: 1.0
*/
 
class wp_screen_test {
 
	private $slug = 'screentest';
	private $admin_page;
	private $admin_screen;
 
	public function __construct() {
		add_action( 'admin_menu', array(&$this, 'admin_menu') );
	}
 
	public function admin_menu() {
 
		/**
		 * Save the handle to your admin page - you'll need it to create a WP_Screen object
		 */
		$this->admin_page = add_options_page( 
			__('WP_Screen Test','my-plugin'), 
			__('WP_Screen Test','my-plugin'), 
			'manage_options', 
			$this->slug, 
			array(&$this, 'test_page') 
		);
 
		add_action("load-{$this->admin_page}",array(&$this,'create_help_screen'));
	}
 
 
	public function create_help_screen() {
 
		/** 
		 * Create the WP_Screen object against your admin page handle
		 * This ensures we're working with the right admin page
		 */
		$this->admin_screen = WP_Screen::get($this->admin_page);
 
		/**
		 * Content specified inline
		 */
		$this->admin_screen->add_help_tab(
			array(
				'title'    => 'Help',
				'id'       => 'help_tab',
				'content'  => '<p>This is my content.</p>',
				'callback' => false
			)
		);
 
		/**
		 * Content generated by callback
		 * The callback fires when tab is rendered - args: WP_Screen object, current tab
		 */
		$this->admin_screen->add_help_tab(
			array(
				'title'    => 'Info on this Page',
				'id'       => 'page_info',
				'content'  => '',
				'callback' => create_function('','echo "<p>This is my generated content.</p>";')
			)
		);
 
		$this->admin_screen->set_help_sidebar(
			'<p>This is my help sidebar content.</p>'
		);
 
		$this->admin_screen->add_option( 
			'per_page', 
			array(
				'label' => 'Entries per page', 
				'default' => 20, 
				'option' => 'edit_per_page'
			) 
		);
 
		$this->admin_screen->add_option( 
			'layout_columns', 
			array(
				'default' => 3, 
				'max' => 5
			) 
		);
 
		/**
		 * This option will NOT show up
		 */
		$this->admin_screen->add_option( 
			'invisible_option', 
			array(
				'label'	=> 'I am a custom option',
				'default' => 'wow', 
				'option' => 'my_option_id'
			) 
		);
 
		/**
		 * But old-style metaboxes still work for creating custom checkboxes in the option panel
		 * This is a little hack-y, but it works
		 */
		add_meta_box(
			'my_meta_id',
			'My Metabox',
			array(&$this,'create_my_metabox'),
			$this->admin_page
		);
	}
 
	public function test_page() {
		// Plugin options page content
	}
 
}
 
function screen_test_init() {
	$screenTest = new wp_screen_test();
}
 
add_action( 'init', 'screen_test_init' );

4 Responses to WordPress Plugin Help Panels with WP_Screen – Features and Limits

Murali

November 29, 1999 at 7:00 pm

Great tutorial David!

Thanks a lot.

olivier

December 22, 2011 at 4:07 am

Thanks a lot, it helped me

lloop

December 28, 2011 at 4:55 pm

thanks!!

Jose

April 21, 2012 at 3:21 am

Thanks David !

GeneralThreat.com