Write tour integration for the first page after install showing extend and other things

This is definitely almost a "postponed" we should have a strategy for tour module, randomly adding tours is not what we should do - its likely we will start trowing usability problems under the rug.

It would be really nice if we had a tour for brand new users and users who are new to Drupal 8, showing them what's changed. I'm not sure at what point we identify they are new to Drupal 8 only.

As a first step, I've made this screen capture of a new D8 site and put squares around everything that could possibly be included. Since there are too many elements for one tour and many of them are relatively self-explanatory, I've used thick green boxes to highlight the elements that I'm guessing would be good candidates for a tour. My thinking is that we should focus on those areas where the user says "What is this widget?" or "How do I change this content/structure/colour etc?"

To mark up the screen capture I'm using Adobe Acrobat and enabled the file so that others can mark it up and add comments. I realize that a PDF is not ideal for many reasons, but for the moment it seems like a practical way for myself to add editable text, comments etc in a graphical setting. If you have Adobe Reader, you should be able to edit the markup and add comments by visiting the file in my public Dropbox folder https://www.dropbox.com/sh/in81k4tgg73woba/ZuHc_eufwS/Drupal However, it would generally be more useful to post comments here in the queue.

As I work on this some more over the next couple of days, I'll post new versions but in the interim I'd also like to get feedback on whether I'm on the right track (e.g. addressing the right elements on the page) and any other insights you might have into things like the sequence of the tour etc.

One thing I'm curious about re Tours is how they are displayed. Specifically, how does Drupal know whether the user wants to see the tour or not: does it only display one time or does it keep popping up until the user takes some action to stop it being displayed (and if that's the case, is there any way for the user to bring it back again).

I completely agree with the proposed elements.

In regards to how the tour elements are displayed....

We have a permission called "View tour tips". Users who have this permission will be provided a "Tour" item in the right of the toolbar. This toggles tips on and off. By default the tips are not shown. However, for something like "This initial experience" we have the following being worked on that will enable the tour to be fired right away on page load http://drupal.org/node/1942576 based on a query string. We just need to provide the pages that we want this tour to be displayed on. I imagine this would just be after first install or just the front page?

A good example of this can be found on the views edit page or a screencast can be found here: http://previousnext.com.au/blog/tour-module-part-1-journey-adding-drupal...

Here's a first crack at the tour. In trying to give it a logical flow I played with a few sequences, but in the end went for a straightforward top down/left to right flow. Aside from being (I believe) fairly predictable to the user it has the advantage of subtly grouping the two admin UI widgets (items 1 and 2) and then 3 to 7 are all things you can change on the actual site. But it might actually might make sense to put those two widgets at the end of the tour since they're probably not the priority for a new user and they're off in a corner by themselves anyway. I'm not sure if you can do bold text in a tour but if you can, it would be helpful as a way of differentiating text that is actually the title of a UI item.

I was also wondering whether it needs an introductory tip (e.g. Welcome to your new site. This brief tour will help you understand your home page and how to start making changes.) and possibly an ending tip (e.g. For more information, see the Drupal documentation).

1. Click this button to show or hide the configuration buttons that are available for each page element.
2. This button moves the Administration toolbar between the top and side of the page.
3. To change the logo, click Appearance and select the Settings tab.
4. To change the site name, click Configuration > Site Information.
5. The Home tab is actually a menu item. To add more items, click Structure > Menus and select Main Navigation.
6. This message appears when there is no content. To change the settings, click Structure > Views > Frontpage.
7. You can create a new block and specify where it goes. Any kind of content can be placed in a block including menu items, lists of content (from Views) etc.

This looks pretty awesome already. I would suggest we get a version of this in to put it in people's faces so we can refine in a second step. I think two or three reviews should suffice and then we can set this RTBC, IMHO.

A couple suggestions:

• I would add another item for the "Add content" link as 6. Suggestion:
  

  By default Drupal allows to create articles and basic pages as content. Articles will be listed on the front page by default.

  . 7. Would then still be the "Add custom block" link.

• I would make 7. more explicit. Also I would not reference "Views" just yet, as that concept has not really been introduced. Also the word 'content' is redundant. Lastly, I think it makes more sense to place entire menus in blocks instead of menu links. Suggestion:
  

  You can create a new block and specify where it should be displayed, for example in the header, the sidebar or in the footer of the page. Any kind of content can be placed in a block including menu items, lists of articles, comments, etc.

