你在这里

Drupal8中的向导API

原文链接Tour API in Drupal8

您可以通过将YAML文件添加到您的模块配置文件夹的方式来创建若干个向导团,从而让它们和Drupal8向导模块一起配合使用。

或者您也可以通过调用向导用户界面模块(Tour UI)来创建向导团。

论坛(模块)向导样例

让我们先来参考一个例子,这个例子在《为论坛模块编写向导集成》当中有提到。

YAML文档的命名

用于实现论坛的添加/编辑页面的YAML文件的命名类似于tour.tour.forum-container.yml,也就是说它遵循module.type.id.yml模式。

如果你想在你的模块当中为你的‘configure pants’(“配置裤”)表单提供一个建议,你可以把你的模块命名为tour.tour.configure-pants.yml。

向导YAML文档的内容

用来添加或编辑论坛页面的YAML文档内容如下:

id: forum-container
module: forum
label: Add or edit a forum container
langcode: en
uuid: dd06919e-9c54-49a8-b0e7-bbf7e03d0db7
routes:
  - route_name: forum.add_container
  - route_name: forum.add_forum
tips:
  introduction:
    id: introduction
    plugin: text
    label: Adding or editing a container
    body: This form can be used to edit an existing container or add a new container to your site.Containers are used to group forums together. For example if you ran a Drupal forum you might create a 'Support' container and include forums for 'Installing Drupal' and 'Getting started' inside the 'Support' Container
    weight: "1"
  container-name:
    id: container-name
    plugin: text
    label: Container name
    body: Enter a name to identify this container. Eg 'Support'
    weight: "2"
    attributes:
      data-id: edit-name
  container-description:
    id: container-description
    plugin: text
    label: Container description
    body: Give your container a description to help identify the purpose of the container and the types of forum it will contain. You can also use the container description to provide guidelines for other site administrators to help them decide which container a new forum might belong in.
    weight: "3"
    attributes:
      data-id: edit-description
  container-save:
    id: container-save
    plugin: text
    location: top
    label: Save
    body: When you have finished completing the form, click 'Save' to create the new container or save the changes to an existing container.
    weight: "6"
    attributes:
      data-id: edit-submit

YAML文档的相关属性

  • id:向导的ID号。
  • module:你的模块名(在我们的案例中叫“forum”)。
  • langcode:向导的语言。我们现在有配置架构,这样配置过的实体最终将能够被翻译。
  • label:向导的名称,在核心中不会用到它们,但是将被向导界面模块(正在积极开发中)所利用。
  • routes:一个用于活跃向导的路径数组。把它们与route_name和可选择的rout_params(也是一个数组)一起指定为一个数组。路径名可以在每一个模块的routing.yml文件中找到。
  • tips:一个用来构建向导,与提示插件配置有关的数组

提示插件

提示类型对核心插件系统产生影响并且实现了一个TipPluginInterface(注:提示插件接口)。核心插件系统拥有一个“文本”类型的插件,同时在测试的时候还用到了“图片”插件。实现了这个API,任何模块都可以创建一个新的插件。比如,你想在你的建议当中用到Youtube视频或者其他更为丰富的交互。只要实现了这个API,那么这(个功能)就特别容易实现。

插件配置

在论坛样例的YAML文档中,上述每一个建议的配置如下:

 

container-delete:
    id: container-delete
    plugin: text
    label: Delete
    body: Use this button to delete your container. You will be required to confirm you wish to delete the container before it is actually deleted.
    weight: "7"
    attributes:
      data-id: edit-delete

这个配置为论坛的编辑页面的删除按钮定义了一个建议,这些键都不言自明:

  • id:建议的ID号
  • plugin:插件类型(在核心中只有文本插件是可用的)
  • label:建议的头部,在建议中,它们被h3标签渲染
  • body:建议的主体,允许使用标记
  • location:箭头的位置
  • weight:在向导里面,提示按权重排列。
  • attributes:属性被传递给建议的呈现函数,但是有几个特别有意思的地方值得注意——控制建议(展现)的位置。
  • data-id:命名提示目标的dom元素的ID号。例如,在删除按钮的样例当中,它的目标元素ID号是“edit-delete”,无需在前面再加入#号,内部的joyride插件取得元素的ID并把它直接传递给(对应的)文档。getElementById()(返回的)就是一个ID字段,而不是一个jquery选择器。
  • data-class:如果你的目标元素没有ID号,你可以用data-class来标记它。注意它的前面不需要用到句点(即英文的句号)。Joyride插件会把它解析成一个jquery选择器,因此你可以使用更复杂的选择器规则。提供一个以class名开头没有句点的选择器。例如
action-links a[href=”/admin/structure/forum/add/forum”]

它会被joyride插件解析为“.action-links a[href=”/admin/structure/forum/add/forum”]”。

  • 如果你同时省略了.data-id和.data-class,那么建议将以模态化的方式显示,而不是被定位到某个元素,这对于一般的单个页面/表格的介绍等是非常有用的。

样式和标准

请确保你对向导团和UI文本的一般接口模式和样式指南有所了解。

编写/开发向导团

如果你正在编写一个向导,你需要遵循以下步骤,以查看向导在网站中出现的实际位置。

如果你只是测试一个向导补丁,请确认您在应用补丁后启用了对应的模块。

  • 创建你的向导yml文件,并命名成tour.tour.[tour-name].yml。例如:
tour.tour.language.yml
  • 如果你想使用你的样例yml文件,试着用以下方式启动
core/modules/view_ui/config/tour.tour.views-ui.yml

复制yml文件到网站的配置目录下的活跃和暂存的子目录,比如:

sites/default/files/config_zAYjIjYlwIIJYm5UOQscPNMnQQDeWd96fKV9ThwO9XU/staging
sites/default/files/config_zAYjIjYlwIIJYm5UOQscPNMnQQDeWd96fKV9ThwO9XU/active

(点此查看)更过关于Drupal8管理配置

  • 进入网站的后台管理部分,进入到admin/config/development/configuration页面,然后点击“导入所有”。
  • 把下面这行代码加入到你的settings.php文件
$settings['cache']['config'] = 'cache.backend.memory';

它将禁用配置文件的缓存(不推荐在生产网站上使用)。这样,你就做了一些变化,重新加载网页来查看这些变化(否则每一次你都要清除缓存,那是一件相当乏味的事情)。

  • 你每一次确实需要从向导最开始的地方开始,直到补丁程序被加载进去。

#1942576: Tour tips to be able to link to other pages and start tour's automatically.

  • 一旦向导准备活动,你需要将该文件复制到正确的位置。例如,一个语言模块的向导(文件)不会存放在
core/modules/language/config

然后像往常一样创建你的补丁程序。

获取更多更高级的功能

如果你发现你需要做一些比显示文本提示更高级的(功能),例如,你需要一些额外的参数或逻辑,你将需要通过调用TipPluginInterface(接口)来创建一个提示插件。以tour_test模块为例,它包含了一个代替文本来展示图片的图片插件,自带了一个“url”配置键,而不是“主体”。

此页面是从这篇博文改编

你可以在YouTube上观看完整的过程