[wp-hackers] Change in plugin Options page handling

[Morgan Doocy]

Hi all,

Matt is implementing a change in the way plugin Options pages are be 
loaded, and he wanted me to contact plugin developers to inform them of 
the change. It relates to bug #785 in Mosquito. [1]

[1] http://mosquito.wordpress.org/view.php?id=785

First, some background on the way plugin Options pages are currently 
handled.

In order to add a custom Options page, a plugin does the following:

add_options_page($page_title, $menu_title, $access_level, $file);

...where $page_title is the text to be displayed in the <title> of the 
page, $menu_title is the text of the item in the Options submenu, 
$access_level is the minimum user level required in order to access the 
plugin's Options page, and $file is the filename of the plugin.

Since it is recommended that plugins be contained in one file, rather 
than being split up into a plugin file and an Options page, most 
plugins specify the plugin's own filename for $file -- causing it to be 
loaded an additional time for displaying the Options page.

In order prevent function redeclaration errors, the is_plugin_page() 
function was created, making plugin pages take on the following format:

if (is_plugin_page()) {
	// do Options page output
}
else {
	// declare functions, add filters and hooks, etc.
}

Meaning that the first time the page is loaded (i.e. along with all the 
rest of the plugins), is_plugin_page() evaluates to false, and the else 
block is executed. The second time it is loaded, is_plugin_page() 
evaluates to true, and the if block is executed.

This has been extremely difficult for first-time plugin developers to 
wrap their minds around, and most of us felt that it was a pretty 
kludgy way of doing things -- inconsistent with 'hook' nature of the 
rest of the plugin architecture and causing unnecessary heartburn and 
confusion over the fact that the plugin is loaded twice.

To remedy this I proposed deprecating the double-load method in favor 
of an action hook for outputting a plugin's Options page. The hook tag 
is in the format 'options_page_<pluginname>', where <pluginname> is the 
filename of the plugin, stripped of its '.php' extension. To use my 
plugins as examples:

add_action('options_page_multilingual', 'ml_options_page');

...for my multilingual.php plugin, and:

add_action('options_page_mini-posts', 'mp_options_page');

...for my mini-posts.php plugin.

This eliminates the need for the plugin to be loaded a second time, 
thereby eliminating the confusion of using is_plugin_page() (or even if 
(!function_exists()), as some people are using) to prevent code from 
being executed twice.

Note that backward compatibility with the current method will be 
maintained, but it is deprecated, and plugin documentation will be 
changed to reflect the new method only. At some point in the future the 
double-loading functionality will be eliminated entirely.

Thanks!

Morgan Doocy