I would make 6. (which I would put at 8.) more explicit. Suggestion:

This message appears when you have not created any articles. To change the settings of the content listing, click Structure > Views > Frontpage.

Woooo, this is waaay to much. It should be a tour of the most important things, not of everything. Doing this much is the best way to get people to skip it.

The most important thing, I have found people struggle with when they land on Drupal is knowing what is in structure, extend and configuration. All the other items tend to be pretty self-explanatory.

I'm surprised that the Structure, Extend and Configuration menu items would be things that people have problems with.

For myself, if I didn't already know something about how Drupal worked I would never have guessed that the "Home" tab was actually a menu item or that the "Welcome to ..." text was something generated by Views.

Has anyone done tests of the D8 interface yet? If so, are the results available online?

@LeeHunter We actually have done quite a number of tests, http://drupal.org/node/1166656 (Drupal 7, but really just after release so still close to D8), http://drupal.org/node/1427940, http://groups.drupal.org/node/277458 and http://groups.drupal.org/node/260203. Probally a few more that I am missing.

I think one of the things you are overestimating is the depth that is needed, just after install we want people to understand the bare fundamentals. Showing them how Vies generates the welcome to.. part is very advanced. What people really want to know is where things can be found, what navigational "hubs" exist.

How about this then:

1. Configure content types, menus, blocks, taxonomies, etc.
2. Change the functionality of your site by enabling, disabling or updating modules
3. Configure site information and other options such as language, region, file locations etc.

I noticed that when I installed Drupal 8 just now, this menu didn't actually display until I clicked Menu. Do we need another item for the Menu button, something like "Click here to see the Administration menu"?

@LeeHunter that is a bug, and yes I think what you are describing there should be a good first pointer. The tour can't move through pages, can it?

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

One issue I can see is that the toolbars submenu has multiple states eg. Opened, closed, below the toolbar and to the left of the page.

Im not sure if we can account for all these states.

Updated issue summary, added link to meta

Some technical remarks.

- what module provides this front page tour? The current sketch is about the toolbar. So the patch do the same.
- What if more then one module claims the same path?
- The z-index for the tour is was lower then that of the tour.
- On small screen the tour cannot point to the correct element

I forgot the reply to #15 #16 and #18

+++ b/core/modules/toolbar/config/tour.tour.toolbar.yml
@@ -0,0 +1,54 @@
+    body: '<p>You can toggle this Menu button.</p><p>Please make sure it is open now.</p>'

Step contains instruction to open the menu. What more can we do?

What is the 'postponed' status mentioned in #3?

Should we rename this issues title into something like 'toolbar tour on frontpage'?

+++ b/core/modules/toolbar/config/tour.tour.toolbar.yml
@@ -0,0 +1,54 @@
+id: language
+module: language

This is not about language module.

+++ b/core/modules/toolbar/config/tour.tour.toolbar.yml
@@ -0,0 +1,54 @@
+    plugin: text
+    label: Menu
+    body: '<p>Configure content types, menus, blocks, taxonomies, etc.</p>'

Should have different titles. Attached patch fixes this.

I split off #19 (z-index) to #2021361: tour should be in front of toolbar (z-index)

Updated issue summary.

Perhaps the initial tour should also introduce the user to how Drupal conceives of the page structure.

See for example #1164702: “Block” has no meaning. (New users challenged by use of the term 'block')

There could be a tip that says something simple like "This is a block. You can configure it in the Structure settings."

Attached is a yml file that I renamed to .txt extension.

The approach is to introduce them to the toolbar as well as the major parts of their home page. I plan to have a colleague review the text, so feel free to concentrate on the section labels and the flow for now; we can wordsmith the contents later. Am I missing anything?

@lisarex, any chance of a screencast for ease of review?

Screencast: http://screencast.com/t/WRWGyCK8usC

Attached is a patch (thanks to xjm to reminded me I needed to to git add first ;)

+++ b/core/modules/toolbar/config/tour.tour.toolbar.ymlundefined
@@ -0,0 +1,126 @@
+    body: '<p>Click the Menu button to explore the administrative menu.</p><p>Then click Next.</p>'

Pretty sure there are event listeners in the tour library that trigger before moving to the next tip, we could use that to make sure the menu was open when next was clicked on this item. Beyond my JavaScript skills though :)

+++ b/core/modules/toolbar/config/tour.tour.toolbar.ymlundefined
@@ -0,0 +1,126 @@
+    body: '<p>Toggle the edit icon to show what parts of the page are directly editable. When the "show fedit" is off, you can hover over the area and see the edit icon.</p>'

