show help icons in left and display help messages on click13716-page-help

14 files changed, 146 insertions, 11 deletions

diff --git a/core/Category/Category.php b/core/Category/Category.php
index 6bcc1ba35c..08320b1531 100644
--- a/core/Category/Category.php
+++ b/core/Category/Category.php
@@ -121,4 +121,12 @@ class Category
         return $this->icon;
     }
 
+    /**
+     * Get the help text (if any) for this category.
+     * @return null
+     */
+    public function getHelp()
+    {
+        return null;
+    }
 }
diff --git a/core/Category/Subcategory.php b/core/Category/Subcategory.php
index 9605c6b792..f2180aa22e 100644
--- a/core/Category/Subcategory.php
+++ b/core/Category/Subcategory.php
@@ -56,6 +56,13 @@ class Subcategory
     protected $order = 99;
 
     /**
+     * Help text to display for this category.
+     *
+     * @var null
+     */
+    protected $help = null;
+
+    /**
      * Sets (overwrites) the id of the subcategory see {@link $id}.
      *
      * @param string $id A translation key eg 'General_Overview'.
@@ -143,4 +150,22 @@ class Subcategory
     {
         return $this->order;
     }
+
+    /**
+     * Get the help text (if any) for this category.
+     * @return null
+     */
+    public function getHelp()
+    {
+        return $this->help;
+    }
+
+    /**
+     * Sets the help text for this category.
+     * @param null $help
+     */
+    public function setHelp($help)
+    {
+        $this->help = $help;
+    }
 }
diff --git a/lang/en.json b/lang/en.json
index 8b976da0de..1134b399e4 100644
--- a/lang/en.json
+++ b/lang/en.json
@@ -464,6 +464,7 @@
         "VisitType": "Visit type",
         "VisitTypes": "Visit types",
         "VisitTypeExample": "For example, to select all visitors who have returned to the website, including those who have bought something in their previous visits, the API request would contain %s",
+        "VisitorsOverviewHelp": "This page displays a general overview of your web traffic. See your website's visits and get a birds eye view of how they behave.",
         "Warning": "Warning",
         "Warnings": "Warnings",
         "WarningPhpVersionXIsTooOld": "The PHP version %s you are using has reached its End of Life (EOL). You are strongly urged to upgrade to a current version, as using this version may expose you to security vulnerabilities and bugs that have been fixed in more recent versions of PHP.",
diff --git a/plugins/API/WidgetMetadata.php b/plugins/API/WidgetMetadata.php
index 1ea420ea80..ccbd914f05 100644
--- a/plugins/API/WidgetMetadata.php
+++ b/plugins/API/WidgetMetadata.php
@@ -191,6 +191,7 @@ class WidgetMetadata
             'name'  => $category->getDisplayName(),
             'order' => $category->getOrder(),
             'icon' => $category->getIcon(),
+            'help' => Piwik::translate($category->getHelp()),
         );
     }
 
@@ -208,6 +209,7 @@ class WidgetMetadata
             'id'    => (string) $subcategory->getId(),
             'name'  => Piwik::translate($subcategory->getName()),
             'order' => $subcategory->getOrder(),
+            'help' => Piwik::translate($subcategory->getHelp()),
         );
     }
 
diff --git a/plugins/CoreHome/Categories/VisitorsCategory.php b/plugins/CoreHome/Categories/VisitorsCategory.php
index 3541c7818f..857d9957df 100644
--- a/plugins/CoreHome/Categories/VisitorsCategory.php
+++ b/plugins/CoreHome/Categories/VisitorsCategory.php
@@ -9,10 +9,26 @@
 namespace Piwik\Plugins\CoreHome\Categories;
 
 use Piwik\Category\Category;
