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