www.aleph1.co.uk Git - yaffs-website/blob - web/core/modules/help/help.api.php

   1 <?php
   2
   3 /**
   4  * @file
   5  * Hooks for the Help system.
   6  */
   7
   8 /**
   9  * @addtogroup hooks
  10  * @{
  11  */
  12
  13 /**
  14  * Provide online user help.
  15  *
  16  * By implementing hook_help(), a module can make documentation available to
  17  * the user for the module as a whole, or for specific pages. Help for
  18  * developers should usually be provided via function header comments in the
  19  * code, or in special API example files.
  20  *
  21  * The page-specific help information provided by this hook appears in the
  22  * Help block (provided by the core Help module), if the block is displayed on
  23  * that page. The module overview help information is displayed by the Help
  24  * module. It can be accessed from the page at /admin/help or from the Extend
  25  * page. If a module implements hook_help() the help system expects module
  26  * overview help to be provided.
  27  *
  28  * For detailed usage examples of:
  29  * - Module overview help, see content_translation_help(). Module overview
  30  *   help should follow
  31  *   @link https://www.drupal.org/node/632280 the standard help template. @endlink
  32  * - Page-specific help using only routes, see book_help().
  33  * - Page-specific help using routes and $request, see block_help().
  34  *
  35  * @param string $route_name
  36  *   For page-specific help, use the route name as identified in the
  37  *   module's routing.yml file. For module overview help, the route name
  38  *   will be in the form of "help.page.$modulename".
  39  * @param Drupal\Core\Routing\RouteMatchInterface $route_match
  40  *   The current route match. This can be used to generate different help
  41  *   output for different pages that share the same route.
  42  *
  43  * @return string|array
  44  *   A render array, localized string, or object that can be rendered into
  45  *   a string, containing the help text.
  46  */
  47 function hook_help($route_name, \Drupal\Core\Routing\RouteMatchInterface $route_match) {
  48   switch ($route_name) {
  49     // Main module help for the block module.
  50     case 'help.page.block':
  51       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.', [':blocks' => \Drupal::url('block.admin_display')]) . '</p>';
  52
  53     // Help for another path in the block module.
  54     case 'block.admin_display':
  55       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>';
  56   }
  57 }
  58
  59 /**
  60  * Perform alterations on help page section plugin definitions.
  61  *
  62  * Sections for the page at /admin/help are provided by plugins. This hook
  63  * allows modules to alter the plugin definitions.
  64  *
  65  * @param array $info
  66  *   Array of plugin information exposed by hook page section plugins, altered
  67  *   by reference.
  68  *
  69  * @see \Drupal\help\HelpSectionPluginInterface
  70  * @see \Drupal\help\Annotation\HelpSection
  71  * @see \Drupal\help\HelpSectionManager
  72  */
  73 function hook_help_section_info_alter(&$info) {
  74   // Alter the header for the module overviews section.
  75   $info['hook_help']['header'] = t('Overviews of modules');
  76 }
  77
  78 /**
  79  * @} End of "addtogroup hooks".
  80  */