+use Piwik\Piwik;
+use Piwik\Url;
 
 class VisitorsCategory extends Category
 {
     protected $id = 'General_Visitors';
     protected $order = 5;
     protected $icon = 'icon-reporting-visitors';
+
+    public function getHelp()
+    {
+        $visitsLogUrl = Url::getQueryStringFromParameters([
+            'category' => 'General_Visitors',
+            'subcategory' => 'Live_VisitorLog',
+        ]);
+        $visitsLogUrl = '<a href="?' . htmlspecialchars($visitsLogUrl) . '" rer="noreferrer noopener">';
+
+        $helpText = '<p>' . Piwik::translate('CoreHome_VisitorsCategoryHelp1') . '</p><br/>';
+        $helpText .= '<p>' . Piwik::translate('CoreHome_VisitorsCategoryHelp2', [$visitsLogUrl, '</a>']) . '</p>';
+
+        return $helpText;
+    }
 }
diff --git a/plugins/CoreHome/Categories/VisitorsOverviewSubcategory.php b/plugins/CoreHome/Categories/VisitorsOverviewSubcategory.php
index abb84ff0ab..9250204df7 100644
--- a/plugins/CoreHome/Categories/VisitorsOverviewSubcategory.php
+++ b/plugins/CoreHome/Categories/VisitorsOverviewSubcategory.php
@@ -15,5 +15,5 @@ class VisitorsOverviewSubcategory extends Subcategory
     protected $categoryId = 'General_Visitors';
     protected $id = 'General_Overview';
     protected $order = 2;
-
+    protected $help = 'General_VisitorsOverviewHelp';
 }
diff --git a/plugins/CoreHome/CoreHome.php b/plugins/CoreHome/CoreHome.php
index cb3f102141..8b4459b99d 100644
--- a/plugins/CoreHome/CoreHome.php
+++ b/plugins/CoreHome/CoreHome.php
@@ -488,5 +488,6 @@ class CoreHome extends \Piwik\Plugin
         $translationKeys[] = 'General_Custom';
         $translationKeys[] = 'General_PreviousPeriod';
         $translationKeys[] = 'General_PreviousYear';
+        $translationKeys[] = 'CoreHome_ReportingCategoryHelpPrefix';
     }
 }
diff --git a/plugins/CoreHome/angularjs/reporting-menu/reportingmenu.controller.js b/plugins/CoreHome/angularjs/reporting-menu/reportingmenu.controller.js
index 533e38fcfe..ce72596703 100644
--- a/plugins/CoreHome/angularjs/reporting-menu/reportingmenu.controller.js
+++ b/plugins/CoreHome/angularjs/reporting-menu/reportingmenu.controller.js
@@ -11,6 +11,8 @@
 
     function ReportingMenuController($scope, piwik, $location, $timeout, menuModel, $rootScope, piwikUrl) {
 
+        $scope.helpShownCategory = null;
+
         var idSite = piwikUrl.getSearchParam('idSite');
         var period = piwikUrl.getSearchParam('period');
         var date   = piwikUrl.getSearchParam('date');
@@ -61,6 +63,18 @@
                 subcategory.name = subsubcategory.name;
                 subsubcategory.active = true;
             }
+        }
+
+        $scope.showHelp = function (category) {
+            var UI = require('piwik/UI');
+            var notification = new UI.Notification();
+            var prefix = '<strong>' + _pk_translate('CoreHome_ReportingCategoryHelpPrefix') + '</strong><br/><br/>';
+            notification.show(prefix + category.help, { context: 'info', id: 'reportingmenu-help', type: 'persistent' });
+            $scope.helpShownCategory = category;
+        };
+
+        $scope.isNotificationShown = function () {
+            return !! $('#reportingmenu-help').length;
         };
 
         $scope.makeUrl = function (category, subcategory) {
@@ -97,6 +111,8 @@
             }
 
             if (category.active && category.subcategories && category.subcategories.length === 1) {
+                $scope.helpShownCategory = null;
+
                 var subcategory = category.subcategories[0];
 
                 if (subcategory.active) {
@@ -111,7 +127,12 @@
         };
 
         $scope.loadSubcategory = function (category, subcategory) {
+            var UI = require('piwik/UI');
+            UI.Notification.prototype.remove('reportingmenu-help');
+
             if (subcategory && subcategory.active) {
+                $scope.helpShownCategory = null;
+
                 // this menu item is already active, a location change success would not be triggered,
                 // instead trigger an event
                 $rootScope.$emit('loadPage', category.id, subcategory.id);
@@ -168,5 +189,8 @@
             enterSubcategory(found.category, found.subcategory, found.subsubcategory);
         });
 
+        $scope.$on('loadPage', function () {
+            $scope.helpShownCategory = null;
+        });
     }
 })();
