Tour API in Drupal 8Drupalcamp Brighton 2016

Tassos Koutlas (@akoutlas) , 17. 06. 2016

Content● Who am I

● Tours in Drupal

● Creating a custom tour

● Other ways to provide help to users

Who am I?

Tassos KoutlasSenior Technical Consultant @ C&W

web projects / machine learning / image processing algorithms / administering IT systems / scrum master

Tours in Drupal

What are tours?

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.

Tours in contribA 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

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

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

Creating a tour

Anatomy of a tour [1/2]YAML properties:

- id

- module

- label

- routes

- langcode

- tips

Anatomy of a tour [2/2]Tips: core ships with text and image plugin types

- id

- plugin

- label

- body

- location

- weight

- attributes

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

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.

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.

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.

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.

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.

An exampledrupalcamp_tour.info.yml ./config/install/tour.tour.content-overview.yml

Advanced tour options

Extending tips● Tips types implement a

TipPluginInterface

● Through the API other plugin

types can be created

(youtube, soundcloud)

Other ways to provide help to users

Markdown● Always have a README file

● Add in version control

● Help onboard developers

● Help onboard users

● Credit yourself!

Read the docs● Git / Subversion / Mercurial

● Fully searchable

● Webhooks (build when

committing)

● Versioning (build from tags)

Beautify my docsA simple service to

convert text

between markdown,

html and drupal.

Thank you !

WEB www.cameronandwilding.com EMAIL info@cameronandwilding.com

TWITTER https://twitter.com/cameronwilding LINKEDIN https://www.linkedin.com/company/cameron-&-wilding/