Simple, free resources to help you build a better WordPress website.

Sign up for our newsletter.

Incorporating Contextual Help and Support into WordPress Themes

One of the great improvements of the recently released WordPress 3.3 is the enhancement to the contextual help feature for admin screens. Originally, the contextual help screen was largely rudimentary, and designed to display basic text.

However, contextual help was improved considerably in WordPress 3.3, with an all-new Screen API, and UI enhancements such as tabs and a sidebar. These enhancements are perfect for organizing contextual help, especially for Themes with complex Theme options, and/or tabbed UIs for Theme settings pages – in other words, these enhancements are perfect for UpThemes!

So, I’ve been experimenting with incorporating the new hotness in our Themes. Especially compared to the previous iteration, the WP 3.3 contextual help is actually quite simple to integrate. Otto Wood wrote a detailed tutorial here.

All contextual help-related functionality is handled through the WP_Screen() class, so the first step is identifying the Theme’s specific admin screen. WordPress simplifies this identification, by defining a hook for every admin screen, based on the add_*_page() function used to instantiate the page. Accessing this hook is as simple as defining a global variable when calling add_*_page(). If our original code is as follows:

function micro_add_settings_page() {
    // Add Micro Theme settings page
    add_theme_page( $args );
}
add_action( 'admin_menu', 'micro_add_settings_page' );

…then we modify it like so:

function micro_add_settings_page() {
    // Global variable for Micro's settings page hook
    global $micro_settings_page;
    // Add Micro Theme settings page
    $micro_settings_page = add_theme_page( $args );
}
add_action( 'admin_menu', 'micro_add_settings_page' );

The next step, then, is to invoke contextual help for our Theme’s settings page. Again, WordPress provides a specific hook for this purpose: load-$pagehook. Since we’ve defined a global to hold the name of our Theme’s specific page hook, we can use it here:

function micro_add_settings_page() {
    // Global variable for Micro's settings page hook
    global $micro_settings_page;
    // Add Micro Theme settings page
    $micro_settings_page = add_theme_page( $args );
    // Add contextual help
    add_action( 'load-' . $micro_settings_page, 'micro_add_contextual_help' );
}
add_action( 'admin_menu', 'micro_settings_page_contextual_help' );

Next, as you might imagine, we define the micro_settings_page_contextual_help() callback:

function micro_settings_page_contextual_help() {
}

The first step is to invoke the screen object. The WP_Screen() class provides a useful function that we’ll use for this step, but will also make use of later: get_current_screen(). This function “returns an object that includes the screen’s ID, base, post type, and taxonomy, among other data points.”

function micro_settings_page_contextual_help() {
    // Globalize settings page
    global $micro_settings_page;
    // Get the current screen object
    $screen = get_current_screen();
}

The next step is redundant (since we already use a page-specific hook to execute our callback), but is a standard failsafe: ensure we’re on our own Theme’s settings page. Here, we use the $screen->id parameter:

function micro_settings_page_contextual_help() {
    // Globalize settings page
    global $micro_settings_page;
    // Get the current screen object
    $screen = get_current_screen();

    // Ensure current page is Micro settings page
    if ( $screen->id != $micro_settings_page ) {
        return;
    }
}

Having assured that we are on our own Theme’s settings page, we now begin to add content to the contextual help, using the add_help_tab() member function of the WP_Screen() class. We’ll use a “README” tab for example:

function micro_settings_page_contextual_help() {
    // Globalize settings page
    global $micro_settings_page;
    // Get the current screen object
    $screen = get_current_screen();

    // Ensure current page is Micro settings page
    if ( $screen->id != $micro_settings_page ) {
        return;
    }

    // Add README Reference help screen tab
    $screen->add_help_tab( array(
        // HTML ID attribute
        'id'      => 'micro-readme',
        // Tab title
        'title'   => __( 'README', 'micro' ),
        // Tab content
        'content' => file_get_contents( get_template_directory() . '/help/readme.html' ),
    ) );
}

The 'content' parameter expects a string, but this parameter can be replaced with 'function' in order to pass a callback instead. Since our Themes already ship with a “readme.html” file, we can simply pass it here as a string, via file_get_contents().

For every contextual help tab needed, simply add another $screen->add_help_tab() call. Here are some proof-of-concept screenshots:

Here, you can see the contextual help panel, with several tabs. The "Theme Documentation" tab includes the (HTML) content of the Theme's existing readme.html file.

And here you can see the several tabs in the contextual help panel - one tab for each of the UpThemes settings pages.

Notice, in the tab list, a “Support” tab at the bottom. This tab is something else that I’m working on integrating into our Themes.

Here at UpThemes, we use private GitHub repositories for collaborative development, and for bug tracking. I also use GitHub for my personal projects, including my Oenology Theme, which also integrates the new WordPress 3.3 contextual help. Also included in the contextual help, however, is a fairly full-featured support tab, including links to submit support issues, an RSS feed for support forum posts, and, thanks to the awesome GitHub API, real-time reports of commits and issues (i.e. bugs), both opened and closed. Here’s how it looks in Oenology:

Here's how the contextual help support tab looks in Oenology. The data are all pulled in dynamically, from the wordpress.org support forum, and via the GitHub API.

I think this is great, because it helps Theme users get a better idea of ongoing development and bugfixes. While useful for a free Theme, it can potentially be a great premium feature for a commercial Theme. So, I’ve roughed in the same features into Micro. Since the UpThemes GitHub repositories are private, I need to add in an oAuth token in order to use the API to read commit and issue data, which is why the API is returning 404s:

This will be essentially the same, once I implement the oAuth tokens to be able to read GitHub API data for private repositories.

Look for these features to be rolled out into our Themes in the very near future! For current and future UpThemes customers: how would you like to see these features implemented? What would you find the most useful?

16 Comments

  1. Pingback: WordPress Weekly Links | WPStream.com

  2. Pingback: Incorporating Contextual Help and Support into WordPress Themes … | codu.in

  3. Pingback: Writing Effective Documentation For WordPress End Users | t1u

  4. Pingback: Writing Effective Documentation For WordPress End Users@smashing | seo博客大全

  5. Pingback: Writing Effective Documentation For WordPress End Users | MyOfflineTheme.com Skyrocket Your Offline Business Just Now

  6. Pingback: Writing Effective Documentation For WordPress End Users | Web Design Kingston

  7. Pingback: Writing Effective Documentation For WordPress End Users | DigitalMofo

  8. Pingback: Writing Effective Documentation For WordPress End Users » E BLADE

  9. Pingback: Steve deGuzmanWriting Effective Documentation For WordPress End Users » Steve deGuzman

  10. Pingback: Writing Effective Documentation For WordPress End Users | TheSite.me

  11. Pingback: Writing Effective Documentation For WordPress End Users | Elitewebworks-Web Design and Development

  12. Pingback: Writing Effective Documentation For WordPress End Users – Creativevia

  13. Pingback: Rutweb Technology : Writing Effective Documentation For WordPress End Users

  14. Pingback: Writing Effective Documentation For WordPress End Users | Buypappa blog

  15. Pingback: Effective Documentation Writting For End Users Of Wordpress | WordPress Planet

  16. Pingback: Writing Effective Documentation For WordPress End Users - Goodfav Howto

Leave a Reply

Your email address will not be published. Required fields are marked *