typo

Do you think it is worth having a 'Continue this tour' modal tooltip at the end that lists other tours?
I think this tour should live in core/profiles/standard/config instead of toolbar.
It is referring to items (eg the search block) that are only available in standard.
This also allows other distros to ship their own front page tour and have toolbar enabled.
Thoughts?

Truly awesome to see this all coming into place!

Can tip 12 (edit) target the icon in the toolbar?

+++ b/core/modules/toolbar/config/tour.tour.toolbar.ymlundefined
@@ -0,0 +1,126 @@
+      #data-class: 'contextual-toolbar-tab'

you want data-class: 'contextual-toolbar-tab .icon-edit' here to target it

The z-index of the tips needs to be higher than the element revealed by the next tip. So that for example the 3rd tip does not go under the menu as shown at around 0:08 in that screencast.

@klonos see #2021361: tour should be in front of toolbar (z-index)

Thanx mate ;)

Tour needs tests since we now have #2028535

+++ b/core/modules/toolbar/config/tour.tour.toolbar.yml
@@ -0,0 +1,126 @@
+id: frontpage

id must match file name id. In this case "id: toolbar" or change the file name to tour.tour.frontpage.yml"

This problem only arise when trying to edit a tour through Tour UI: #2072899: A mismatch between file name and tour ID fails to EDIT the file.

I suspect a bug in core tour module.

@nick_schuch and I reviewed the current toolbar tour patch provided by lisarex and agreed that is was far too detailed and too long for an initial user experience.

I'm going to investigate a slightly different approach that covers the main features in 5 or 6 steps, with each step linking to new tours of that feature.

Thanks @xtfer!