diff --git a/plugins/CoreHome/angularjs/reporting-menu/reportingmenu.directive.html b/plugins/CoreHome/angularjs/reporting-menu/reportingmenu.directive.html
index c8f8e12759..fc8c203ce8 100644
--- a/plugins/CoreHome/angularjs/reporting-menu/reportingmenu.directive.html
+++ b/plugins/CoreHome/angularjs/reporting-menu/reportingmenu.directive.html
@@ -1,4 +1,4 @@
-<div><ul class="navbar hide-on-med-and-down" role="menu" aria-label="{{ 'CoreHome_MainNavigation'|translate }}">
+<div class="reportingMenu"><ul class="navbar hide-on-med-and-down" role="menu" aria-label="{{ 'CoreHome_MainNavigation'|translate }}">
     <li ng-repeat="category in menuModel.menu"
         class="menuTab"
         role="menuitem"
@@ -11,6 +11,15 @@
              {{ 'CoreHome_Menu'|translate }}
            </span>
         </a>
+
+        <a class="item-help-icon"
+           tabindex="5" href="javascript:"
+           ng-if="(category.active || helpShownCategory == category) && category.help"
+           ng-click="showHelp(category)"
+           ng-class="{'active': helpShownCategory == category && category.help}"
+        >
+            <span class="icon-help"></span>
+        </a>
         <ul role="menu">
             <li ng-repeat="subcategory in category.subcategories"
                 role="menuitem"
@@ -32,6 +41,15 @@
                    ng-click='loadSubcategory(category, subcategory)'>
                     {{ subcategory.name }}
                 </a>
+
+                <a class="item-help-icon"
+                   tabindex="5" href="javascript:"
+                   ng-if="(subcategory.active || elpShownCategory == subcategory) && subcategory.help"
+                   ng-click="showHelp(subcategory)"
+                   ng-class="{'active': helpShownCategory == subcategory && subcategory.help}"
+                >
+                    <span class="icon-help"></span>
+                </a>
             </li>
         </ul>
     </li>
diff --git a/plugins/CoreHome/lang/en.json b/plugins/CoreHome/lang/en.json
index fac30632ed..c85df85d63 100644
--- a/plugins/CoreHome/lang/en.json
+++ b/plugins/CoreHome/lang/en.json
@@ -113,6 +113,9 @@
         "SeeAvailableVersions": "See Available Versions",
         "QuickLinks": "Quick Links",
         "Profilable": "Profilable",
-        "SearchOnMatomo": "Search '%1$s' on Matomo.org"
+        "SearchOnMatomo": "Search '%1$s' on Matomo.org",
+        "ReportingCategoryHelpPrefix": "What does this reporting page show me?",
+        "VisitorsCategoryHelp1": "The Visitors pages tell you things about who your visitors are. Things like where your visitors came from, what devices and browsers they're using and when they generally visit your website. Understand, in the aggregate, who your audience is, and look for outliers to see how your audience could grow.",
+        "VisitorsCategoryHelp2": "In addition to general information about your visitors, you can also use the %1$sVisits Log%2$s to see what occurred in every individual visit."
     }
 }
