93. 帮助系统help

一个系统要是没有帮助信息那么会给使用者带来困惑， drupal除了官方网站上面有各种详尽的文档介绍外，还在系统内部内置了帮助系统来提供引导信息，为使用者考虑的很全面，内置帮助系统是由帮助模块来完成的，她通过三种方式向用户提供在线帮助：帮助块、系统帮助主页、模块帮助主页。

 

帮助块：

帮助模块提供了一个块：

\Drupal\help\Plugin\Block\HelpBlock

这是一个很简单的块Block（关于块更多请见本系列块主题），称为帮助块，但功能强大灵活，只要页面放置了该块，任意模块就可以通过她来显示帮助信息，在该块内部实际上是执行了 “help” 钩子，从钩子中收集帮助信息，这意味着任意模块可以通过help钩子向任意放置了帮助块的页面添加帮助信息，钩子如下：

function hook_help($route_name,  $route_match)
{
    return ;
}

参数$route_name是被请求页面的路由名（字符串值），但有一个例外见下文的模块帮助主页

参数$route_match是被请求页面的路由匹配器，也就是\Drupal::service("current_route_match");

在钩子函数中返回任意非真值时将忽略该钩子，她应该返回渲染数组或者一个字符串（也可以是能当做字符串使用的对象，如\Drupal\Core\Render\Markup），返回值处理如下：

$build[] = is_array($help) ? $help : ['#markup' => $help];

通常模块在实现该钩子时需要在内部依据路由名进行判断，以便只在目标页面提供帮助信息，否则提供的帮助信息将显示在所有放置了帮助块的页面中，这是不合理的，如果路由名相同但页面内容不同时，需要根据路由匹配器提供的信息做进一步判断。

注意：如果请求发生意外时帮助信息将不起作用，这里所指的意外并不是指异常，而是以下表达式为真：

$request->attributes->has('exception')为真，比如403或404响应

 

系统帮助主页：

也就是点击后台“管理>帮助”时打开的页面，在这里系统集中提供了所有帮助信息及其入口，该页面的路由定义如下：

help.main:
  path: '/admin/help'
  defaults:
    _controller: '\Drupal\help\Controller\HelpController::helpMain'
    _title: 'Help'
  requirements:
    _permission: 'access administration pages'

模块可以向该页面添加内容，该页面由帮助块以及帮助节section构成，帮助块上文已经讲了，该页面的“Getting Started”段落就是由help模块的钩子函数help_help提供的，其他段落由帮助节提供，默认有两个帮助节：“Module overviews”和“Tours”，她们分别由help模块和tour模块提供，其他模块也可以通过提供帮助节的方式向该页面添加内容，帮助节是由插件机制实现的，一个帮助节就是一个插件，以上控制器依据帮助节插件返回的内容构造用于显示的渲染数组。

 

帮助节插件管理器：

用于收集和管理系统中所有的帮助节插件，模块通过帮助节插件向系统帮助主页提供内容

服务id：plugin.manager.help_section

获取方法：\Drupal::service("plugin.manager.help_section ");

类：Drupal\help\HelpSectionManager

插件目录：Plugin/HelpSection

定义修改钩子：help_section_info

帮助节插件接口：\Drupal\help\HelpSectionPluginInterface

 

一个帮助节由三部分组成，在接口中分别对应三个方法：

标题：

对应系统帮助主页的段落标题，由getTitle()返回，返回值可以是字符串或渲染数组

描述：

对应系统帮助主页的段落描述，由getDescription()返回，返回值可以是字符串或渲染数组

主题链接：

一些超链接，可以让用户方便导航到对应页面，由listTopics()方法返回，返回值是一个数组，数组元素可以是Link对象也可以是一个渲染数组，后者允许更多控制

 

在自定义帮助节插件时可以继承帮助节基类：

\Drupal\help\Plugin\HelpSection\HelpSectionPluginBase

继承该基类后就可以把标题和描述放置到插件释文中，只需要根据情况实现listTopics()方法即可

如果需要对帮助节的内容进行权限控制，那么可以在插件释文中指定permission属性，其值是一个权限字符串，帮助节插件转化为渲染数组的逻辑在以下方法中实现：

\Drupal\help\Controller\HelpController::helpMain

 

 

模块帮助主页：

help模块向系统帮助主页提供了一个模块概览帮助节，在这个节中用户可以点击链接达到模块的帮助主页，模块帮助主页的内容是由其实现的help钩子提供的，如果模块没有实现help钩子将没有帮助主页，在模块概览帮助节中也不会出现到达链接，用于显示模块帮助主页的路由定义如下：

help.page:
  path: '/admin/help/{name}'
  defaults:
    _controller: '\Drupal\help\Controller\HelpController::helpPage'
    _title: 'Help'
  requirements:
    _permission: 'access administration pages'

注意：前文讲了块中的帮助信息也是由help钩子提供，该钩子的第一个参数名是路由名，但是在模块帮助主页调用help钩子时传递的是虚拟的路由名，并不真实存在于系统中，格式如下：

"help.page.模块名"

在help钩子中如果发现路由名是这个那么说明应该提供模块帮助主页的帮助信息。

 

补充：

1、官方标准推荐参考：

帮助消息推荐标准：

https://www.drupal.org/node/632280#description

界面文本推荐标准：

https://www.drupal.org/node/604342

2、帮助模块只提供了以上三种类型的帮助，模块或主题的描述帮助来自info文件，和帮助模块无关，表单等处的帮助内容也和帮助模块无关