Accueil / Migrating the Drupal way. Part IV: helping your admins with hook_help() and Advanced Help

Migrating the Drupal way. Part IV: helping your admins with hook_help() and Advanced Help

Training is a huge consideration when moving to a new software platform. You have to ask yourself, how steep is the learning curve? How many people do you have to train? How many of those people are going to drag their feet? It has been my experience that no matter how much easier the new solution is, people still resist change. Sooner or later, you will have to send them off and running. For the fourth installment of my migration blog, I'm going to recommend leveraging Drupal's built in help functions as well as the Advanced Help module to make the transition smoother.

Create a custom module

Drupal comes with a great help system in the form of hook_help(), which allows you to create an entry in the global help page as well as providing help messages on regular site pages.

A simple custom module can go a long way in making your administrators feel comfortable. Remember that a module doesn't need to provide major site functions. A module can simply alter a form or, in this case, add specific documentation for your site administrators. The following custom module, which we'll call "website_help" is a quick example of how you might execute this method. Minimally, we will have to create two files: website_help.info and website_help.module. (See the module developer's guide on Drupal.org for more information on creating modules)

website_help.info:

; $Id$
name = Website Help
description = Provides helpful documentation for site administrators
core = 6.x

website_help.module:

<?php
// $Id$

/**
* @file
* Adds helpful messages for website administrators
* and provides documentation in /admin/help
*/

/**
* Implementation of hook_help().
*/
function website_help_help($path) {
  switch (
$path) {
    case
'admin/help#website_help':
      return
t('Here is a little bit of helpful information about administrating the site. This can use business-specific language to make things easier to understand.');
    break;
    case
'node/add/story':
      return
t('Don\'t forget to:<ul><li>Enter a title</li><li>Promote to front page</li><li>etc.</li></ul>');
    break;
    case
'node/%/edit':
      return
t('Some notes on editing nodes');
    break;
  }
}
?>
New Help TopicCreate a new topic in /admin/help
Create Story TipsCreate tips for entering nodes

Enabling this module will allow hook_help() to do the following:

You can use this method to add reminders for your site editors when they are adding or editing nodes. You can even use HTML elements like <ul> or <ol> to make things easy to follow. This method also creates a page in /admin/help where you can create a longer document or FAQ to provide more in-depth tutorials.

Advanced Help to the rescue

So, what if hook_help() isn't robust enough to explain your complex site administration? If you haven't tried it yet, I highly recommend checking out the Advanced Help module. This module extends Drupal help and provides a lot of cool features.

The biggest benefit that I have found by using Advanced Help is that it provides a hierarchical structure of help topics, much like a book with chapters. You may provide a general overview and then create sub-pages that go into depth about any number of topics. Some modules which can seem intimidating, like Views, now come with Advanced Help topics to make them much easier to learn.

Another big benefit of using Advanced Help is the ability to take complex help topics out of the module file and place them into .html files. This makes it easier to manage long topics and doesn't require knowledge of PHP to edit the help documents. These documents can be translated as well as indexed in site search!

File SystemAdd a help directory, .ini file and subtopic .html files to your custom module's directory
Advanced Help TopicYou will see your topic at /admin/advanced_help...
Advanced Sub Topicsalong with your subtopics

Let's take a look at a quick example by adding Advanced Help topics to your website_help module.

  1. Begin by creating a directory called "help" inside of the website_help directory.
  2. Inside of your new help directory, create a file called "website_help.help.ini" -or- [your module name].help.ini
  3. Add the following to website_help.help.ini:
    ; $Id$

    [advanced help settings]
    navigation = true

    [website-overview]
    title = "Website admin instructions and FAQ"
    weight = -10

    [website-admin]
    title = "How to use the Admin Settings"
    parent = "website-overview"
    weight = 0

    [website-permissions]
    title = "User Permissions"
    parent = "website-overview"
    weight = 1

    [website-content]
    title = "Content Management"
    parent = "website-overview"
    weight = 2
       
  4. The code above tells the system to look in your help folder for: website-overview.html, website-admin.html, website-permissions.html and website-content.html. These .html files will contain your help topics. It also says that website-overview.html is the parent of the other three.
  5. Write help topics inside of those .html files using HTML elements for organization NOTE: you don't need to use tags like <html>, <head>, <body>, etc.
  6. The Advanced Help module, not surprisingly, provides a great Advanced Help section for creating your own topics. Download and install it to read more about other settings. It also comes with an example module so that you can see it in action.

You will now have access to new topics in http://example.com/admin/advanced_help.

Using hook_help() and Advanced Help in concert

File SystemHide lengthy explainer text in a popup window

You can take this one step further by using popup windows. I guess this is somewhat controversial, but personally I like using popups. The Advanced Help module allows you to place a little "circle-?" icon next to any text on the site that will pop a window containing any one of your help topics (e.g. the website-content.html we created above). Advanced Help provides a theme hook that does all of the dirty work for you. Notice that the theme function takes three arguments here. The first specifies the theme hook, the second specifies your module name and the third specifies your help page without the .html extension.

<?php
// Creates a link to website-content.html
theme('advanced_help_topic', 'website_help', 'website-content');
?>

So, adding this to the hook_help() function in the website_help module will look like the following segment - notice the theme() function under the "node/add/story" case:
<?php
/**
* Implementation of hook_help().
*/
function website_help_help($path) {
  switch (
$path) {
    case
'admin/help#website_help':
      return
t('Here is a little bit of helpful information about administrating the site');
    break;
    case
'node/add/story':
     
// If the Advanced Help module exists, create a
      // popup link to the file: website-content.html
     
$popup = (module_exists('advanced_help')) ? theme('advanced_help_topic', 'website_help', 'website-content') : '';
      return
$popup . t('Don\'t forget to:<ul><li>Enter a title</li><li>Promote to front page</li><li>etc.</li></ul>');
    break;
    case
'node/%/edit':
      return
t('Some notes on editing nodes');
    break;
  }
}
?>

Using this method you can add specific help to nearly any page on your site and also keep tutorials handy in case someone gets lost. Having this documentation embedded in the site is going to save time and frustration... and hopefully stop some heel dragging. I really like using a system like this because I can tailor the language for the users, and write the tutorials specifically for the site. I usually create lots of ordered lists with steps for adding content and changing settings.

Hopefully you can see how extensible and user friendly this system is. If you provide lots of help documents for your site administrators, they will never feel lost when learning the new system. When migrating to Drupal, take the time to do this and your team will be much happier and much more productive!

Commentaires

Posted on by dmitrig01 (non vérifié).
<?php
$popup
= (module_exists('advanced_help')) ? theme('advanced_help_topic', 'website_help', 'website-content') : '';
?>

The module_exists part is not necessary. The theme theme function will output an empty string if it can't find a theme function with the specified name. Therefore, you only need the code to be the following:

<?php
$popup
= theme('advanced_help_topic', 'website_help', 'website-content');
?>

Also, would you mind describing a better use case for advanced help. Using it because some Acquia engineer likes it is not exactly going to sway me either way.