diff --git a/plugins/CoreHome/stylesheets/layout.less b/plugins/CoreHome/stylesheets/layout.less
index 67967f20ca..2c3743bfc3 100644
--- a/plugins/CoreHome/stylesheets/layout.less
+++ b/plugins/CoreHome/stylesheets/layout.less
@@ -199,22 +199,43 @@ nav {
         .border-radius(0px);
         border: 0;
         background: none;
+        position: relative;
 
         .item {
-          display: inline-block;
           width: 100%;
-          .font-default(13px, 21px);
           padding: 12px 21px 12px 19px;
-          color: @theme-color-menu-contrast-text;
-          decoration: none !important;
           word-wrap: break-word;
           word-break: break-word;
+        }
 
-          &:hover, &:focus {
-            decoration: none !important;
+        .item,.item-help-icon {
+          display: inline-block;
+          .font-default(13px, 21px);
+          color: @theme-color-menu-contrast-text;
+        }
+
+        .item-help-icon {
+          display:none;
+          opacity: 0.2;
+          position: absolute;
+          right: 21px;
+          top: 12px;
+          line-height: 13px;
+        }
+
+        &.menuTab:hover {
+          .item-help-icon:not(.active) {
+            display:inline-block;
+            color: @color-black-piwik;
           }
         }
 
+        .item-help-icon.active {
+          display: inline-block;
+          color: #00bcd4;
+          opacity: 0.75;
+        }
+
         > .item {
           cursor: default;
           font-weight: bold;
@@ -224,6 +245,7 @@ nav {
         }
 
         > ul {
+          position: relative;
 
           li {
             .item {
@@ -250,6 +272,9 @@ nav {
         }
       }
 
+      .menuTab > .item-help-icon {
+        top: 14px;
+      }
 
       .menuDropdown {
         width: 100%;
@@ -330,6 +355,10 @@ nav {
   }
 }
 
+p.reporting-page-help {
+
+}
+
 #root {
   .top_controls {
     visibility: hidden;
diff --git a/plugins/CoreHome/templates/_menu.twig b/plugins/CoreHome/templates/_menu.twig
index 5aee9e8456..a2c69f1920 100644
--- a/plugins/CoreHome/templates/_menu.twig
+++ b/plugins/CoreHome/templates/_menu.twig
@@ -22,7 +22,8 @@
                         <ul role="menu">
                             {% for name,urlParameters in level2 %}
                                 {% if name|slice(0,1) != '_' %}
-                                    <li {% if urlParameters._url.module is defined and urlParameters._url.module == currentModule and urlParameters._url.action is defined and urlParameters._url.action == currentAction %}class="active"{% endif %}
+                                    {% set isActive = urlParameters._url.module is defined and urlParameters._url.module == currentModule and urlParameters._url.action is defined and urlParameters._url.action == currentAction %}
+                                    <li {% if isActive %}class="active"{% endif %}
                                         role="menuitem"
                                     >
                                         <a class="item" tabindex="5" target="_self"
diff --git a/plugins/Dashboard/Categories/DashboardCategory.php b/plugins/Dashboard/Categories/DashboardCategory.php
index 6a7ca4bcc5..746d4e2ca7 100644
--- a/plugins/Dashboard/Categories/DashboardCategory.php
+++ b/plugins/Dashboard/Categories/DashboardCategory.php
@@ -9,10 +9,16 @@
 namespace Piwik\Plugins\Dashboard\Categories;
 
 use Piwik\Category\Category;
+use Piwik\Piwik;
 
 class DashboardCategory extends Category
 {
     protected $id = 'Dashboard_Dashboard';
     protected $order = 0;
     protected $icon = 'icon-reporting-dashboard';
+
+    public function getHelp()
+    {
+        return '<p>' . Piwik::translate('Dashboard_DashboardCategoryHelp', ['<strong>', '</strong>']) . '</p>';
+    }
 }
diff --git a/plugins/Dashboard/lang/en.json b/plugins/Dashboard/lang/en.json
index 68bfd22c8e..522408467b 100644
--- a/plugins/Dashboard/lang/en.json
+++ b/plugins/Dashboard/lang/en.json
@@ -32,6 +32,7 @@
         "SetAsDefaultWidgetsConfirmHelp": "This widgets selection and dashboard columns layout will be used when any user creates a new dashboard, or when \"%s\" feature is used.",
         "TopLinkTooltip": "View Web Analytics reports for %s.",
         "WidgetNotFound": "Widget not found",
-        "WidgetPreview": "Widget preview"
+        "WidgetPreview": "Widget preview",
+        "DashboardCategoryHelp": "This is a dashboard page. Dashboards are a collection of Matomo's widgets that you add yourself to suit your specific needs. Mix and match any of Matomo's widgets to get the data %1$s*you*%2$s need at a glance."
     }
 }
\ No newline at end of file