Help Tooltips

How is content displayed in Help Tooltips

Ah-O2 utilizes the JQuery UI Tooltips object to create and display Help Content on the various Administrative Pages. As WordPress does not currently have a concept of Help Tooltips any and all tooltip content are added by the Ah-O2 project. To have tooltips display within the administration page you need to declare JS code to identify the DOM element the tooltip will be displayed on and add the content to be displayed in PHP to allow for localization.

I want to add new tooltips, but I don't know where to start

We have a handy-dandy spreadsheet prepared that outlines all the admin pages and what they need. This is sort of all-purpose, but right now we're using it to mark admin pages as done as far as tooltips go as well as allowing people to "claim" an admin page.

How do I add tooltips to a new admin page?

To maintain ease of adding new tooltips we have segregated the content and JS based on the screen ID of the Administrative Page.

JavaScript files will be found witin the js folder of the plugin and have the format adminhelp-[slug].js for example: adminhelp-plugins.js, adminhelp-edit-post.js

PHP Content files will be found within the docs folder and have the format [slug]-tips.php for example: edit-post-tips.php, plugins-tips.php

In most cases, the page slug will be the same as the screen ID (for example, plugins.php corresponds to screen ID, plugins). In others, that won't be the case. In order to identify which screen ID is in use on any given page, you can add this line to class-ah-o2-admin.php around line 152 right below $screen = get_current_screen():

var_dump($screen->id);

The screen ID will be dumped at the top of the admin page and that is the slug that you will need to use to create the doc and js file.

You can also check the Admin Screen Reference page for screen IDs.

How do I create a new Tooltip

To add a new Help Tooltip to the page you add an entry to the AdminHelp object in Javascript. The add function takes an array as input so you can comma separate as many tooltips that you want for the page. The tooltip is defined by using 3 parameters.

slug : name of tooltip

selector :: array of css selectors to find element that tooltip will be attached to

content :: PHP Associative array key that contains the content of the tooltip. Note that adminhelp_content is the variable the PHP content gets written to in JS.

jQuery(function( $ ) {
	/**
	 * Setup tooltips as objects in an array.
	 * @param string slug How the AdminHelp class identifies the tooltip
	 * @param array selector Array of css selectors for the items the tooltip
	 * should be attached to
	 * @param string content Content to be displayed in the tooltip
	 */
	adminHelp.add([
		{
			slug: 'filtercategory'
			,selector: [
				'#post-query-submit'
			],
			content: adminhelp_content.filtercategory
		}
	]);
});

You can add as many Help Tooltips as desired for the page.

Where do I define the Help Tooltip Content?

The content for tooltips can be defined in the associated docs/[slug]-tips.php file. If no file exists for your page you can simply copy an existing file and rename it to have the correct syntax. In the file you simply define the content you want for the specified tooltip into the tooltip_help_content array.

<?php
$this->tooltip_help_content['filtercategory'] = '<p>' . __( 'Use the dropdown menus to the left to refine the list of posts by a specific category or from a specific month by. Click the Filter button after making your selection.', 'ah-o2' ) . '</p>';

Please remember to use the __() function for your content so it can be properly localized.