function hook_help

You are here

7 help.api.php hook_help($path, $arg)
4.6 core.php hook_help($section)
4.7 core.php hook_help($section)
5 core.php hook_help($section)
6 core.php hook_help($path, $arg)
8 help.api.php hook_help($path, $arg)

Provide online user help.

By implementing hook_help(), a module can make documentation available to the user for the module as a whole, or for specific paths. Help for developers should usually be provided via function header comments in the code, or in special API example files.

For a detailed usage example, see page_example.module.

Parameters

$path: The router menu path, as defined in hook_menu(), for the help that is being requested; e.g., 'admin/people' or 'user/register'. If the router path includes a wildcard, then this will appear in $path as %, even if it is a named %autoloader wildcard in the hook_menu() implementation; for example, node pages would have $path equal to 'node/%' or 'node/%/view'. To provide a help page for a whole module with a listing on admin/help, your hook implementation should match a path with a special descriptor after a "#" sign: 'admin/help#modulename' The main module help text, displayed on the admin/help/modulename page and linked to from the admin/help page.

$arg: An array that corresponds to the return value of the arg() function, for modules that want to provide help that is specific to certain values of wildcards in $path. For example, you could provide help for the path 'user/1' by looking for the path 'user/%' and $arg[1] == '1'. This given array should always be used rather than directly invoking arg(), because your hook implementation may be called for other purposes besides building the current page's help. Note that depending on which module is invoking hook_help, $arg may contain only empty strings. Regardless, $arg[0] to $arg[11] will always be set.

Return value

A localized string containing the help text.

Related topics

48 functions implement hook_help()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

aggregator_help in modules/aggregator/aggregator.module
Implements hook_help().
block_help in modules/block/block.module
Implements hook_help().
blog_help in modules/blog/blog.module
Implements hook_help().
book_help in modules/book/book.module
Implements hook_help().
color_help in modules/color/color.module
Implements hook_help().

... See full list

6 invocations of hook_help()
field_help in modules/field/field.module
Implements hook_help().
help_links_as_list in modules/help/help.admin.inc
Provides a formatted list of available help topics.
help_menu in modules/help/help.module
Implements hook_menu().
help_page in modules/help/help.admin.inc
Menu callback; prints a page listing general help for a module.
menu_get_active_help in includes/menu.inc
Returns the help associated with the active menu item.

... See full list

File

modules/help/help.api.php, line 49
Hooks provided by the Help module.

Code

function hook_help($path, $arg) {
  switch ($path) {
    // Main module help for the block module
    case 'admin/help#block':
      return '<p>' . t('Blocks are boxes of content rendered into an area, or region, of a web page. The default theme Bartik, for example, implements the regions "Sidebar first", "Sidebar second", "Featured", "Content", "Header", "Footer", etc., and a block may appear in any one of these areas. The <a href="@blocks">blocks administration page</a> provides a drag-and-drop interface for assigning a block to a region, and for controlling the order of blocks within regions.', array('@blocks' => url('admin/structure/block'))) . '</p>';

      // Help for another path in the block module
    case 'admin/structure/block':
      return '<p>' . t('This page provides a drag-and-drop interface for assigning a block to a region, and for controlling the order of blocks within regions. Since not all themes implement the same regions, or display regions in the same way, blocks are positioned on a per-theme basis. Remember that your changes will not be saved until you click the <em>Save blocks</em> button at the bottom of the page.') . '</p>';
  }
}

Comments

Another example:

/**
  * Implement hook_help()
  */
function yourmodulename_help($path, $arg) {
switch ($path) {
case 'admin/help#yourmodulename':
   $output = '';
   $output .= '<h3>' . t('About') . '</h3>';
   $output .= '<p>' . t("A helpful entry about your module") . '<p>';
return $output;
   }
}

@bhosmer - the extra $output in your example may have side effects, such as for example #yourmodulename not being defined on the admin/help page.

A cleaner way to do this without errors would to just return your output:

/**
  * Implement hook_help()
  */
function yourmodulename_help($path, $arg) {
switch ($path) {
case 'admin/help#yourmodulename':
   return '' .  '<h3>' . t('About') . '</h3>' . '<p>' . t("A helpful entry about your module") . '<p>'
   }
}

You can wrap your output in a variable if you need to, however the example you give will probably throw a warning in D7.

When experimenting with hook_help(), or adding it to an existing module, there is some caching in effect. Possibly in the menu router.
If you don't see the results you expect, try flushing your caches.

Drupal 7

Module administration page - on bottom of help page
Example, go to help page and click on block.
Now at the bottom you will see the block administration page.
The code for generating this is in core.
See help.admin.inc in the modules/help folder.

Remember don't modify core.

// Only print list of administration pages if the module in question has
// any such pages associated to it.
$admin_tasks = system_get_module_admin_tasks($name, $info[$name]);
if (!empty($admin_tasks)) {
$links = array();
foreach ($admin_tasks as $task) {
$links[] = l($task['title'], $task['link_path'], $task['localized_options']);
}
$output .= theme('item_list', array('items' => $links, 'title' => t('@module administration pages', array('@module' => $info[$name]['name']))));
}

<?php
/**
  * Implement hook_help()
  */
function yourmodulename_help($path, $arg) {
switch (
$path) {
case
'admin/help#yourmodulename':
      
$current_theme = variable_get('theme_default');
      
$output = '<h3>';
      
$output .= t('Help Title') . '</h3>';
      
$output .= '<p>' . t('Description: @theme', array('@theme' => $current_theme)) . '</p>';
       return
$output;
   }
}
?>

Assume demo is my module name

<?php
function demo_help($path,$arg){
switch(
$path){
case
'admin/setting/demo':
     return
t('this is some help text for demo module');
break;
case
'admin/help#demo';
 
$helpTxt='<p>'.t('this is a demo help text').'<p>';
  return
$helpTxt;   
break;

}

}

?>

Where is break in the end of switch statement?

it's not strictly necessary if there's a return, which will interrupt the code's execution.

Return should always be at the end of the function instead of in the middle. That way the switch (or if-else, if you use one) statement fully executes, all conditions are fully tested, and the function does not exit prematurely.

<?php
function demo_help($path, $arg) {
 
$helpText = "";
 
  switch(
$path){
    case
'admin/setting/demo':
     
$helpText = "this is some help text for demo module";
      break;
    case
'admin/help#demo';
     
$helpText = "this is a demo help text";
      break;
  }
 
  return
"<p>" . t($helpText) . "</p>";
}
?>

This way you will always return something, in your case you gonna return always a string containing at least '<p></p>', so the help page of every module will always display your (empty) paragraph, regardless of the fact that the user has opened the help page of your module.

I agree about return case, but I'm not sure about variable inside t() concerning the translation system.

$helpText = 'this is some string';
t($helpText);

I think the translation system won't work in the case above. Because when the automated translation system runs through the code, it does not execute the code. It simply reads it.

I made a module, and I made a Help page for it, a Configure link as well.
But I can't see the "Mymodule administration pages" at the bottom of the Help page.
Isn't that automatically create ?