tassos koutlas - tour api in drupal 8
TRANSCRIPT
![Page 1: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/1.jpg)
Tour API in Drupal 8Drupalcamp Brighton 2016
Tassos Koutlas (@akoutlas) , 17. 06. 2016
![Page 2: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/2.jpg)
Content● Who am I
● Tours in Drupal
● Creating a custom tour
● Other ways to provide help to users
![Page 3: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/3.jpg)
Who am I?
![Page 4: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/4.jpg)
Tassos KoutlasSenior Technical Consultant @ C&W
web projects / machine learning / image processing algorithms / administering IT systems / scrum master
![Page 5: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/5.jpg)
Tours in Drupal
![Page 6: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/6.jpg)
What are tours?
![Page 7: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/7.jpg)
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.
![Page 8: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/8.jpg)
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
![Page 9: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/9.jpg)
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
![Page 10: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/10.jpg)
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
![Page 11: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/11.jpg)
Creating a tour
![Page 12: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/12.jpg)
Anatomy of a tour [1/2]YAML properties:
- id
- module
- label
- routes
- langcode
- tips
![Page 13: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/13.jpg)
Anatomy of a tour [2/2]Tips: core ships with text and image plugin types
- id
- plugin
- label
- body
- location
- weight
- attributes
![Page 14: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/14.jpg)
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
![Page 15: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/15.jpg)
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.
![Page 16: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/16.jpg)
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.
![Page 17: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/17.jpg)
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.
![Page 18: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/18.jpg)
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.
![Page 19: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/19.jpg)
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.
![Page 20: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/20.jpg)
An exampledrupalcamp_tour.info.yml ./config/install/tour.tour.content-overview.yml
![Page 21: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/21.jpg)
![Page 22: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/22.jpg)
![Page 23: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/23.jpg)
![Page 24: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/24.jpg)
![Page 25: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/25.jpg)
Advanced tour options
![Page 26: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/26.jpg)
Extending tips● Tips types implement a
TipPluginInterface
● Through the API other plugin
types can be created
(youtube, soundcloud)
![Page 27: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/27.jpg)
Other ways to provide help to users
![Page 28: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/28.jpg)
Markdown● Always have a README file
● Add in version control
● Help onboard developers
● Help onboard users
● Credit yourself!
![Page 29: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/29.jpg)
Read the docs● Git / Subversion / Mercurial
● Fully searchable
● Webhooks (build when
committing)
● Versioning (build from tags)
![Page 30: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/30.jpg)
Beautify my docsA simple service to
convert text
between markdown,
html and drupal.
![Page 31: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/31.jpg)
Thank you !
![Page 32: Tassos Koutlas - Tour API in Drupal 8](https://reader030.vdocuments.net/reader030/viewer/2022020213/5881d62d1a28ab331a8b66b5/html5/thumbnails/32.jpg)
WEB www.cameronandwilding.com EMAIL [email protected]
TWITTER https://twitter.com/cameronwilding LINKEDIN https://www.linkedin.com/company/cameron-&-wilding/