function hook_help

You are here

7 system.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 system.api.php hook_help($route_name, \Drupal\Core\Routing\RouteMatchInterface $route_match)

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/node' or 'user/edit'. If the router path includes a % wildcard, then this will appear in $path; for example, node pages would have $path equal to 'node/%' or 'node/%/view'. Your hook implementation may also be called with special descriptors after a "#" sign. Some examples:

  • admin/help#modulename The main module help text, displayed on the admin/help/modulename page and linked to from the admin/help page.
  • user/help#modulename The help for a distributed authorization module (if applicable).

$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 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

37 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
Implementation of hook_help().
block_help in modules/block/block.module
Implementation of hook_help().
blogapi_help in modules/blogapi/blogapi.module
Implementation of hook_help().
blog_help in modules/blog/blog.module
Implementation of hook_help().
book_help in modules/book/book.module
Implementation of hook_help().

... See full list

5 invocations of hook_help()
help_links_as_list in modules/help/help.admin.inc
help_menu in modules/help/help.module
Implementation of 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.
system_admin_by_module in modules/system/system.admin.inc
Menu callback; prints a listing of admin tasks for each installed module.

File

developer/hooks/core.php, line 883
These are the hooks that are invoked by the Drupal core.

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 Garland, for example, implements the regions "left sidebar", "right sidebar", "content", "header", and "footer", 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/build/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

"Regardless, $arg[0] to $arg[11] will always be set."

I think should read

Regardless, $arg[0] to $arg[1] will always be set

Right?

If not, forgive me, I'm just learning about module development now.

I haven't tested this, but a Drupal menu router path can contain up to 9 parts, arg(0) to arg(9), so this will just be a reference to tell you not to rely on isset() to test a particular path component. So only $arg[0] and $arg[1] would not empty on "node/%", but $arg[0] to $arg[11] are all set.

If I want that the help is being displayed in all page under the path 'admin', what menu router path should I define? Thanks for help.

It appears that the bug detailed at http://drupal.org/node/72645 is still affecting this and if you have a theme that has the same name as your module that you are calling hook_help() from then it will cause problems.

It also appears that if you implement a modulename_theme() call in your module and also a modulename_help() call then its gonna cause problems too.

I found that out the hard way.