You are here: Home . Code, WordPress . Adding screen options to a WordPress plugin

Adding screen options to a WordPress plugin

In WordPress, adding screen options during plugin development is not one of those things with a lot of documentation. There’s a great tutorial on this by Chris Marslender. There’s one here too by someone I’m a fan of, Pippin Williamson. Both went a long way to get me started. I differ from these approaches in 2 things:

  1. I use OO
  2. I use a less expensive approach in retrieving the screen option

Now, on to the good stuff….

First, pick the hook that’s returned when your options page is created:

$my_plugin_hook = add_menu_page( $page_title, $menu_title, $capability, $slug, $function );

Add an action based on that hook:

add_action( "load-$my_plugin_hook", array ( $this, 'add_option' ) );

My assumption here is that add_screen_option is in the same class that the action above is defined.

Then, onto our add_screen_option function:

class My_Plugin_Class {
     private $tickets_per_page_options_key = "myplugin_tickets_per_page";
     private $default_tickets_per_page     = 20;

     public function __construct() {
        $this->add_menu_pages();
       add_filter('set-screen-option', array ( $this, 'set_screen_option' ), 10, 3);
     }
     public add_menu_pages(){
     //Add your page(s), use the hook(s) returned to add screen options as explained above
    }

//The other cool stuff your plugin does 

public function add_option() {

$option = 'per_page';

$args = array(
    'label' => __('Tickets', 'my-plugin'),//The second parameter is your text domain. It is used in 'Internalization', the fancy word to mean 'Translate your plugin into other languages'
    'default' => $this->default_tickets_per_page,
    'option' => $this->tickets_per_page_options_key
);

add_screen_option( $option, $args );

}
//Now we set the screen option. This is called by the filter we defined in our constructor
public function set_screen_option($status, $option, $value) {

    if ( $this->tickets_per_page_options_key == $option ) return $value;

    return $status;

}
}

Now, on to that less expensive approach for retrieving your saved screen option that I spoke of earlier. The other tutorials require that you first get_current_screen() and use it in your retrieval. I believe all you need is this:

$per_page = get_user_meta(get_current_user_id(), $this->tickets_per_page_options_key, true);
//To have a fall-back in case the option isn't defined, all you need is this:
if ( empty ( $per_page) || $per_page < 1 ) {

    $per_page = $this->$default_tickets_per_page;

}
//NB: All this is in your class My_Plugin_Class

From my tests, screen options are stored in the WP usermeta table; all you need to retrieve them is the key and the user’s ID. Then, to fallback to a default value, use your default variable; there’s no need to go back to the Db for that

Using diligent minions, I bring these tutorials & tips to your inbox every week. Give a minion work today; add your email address here