Write tour integration for Dblog page

Tour needs tests since we now have #2028535

Initial run at the tour. Im uploading this patch as Im not sure if I will have time tonight to finish the tests.

Note: I grabbed the help text from the module help but this may need to be reviewed.

Also I was having an issue being able to target the table with id admin-dblog. Whenever I used it with data-id it just wouldnt work.

Initial run at the tour. Im uploading this patch as Im not sure if I will have time tonight to finish the tests.

Note: I grabbed the help text from the module help but this may need to be reviewed.

Also I was having an issue being able to target the table with id admin-dblog. Whenever I used it with data-id it just wouldnt work.

Added another attempt at a dblog tour.

We still need some test coverage before moving to needs review. I don't mind writing the tests.

This patch:
- Adds test coverage.
- Updates path to route.

Hurray! I managed to write a tour (a year has passed since my first attempt ;)

Sorry that I could not create a patch, but the patch from #10 did not apply on my out-of-date D8 version. So that is why I attach just the tour itself.

I completely re-wrote the tour from #10 based on hook_help for the dblog module & info on d.o and other stuff scraped from the internets.

Changed

routes:
  - route_name: dblog.overview 

to

paths:
  - 'admin/reports/dblog'

in order to get the tour working in my D8 site, but I know I shouldnt do that in a real patch

I would like to have this reviewed and use the feedback to improve the guide lines at https://drupal.org/developing/api/tour & https://drupal.org/node/2040099 so that it will become easier to write and review other tours.

What I would like to find out are things are:
- whether to start with an About and a More information
- wording of tip label
- does it makes sense to explain stock items like pagers
- use of links
- use of html in tip body
- standard for tip ID naming
- how to refer to page elements (e.g. say "click this button" or "click the Submit button")
- if it is okay to target variable information in a page like e.g. data-class: 'admin-dblog tr:first-child td:nth-child(1)'

Fire at will, and let's collect feedback so that it will become easier to write and review tours.

p.s. Could someone provide me the link for the issue for multi page tours?

Hi batigolix!

Here is the link to the multipage https://drupal.org/node/1942576.

- whether to start with an About and a More information

I think that is a good idea. Or maybe we can split it up into 2 tips. The first being the "About" or "Overview" and the last tip of the tour being "More information". We could also use the "Modal" for these, which is a tips default state if no selectors are given.

- wording of tip label

I think we should keep it to a few words. Which you have done! eg. "Filtering messages".

- does it makes sense to explain stock items like pagers

I don't think we need to descibe the pagers. But am open to either.

- use of links

All for it! I think as long as the resource is a stable drupal.org (or similiar) page lets do it.

- use of html in tip body

Encouraged, we can do things like lists and bold certain words.

- standard for tip ID naming

I like the way you have done it, which is very similiar to how I have approached it as well. Prefixed with the module name and incorporates the label name.

- how to refer to page elements (e.g. say "click this button" or "click the Submit button")

I think it comes down to context. If the tip was pointing to the button than "this" would be sufficient. But if it were a part of another tip then I would go with "click the Submit button".

- if it is okay to target variable information in a page like e.g. data-class: 'admin-dblog tr:first-child td:nth-child(1)'

Yep, but we have to keep in mind if the selector is not on the page then the tip will not display.

i updated the guidelines a bit: https://drupal.org/node/2040099

OK, had a stab at updating this.

Changes since the last patch:

• Removed the tip on Drupal pagers, I thought this does not makes any sense to explain within the context of DbLog, it also is fragile as it relies on there being at least 2 pages of items for it to show.
• Removed the hardcoded paths in the last tip, and converted it to dynamic paths based on routes with a hook_tour_tips_alter(), I am unsure if this is the best way to approach this, so I am open to better ways to solve this.
• Added unit tests based on TourTestBasic, which include the creation of a sample log message to ensure everything works. I have to alter the CSS selector used on the tour tips, as the PHPUnit library that is used does not understand either :first-child or :nth-child(), as I found after reading the source. I also had to add a class to the message table cell in order to select it.
• Made the tour tips conditional on the help module, so no link to the help module is rendered if there is no help module installed.

Command to run the tests:

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

And results:

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

Tests to be run:
  - Drupal\dblog\Tests\Tour\DbLogTourTest

Test run started:
  Sunday, April 6, 2014 - 14:45

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

Drupal\dblog\Tests\Tour\DbLogTourTest                         17 passes                            3 messages

Test run duration: 53 sec

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


---- Drupal\dblog\Tests\Tour\DbLogTourTest ----


Status    Group      Filename          Line Function                            
--------------------------------------------------------------------------------
Pass      Other      TourTestBasic.php   48 Drupal\tour\Tests\TourTestBasic->se
    Enabled modules: tour, dblog, help
