annotate core/modules/help/help.api.php @ 19:fa3358dc1485 tip

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