1.
Tour API in Drupal 8
Drupalcamp Brighton 2016
Tassos Koutlas (@akoutlas) , 17. 06. 2016

2.
Content
● Who am I
● Tours in Drupal
● Creating a custom tour
● Other ways to provide help to users

3.
Who am I?

4.
Tassos Koutlas
Senior Technical Consultant @
C&W
web projects / machine learning / image
processing algorithms / administering IT
systems / scrum master

5.
Tours in Drupal

6.
What are tours?

7.
Tours in core
● Included with Drupal 8
● Based on joyride jQuery plugin
● Configuration based, translatable
● YAML
When you have a web application
which requires some getting used to
from your users.

8.
Tours in contrib
A few modules try to leverage tours
in core and build new functionality to
make it easier for other to contribute
tours:
● Tour builder
● Tour UI

9.
Why tours?
● Alternative to providing extensive documentation
● Bundled with your Drupal build and version controlled
● Encourages self-paced learning
● Encourages splitting larger tasks into small chunks of
knowledge
● Enables people to visit the resources multiple times
● Because Drupal 8 is so cool

10.
Primary use cases
● To draw the user's attention to critical components of the
interface, especially those elements that might not be
immediately obvious
● To guide the user through a workflow

11.
Creating a tour

12.
Anatomy of a tour [1/2]
YAML properties:
- id
- module
- label
- routes
- langcode
- tips

13.
Anatomy of a tour [2/2]
Tips: core ships with text
and image plugin types
- id
- plugin
- label
- body
- location
- weight
- attributes

14.
General principles [1/2]
General principles for tours as they are captured within the context
of Drupal user interface standards:
● Tours are a complement (not a substitute) for good interface
design.
● Tour text should follow the Drupal style guide for interface text.
● The tour should start and end in a logical place

15.
General principles [2/2]
● If the tour is intended to illustrate a workflow, it should stay
focused on completion of a single task.
● Avoid providing tangential information.
● If the tour is intended to highlight the UI, it may not be
necessary or desirable to include every option for every widget.
● Keep tip content short, preferably 1 to 2 sentences.
Provide examples to give a deeper understanding of tips
context.

16.
Tour text standards [1/2]
● Follow the style guidelines for Interface text
● Keep it simple.
● Use -ing verb mode for the tip label.
○ Viewing log messages instead of View log messages.

17.
Tour text standards [1/3]
● Start the tour with a general model (not linked to any element)
for a general introduction.
● Imagine the most basic task possible and write to that. Don’t try
to cover every use case.
● Remember that your audience is a new user, so assume no
Drupal knowledge.

18.
Tour text standards [2/3]
● If possible, keep the tour to fewer than 8 tips.
● If possible, keep to a single sentence per tip of less than 25
words.
● A tour tip is not UI text. Don’t duplicate the UI text.
● A tour is not documented. You can link to documentation at the
end if you think it’s useful.
● Doesn't explain stock Drupal page elements such as
breadcrumbs or pagers.

19.
Tour text standards [3/3]
● Use links where useful and ensure they will never break.
● Avoid complex tour tip selectors such as :first-child or :nth-child
(n) as these at present cannot be tested via simpletest. Instead,
add classes into the body to make the selectors easier to
understand.

20.
An example
drupalcamp_tour.info.yml ./config/install/tour.tour.content-overview.yml

21.
Advanced tour options

22.
Extending tips
● Tips types implement a
TipPluginInterface
● Through the API other plugin
types can be created
(youtube, soundcloud)

23.
Other ways to provide
help to users

24.
Markdown
● Always have a README file
● Add in version control
● Help onboard developers
● Help onboard users
● Credit yourself!

25.
Read the docs
● Git / Subversion / Mercurial
● Fully searchable
● Webhooks (build when
committing)
● Versioning (build from tags)

26.
Beautify my docs
A simple service to
convert text
between markdown,
html and drupal.

27.
Thank you !

28.
WEB www.cameronandwilding.com
EMAIL info@cameronandwilding.com
TWITTER https://twitter.com/cameronwilding
LINKEDIN https://www.linkedin.com/company/cameron-&-wilding/