Pass      Role       TourTestBasic.php   64 Drupal\tour\Tests\TourTestBasic->se
    Created role ID 'xp6ea8tc' with name 'E[AS1Pt7'.
Pass      Role       TourTestBasic.php   64 Drupal\tour\Tests\TourTestBasic->se
    Created permissions: access site reports, access tour, view the
    administration theme
Pass      User login TourTestBasic.php   64 Drupal\tour\Tests\TourTestBasic->se
    User created with name wqosA03D and pass rTZXdGpfPW
Pass      Browser    TourTestBasic.php   65 Drupal\tour\Tests\TourTestBasic->se
    GET http://d8.localhost/user returned 200 (3.7 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 (3.98 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 wqosA03D successfully logged in.
Pass      Browser    TourTestBasic.php   73 Drupal\tour\Tests\TourTestBasic->te
    GET http://d8.localhost/admin/reports/dblog returned 200 (13.85 KB).
Pass      Browser    TourTestBasic.php   73 Drupal\tour\Tests\TourTestBasic->te
    Valid HTML found on "http://d8.localhost/admin/reports/dblog"
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with class .dblog-filter-form
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with class
    .dblog-clear-log-form
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with class .admin-dblog th
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with class .admin-dblog tbody
    > tr td.icon
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Found corresponding page element for tour tip with class .admin-dblog tbody
    > tr td.message
Pass      Other      TourTestBasic.php   74 Drupal\tour\Tests\TourTestBasic->te
    Total 7 Tips tested of which 2 modal(s).

Well at least the error message was helpful, try this.

I applied the patch in #16. After copying the tour.tour.dblog.yml file to my site config staging directory, synchronizing, and clearing the cache, the tour behaved as expected on the recent log message page.

Will users need to manually add these tours to their configuration though? I'm just curious what the intention is.

More chasing HEAD changes:

• $_SERVER['HTTP_REFERER'] replaced with \Drupal::request()->server->get('HTTP_REFERER')
• tour YAML moved into the config/install dir (no changes)

Tests pass locally now.

Whoops, added additional file. Re-uploading patch (interdiff is stil the same).

Assigning to myself to re-roll

Re-rolled patch, changes since last one

• Moved test file into the new PSR4 Tests directory
• Convert the demo log message into the new logger framework
• Use the built in token for site name (and save a bit of code)

Passes all tests with:
sudo -u www-data php core/scripts/run-tests.sh --verbose --url http://d8.localhost/ --file core/modules/dblog/src/Tests/Tour/DbLogTourTest.php

Fix up the random exception (not a fail):

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.

@Farnoosh your patch misses code from #24

+++ b/core/modules/dblog/dblog.module
@@ -116,3 +116,28 @@ function dblog_form_system_logging_settings_alter(&$form, FormStateInterface $fo
+
+/**
+ * Replace the dblog tour tips with real URL paths based on routes.
+ *
+ * @param array $tour_tips
+ *   Array of \Drupal\tour\TipPluginInterface items.
+ * @param \Drupal\Core\Entity\EntityInterface $entity
+ *   The tour which contains the $tour_tips.
+ */
+function dblog_tour_tips_alter(array &$tour_tips, Drupal\Core\Entity\EntityInterface $entity) {
--snip--
+}

Testbot complains about

--- Errors ---
Drupal\simpletest\Exception\MissingGroupException: Missing @group annotation in Drupal\dblog\Tests\Tour\DbLogTourTest in /var/www/html/core/modules/simpletest/src/TestDiscovery.php:352

4 out 7 displayed

Only 4 out of the 7 tips are presented on http://drupal.d8/admin/reports/dblog

Updated patch with fix of Missing @group annotation.

A few comments for the next patch.

1. The array() syntax should be converted to [].
2. There is a new FakeLogEntries::generateLogEntries() trait that you can use to generate logs.
3. I'm not sure why this change is needed, it seems not related to this patch.
   

   -          $message,
   +          array('class' => array('message'), 'data' => $message),
   

4. body: 'Click <em>Clear log messages</em> to remove the messages from the database.' It may be interesting to mention this deletes "all" the logs from the database
5. Finally, would be great to mention that cron should regularly purge old logs. With a link to the settings page.

Fixing failed tests

Fixing the failed tests in patch #43 and implemented suggestions from #38.
Moved tests to the src/Functional Folder.
The array syntax has been changed to [].
Used FakeLogEntries::generateLogEntries() in tests.
Elaborated the text for deleting log messages.
Replaced the deprecated function \Drupal::url in dblog.module file.
Fixed the yml file to show all the tips. Only 4 out of 7 were previously visible.
Added a test method to the test file.
Please review!

Re-rolled #44 and fixed a few CS errors.

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.