Some details for the query string can be found here (for the original work, it's also in the changelog):

https://drupal.org/node/1942576

This one is the for the token support:

https://drupal.org/node/2019469

I think the token [site:url] might be enough.

Currently partly blocked by #2073891: Customise tour loading by URL.

Updated issue summary.

Removes #2021361: tour should be in front of toolbar (z-index) from TODO (closed)

...we do not remove issues from the todo lists unless they prove to be irrelevant to the issue. We already have issue status colors to indicate that issues are done or not.

...never mind me. #2021361: tour should be in front of toolbar (z-index) was actually closed as "cannot reproduce".

Had to fix a lot of the data-id's, replace paths with routes, made a few text changes, deleted some broken tour elements, and otherwise tested this to make sure it was working. Could still do with a few new inclusions, but is a good template for going forwards with.

tagging and removing old assignee.

Re-rolled this patch, changes include:

• Remove quotes in tour tips and replace with em tags
• Prefix all tour tips with toolbar- for consitancy
• The manage tour tip now points at the correct menu item
• Add a link to the block layout page
• Added tests based on TourTestBasic, this proved to be quite challenging as the menu links in the tour required a lot fo modules and permissions to be setup, which took a long while to get right. I still cannot figure out how to place the search block in the sidebar, so 1 test continues to elude me (help please!). Marking as needs review just to verify there is actually 1 failing test and it's not just my dev box.

Running the tests:

sudo -u www-data php core/scripts/run-tests.sh --verbose --url http://d8.localhost/ --file core/modules/toolbar/lib/Drupal/toolbar/Tests/Tour/FrontpageTourTest.php

Test results:

Drupal test run
---------------

Tests to be run:
  - Drupal\toolbar\Tests\Tour\FrontpageTourTest

Test run started:
  Sunday, April 6, 2014 - 17:05

Test summary
------------

Drupal\toolbar\Tests\Tour\FrontpageTourTest                   27 passes   2 fails                  5 messages

Test run duration: 1 min 38 sec

Detailed test results
---------------------


---- Drupal\toolbar\Tests\Tour\FrontpageTourTest ----


Status    Group      Filename          Line Function                            
--------------------------------------------------------------------------------
Pass      Other      TourTestBasic.php   48 Drupal\tour\Tests\TourTestBasic->se
    Enabled modules: block, help, entity, menu, node, search, shortcut, tour,
    toolbar, views
Pass      Role       TourTestBasic.php   64 Drupal\tour\Tests\TourTestBasic->se
    Created role ID 'n5j5rc0d' with name '\'| 1?o!{'.
Pass      Role       TourTestBasic.php   64 Drupal\tour\Tests\TourTestBasic->se
    Created permissions: access administration pages, administer blocks, access
    content, access content overview, access site reports, access toolbar,
    access tour, administer modules, administer search, administer site
    configuration, administer themes, administer users, search content, view the
    administration theme
Pass      User login TourTestBasic.php   64 Drupal\tour\Tests\TourTestBasic->se
    User created with name cQ2xiw03 and pass BihZsMdiUL
Pass      Browser    TourTestBasic.php   65 Drupal\tour\Tests\TourTestBasic->se
    GET http://d8.localhost/user returned 200 (3.81 KB).
Pass      Browser    TourTestBasic.php   65 Drupal\tour\Tests\TourTestBasic->se
    Valid HTML found on "http://d8.localhost/user"
Pass      Browser    TourTestBasic.php   65 Drupal\tour\Tests\TourTestBasic->se
    GET http://d8.localhost/user/2 returned 200 (11.71 KB).
Pass      Browser    TourTestBasic.php   65 Drupal\tour\Tests\TourTestBasic->se
    Valid HTML found on "http://d8.localhost/user/2"
Pass      User login TourTestBasic.php   65 Drupal\tour\Tests\TourTestBasic->se
    User cQ2xiw03 successfully logged in.
Pass      Browser    FrontpageTourTest   68 Drupal\toolbar\Tests\Tour\Frontpage
    GET http://d8.localhost/admin/structure/block returned 200 (28.4 KB).
Pass      Browser    FrontpageTourTest   68 Drupal\toolbar\Tests\Tour\Frontpage
    Valid HTML found on "http://d8.localhost/admin/structure/block"
Pass      Browser    FrontpageTourTest   70 Drupal\toolbar\Tests\Tour\Frontpage
    GET http://d8.localhost/node returned 200 (18.92 KB).
Pass      Browser    FrontpageTourTest   70 Drupal\toolbar\Tests\Tour\Frontpage
    Valid HTML found on "http://d8.localhost/node"
Fail      Other      FrontpageTourTest   71 Drupal\toolbar\Tests\Tour\Frontpage
    Block title was found.
Pass      Browser    TourTestBasic.php   73 Drupal\tour\Tests\TourTestBasic->te
    GET http://d8.localhost/node returned 200 (18.92 KB).
Pass      Browser    TourTestBasic.php   73 Drupal\tour\Tests\TourTestBasic->te
    Valid HTML found on "http://d8.localhost/node"
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with id #toolbar-bar
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with class .toolbar-icon-menu
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with id
    #toolbar-link-admin-content
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with id
    #toolbar-link-admin-structure
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with id
    #toolbar-link-admin-appearance
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with id
    #toolbar-link-admin-modules
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with id
    #toolbar-link-admin-config
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with id
    #toolbar-link-admin-people
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with id
    #toolbar-link-admin-reports
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with id
    #toolbar-link-admin-help
Fail      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with class .search-block-form
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with class .view-frontpage
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Total 13 Tips tested of which 1 modal(s).

This one seems like a good thing to do, but postponed on #1921152-109: META: Start providing tour tips for other core modules. for now.

#nashville2018 Reopening as part of the core sprints in Nashville DrupalCon

- Normalising the title "Write tour integration"
- Added dependency section to tour yml
- moved tour into toolbarconfig/optional dir.
- Only 5/13 tips are shown on my frontpage.

Let's swap parent relation

And now with a none empty patch file.

- Added dependency section to tour yml
- moved tour into toolbarconfig/optional dir.
- Only 5/13 tips are shown on my frontpage.

Rerolling the patch for 9.1.x
Fixing failed test cases.
And adding a proper test method for frontend tour page.
All the 13 tips are now visible on the frontpage.

Adding @group annotation to test.

Patch or MR doesn't apply anymore
The last patch or MR doesn't apply to the target branch, please reroll the code so that it can be reviewed by the automated testbot.

Rerolled and updated for 10.1.x

Adding a tests-only patch for the FrontPageTourTest file.

Believe existing test is covered
But NW for the nightwatch failures.

Believe the tour config was outdated so updated.

Fixed build error

This extension is being deprecated, see #3336033: [Meta] Tasks to deprecate Tour module. It will be removed from core and moved to a contrib project, #3376099: [11.x] [Meta] Tasks to remove Tour.

This is now Postponed. The status is set according to two policies. The Remove a core extension and move it to a contributed project and the Extensions approved for removal policies.

Definitely want to include