From 050aed35b066544ed0e651529391848ed8e59960 Mon Sep 17 00:00:00 2001 From: Jennifer Hodgdon Date: Wed, 18 Jun 2014 07:12:27 -0700 Subject: Issue #2263047 by joshi.rohit100, lostkangaroo, sachin_s, martin107: Fix up hook_help docs and move to system module --- modules/system/system.api.php | 55 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) (limited to 'modules/system') diff --git a/modules/system/system.api.php b/modules/system/system.api.php index fbcb17348..5a25fe7af 100644 --- a/modules/system/system.api.php +++ b/modules/system/system.api.php @@ -2109,6 +2109,61 @@ function hook_permission() { ); } +/** + * 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. + * + * The page-specific help information provided by this hook appears as a system + * help block on that page. The module overview help information is displayed + * by the Help module. It can be accessed from the page at admin/help or from + * the Modules page. + * + * For detailed usage examples of: + * - Module overview help, see node_help(). Module overview help should follow + * @link https://drupal.org/node/632280 the standard help template. @endlink + * - Page-specific help with simple paths, see dashboard_help(). + * - Page-specific help using wildcards in path and $arg, see node_help() + * and block_help(). + * + * @param $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'. + * For the help page for the module as a whole, $path will have the value + * 'admin/help#module_name', where 'module_name" is the machine name of your + * module. + * @param $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 + * A localized string containing the help text. + */ +function hook_help($path, $arg) { + switch ($path) { + // Main module help for the block module + case 'admin/help#block': + return '

' . 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 blocks administration page 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'))) . '

'; + + // Help for another path in the block module + case 'admin/structure/block': + return '

' . 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 Save blocks button at the bottom of the page.') . '

'; + } +} + /** * Register a module (or theme's) theme implementations. * -- cgit v1.2.3