Tour API

Last updated April 12, 2013. Created by larowlan on March 5, 2013.
Edited by LeeHunter, batigolix, nick_schuch. Log in to edit this page.

You can create a user interface tour for your Drupal 8 modules by adding a YAML document to your module's config folder.

Forum tour example

Let's consider an example from the 'Write tour integration for Forum module' issue.

YAML document name

The YAML for the add/edit forum page is named tour.tour.forum-container.yml, which follows the module.type.id.yml pattern.

If you wanted to provide a tip for the 'configure pants' form in your module, you would name your file tour.tour.configure-pants.yml.

Content Tour YAML document

The YAML document for adding or editing a forum page looks like this:

id: forum-container
module: forum
label: Add or edit a forum container
langcode: en
paths:
  - admin/structure/forum/add/container
  - admin/structure/forum/edit/container/*
tips:
  introduction:
    id: introduction
    plugin: text
    label: Adding or editing a container
    body: <p>This form can be used to edit an existing container or add a new container to your site.</p><p>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</p>
    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-parent:
    id: container-parent
    plugin: text
    label: Container parent
    body: If you wish to nest your containers, select the parent container here. If you don't require nesting, choose &lt;root&gt;.
    weight: "4"
    attributes:
      data-id: edit-parent-0
  container-weight:
    id: container-weight
    plugin: text
    label: Container weight
    body: <p>Use the weight field to alter the order in which containers are displayed. Use a lower number to move a container to the top of the list.</p><p>E.g. if you have two containers, one with weight of -5 and one with weight of 5, the one with the -5 weight will be displayed first.</p><p>Items with the same weight are sorted alphabetically.</p>
    weight: "5"
    attributes:
      data-id: edit-weight
  container-save:
    id: container-save
    plugin: text
    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
  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

Properties YAML document

The YAML document consists of the following key properties

id - The ID of the tour
module - Currently in RTBC on issue http://drupal.org/node/1921132
langcode - The language of the tour. We have configuration schemas now so config entities will eventually be translatable.
label - A name for the tour - these aren't used in core but will be leveraged by the Tour UI module which is under active development (read more below).
paths - An array of paths for which the tour is active. Specify these the same way you would specify block visibility, for example, you can use * for wildcards
tips - An array of tip plugin configuration to comprise the tour

Tip plugins

Tip types leverage the core plugin system and implement a TipPluginInterface. Core ships with a 'text' plugin and there is an 'image' plugin used in tests. Any module can create a new plugin that implements the API. For example you might want YouTube videos or other rich interactions in your tip. This can easily be achieved via the API.

The plugin configuration

In the example of the forum YAML document, above each tip the configuration is presented as follows:

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

This configuration defines a tip for the Delete button on the forum edit page. The keys are fairly self-explanatory -

id is the tip ID
plugin is the plugin type (only text is available in core)
label - is the heading for the tip. This is themed as h3 in the tip
body - the body of the tip. Markup is allowed
weight - tips within a tour are ordered by weight
attributes - these attributes are passed through to the render tip but there are a few of particular interest that control the placement of the tip:
- data-id - nominates the ID of the dom element the tip targets. For example, in the case of the Delete button it targets the element with the ID 'edit-delete'. There is no need to include the leading #, internally the joyride plugin fetches the data-id attribute and passes it directly to document.getElementById() so this is a straight ID field, not a jQuery selector
- data-class - if the element you are targeting does not have an ID, you can use data-class to target it. Note this does not include the leading period (.). This is parsed by the Joyride plugin into a jQuery selector, so you can use more complex selection rules, provided the selector starts with a classname without the leading period (.). For example,
  action-links a[href="/admin/structure/forum/add/forum"]
  which would be parsed by Joyride into '.action-links a[href="/admin/structure/forum/add/forum"]'
- If you omit both the .data-id and .data-class - the tip will be shown as modal instead of being targeted to an element. This is useful for a general introduction to the page/form etc.

Loading Tour YAML documents

The Tour YAML document will be loaded when you enable the module for the first time.

If you create a tour for an already enabled module, you need to uninstall and re-enable this module for the YAML document to get loaded.

To update the tour, stage the YAML document and synchronize the configuration.

Getting more advanced

If you find you need to do something more advanced than show a text tip, for example, you need some additional parameters or logic, you will need to create a tip plugin by implementing the TipPluginInterface. See the tour_test module for an example - it contains an image plugin that renders an image instead of text, taking a 'url' configuration key instead of a body.

This page was adapted from this blog post.