Over a million developers have joined DZone.

The Help Helper

· Web Dev Zone

So in part one of this two part series I covered how to integrate help documentation for your plugin into WordPress using the built in WordPress functions. But if you write a lot of plugins, or plan to, then it might be a good idea to create a class which encapsulates some of this functionality. This is exactly what I have done and the Help helper class can be found on my downloads page.

How to use the Help helper

As before we will need to add a hook to a function to register and display the help. So let us make some assumptions.

  1. Our plugin is implemented in a class which allows the functions to be encapsulated in their own namespaces.
  2. Our plugin is called MyWonderfulPlugin.
  3. We have an admin page, and we register this using the add_plugins_page function which returns the id of our plugin.
  4. We store the id in a member level variable in a class called $my_wonder_plug_id.

First we need to implement the hook. As I said in the last article I find the best place to do this is just after the call to the add_plugins_page function. So if we have a function to register our admin page it would look something like the following.

	public function register_admin_page() {
	
		$this->my_wonder_plug_id = add_plugins_page(
			'My Wonderful Plugin',
			'My Wonderful Plugin',
			'manage_options',
			'my-wonderful-plugin',
			array( $this, 'display_page' )
		);
		
		add_action( 'load-'.$this->my_wonder_plug_id, array( $this, 'register_help' ) );	
	}

This is WordPress plugin development so there should be few surprises. The first function call, add_plugins_page, registers our plugin admin page and the add_action call hooks our register_help function to the ‘load-’ action. When our plugin is loaded our register_help function will be called.

Because we have our functions implemented in a class we use $this to refer to the class or member level variable where we are storing the id of the plugin. We also need to pass an array of a reference to the class, $this, as well as the name of the function to call, to the callback parameters of the add_plugins_page and the add_action functions.

Ignore the function ‘display_page’ that is being passed to add_plugins_page. If you were writing a fully functional plugin you would put the code to render the admin page in this function. However that is beyond the scope of this article.

So let us take a look at our register_help function.

public function register_help () {

	$help = Fofo_Help_Helper_Creator::create();
	$help_directory = plugin_dir_path( __FILE__ ).'/help_files';
	$help->set_help_text_repository( $help_directory );
		
	$help->add_help_tab( 'my-wonder-plug-help1', 'Overview', 'help1.txt');
	$help->add_help_tab( 'my-wonder-plug-help1', 'Help Page 2', 'help2.txt');
	$help->add_help_tab( 'my-wonder-plug-help1', 'Help Page 3', 'help3.txt');
	$help->add_help_tab( 'my-wonder-plug-help1', 'Help Page 4', 'help4.txt');
	
	$help->render_help( $this->my_wonder_plug_id );
}

So how does it work? Well the first line is used to create a Help helper. The creation of the class is hidden as this hides the messiness of versioning from the user of the help helper.

The third line, set_help_text_repository sets the location where all our files will be stored with the help content. By using a repository of smaller help files, the help can be broken into smaller logical chunks making maintenance easier.

The next few lines are where we tell the help system what our tabs should be. The arguments to the add_help_tab are, respectively, the id or slug for the help tab, the title of the tab and finally the name of the file in the repository which contains the content of the help tab.

Finally we call the render_help method, passing in the id of the plugin, to display the help on the plugin’s admin page.

So that is it. Please feel free to download the Help helper class and use it in your own projects. It makes implementing help in WordPress very simple and easy to do.

Topics:

Published at DZone with permission of Chris Odell, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

SEE AN EXAMPLE
Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
Subscribe

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}