Auto generated glossary of all Metrics & Report definitions in Piwik #6773

8 files changed, 177 insertions, 7 deletions

diff --git a/lang/en.json b/lang/en.json
index 8a3b9df0fc..72a699e3ee 100644
--- a/lang/en.json
+++ b/lang/en.json
@@ -43,7 +43,6 @@
         "ColumnAvgTimeOnSiteDocumentation": "The average duration of a visit.",
         "ColumnBounceRate": "Bounce Rate",
         "ColumnBounceRateDocumentation": "The percentage of visits that only had a single pageview. This means, that the visitor left the website directly from the entrance page.",
-        "ColumnBounceRateForPageDocumentation": "Percentage of visits that started and ended on this page.",
         "ColumnBounces": "Bounces",
         "ColumnBouncesDocumentation": "Number of visits that started and ended on this page. This means that the visitor left the website after viewing only this page.",
         "ColumnConversionRate": "Conversion Rate",
diff --git a/plugins/API/Controller.php b/plugins/API/Controller.php
index 17dbe3fd12..f623206786 100644
--- a/plugins/API/Controller.php
+++ b/plugins/API/Controller.php
@@ -137,4 +137,16 @@ class Controller extends \Piwik\Plugin\Controller
 		</table>
 		";
     }
+
+    public function glossary()
+    {
+        Piwik::checkUserHasSomeViewAccess();
+
+        $glossary = new Glossary($this->idSite);
+
+        return $this->renderTemplate('glossary', array(
+            'reports' => $glossary->reportsGlossary(),
+            'metrics' => $glossary->metricsGlossary(),
+        ));
+    }
 }
diff --git a/plugins/API/Glossary.php b/plugins/API/Glossary.php
new file mode 100644
index 0000000000..0b92b9cd35
--- /dev/null
+++ b/plugins/API/Glossary.php
@@ -0,0 +1,102 @@
+<?php
+/**
+ * Piwik - free/libre analytics platform
+ *
+ * @link http://piwik.org
+ * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ *
+ */
+
+namespace Piwik\Plugins\API;
+
+class Glossary
+{
+    function __construct($idSite)
+    {
+        $this->metadata = API::getInstance()->getReportMetadata($idSite);
+    }
+
+    public function reportsGlossary()
+    {
+        $reports = array();
+        foreach ($this->metadata as $report) {
+            if (isset($report['documentation'])) {
+                $reports[] = array(
+                    'name' => sprintf("%s (%s)", $report['name'], $report['category']),
+                    'documentation' => $report['documentation']
+                );
+            }
+        }
+
+        usort($reports, function ($a, $b) {
+            return strcmp($a['name'], $b['name']);
+        });
+
+        return $reports;
+    }
+
+    public function metricsGlossary()
+    {
+        $metrics = array();
+        foreach ($this->metadata as $report) {
+            if (!isset($report['metricsDocumentation'])) {
+                continue;
+            }
+
+            foreach ($report['metricsDocumentation'] as $metricId => $metricDocumentation) {
+
+                $metricKey = $metricId;
+
+                if(empty($report['metrics'][$metricId])
+                    && empty($report['processedMetrics'][$metricId])) {
+                    continue;
+                }
+
+                $metricName = isset($report['metrics'][$metricId]) ? $report['metrics'][$metricId] : $report['processedMetrics'][$metricId];
+
+
+                // Already one metric with same name, but different documentation...
+                if (isset($metrics[$metricKey])
+                    && $metrics[$metricKey]['documentation'] !== $metricDocumentation) {
+
+                    // Don't show nb_hits in glossary since it duplicates others, eg. nb_downloads,
+                    if($metricKey == 'nb_hits') {
+                        continue;
+                    }
+
+                    $metricName = sprintf("%s (%s)", $metricName, $report['category']);
+                    $metricKey = $metricName;
+
+                    if (isset($metrics[$metricKey]) && $metrics[$metricKey]['documentation'] !== $metricDocumentation) {
+                        throw new \Exception(sprintf("Metric %s has two different documentations: \n(1) %s \n(2) %s",
+                                $metricKey,
+                                $metrics[$metricKey]['documentation'],
+                                $metricDocumentation)
+                        );
+                    }
+                } else {
+
+                    if (!isset($report['metrics'][$metricId])
+                        && !isset($report['processedMetrics'][$metricId])
+                    ) {
+                        // $metricId metric name not found in  $report['dimension'] report
+                        // it will be set in another one
+                        continue;
+                    }
+
+                }
+
+                $metrics[$metricKey] = array(
+                    'name' => $metricName,
+                    'id' => $metricId,
+                    'documentation' => $metricDocumentation
+                );
+            }
+        }
+
+        usort($metrics, function ($a, $b) {
+            return strcmp($a['name'], $b['name']);
+        });
+        return $metrics;
+    }
+}
\ No newline at end of file
diff --git a/plugins/API/Menu.php b/plugins/API/Menu.php
index a0f71ddf54..0b1a78e5b3 100644
--- a/plugins/API/Menu.php
+++ b/plugins/API/Menu.php
@@ -26,10 +26,16 @@ class Menu extends \Piwik\Plugin\Menu
 
     public function configureUserMenu(MenuUser $menu)
     {
-        $apiUrlParams = $this->urlForAction('listAllAPI', array('segment' => false));
-        $tooltip      = Piwik::translate('API_TopLinkTooltip');
+        $menu->addPlatformItem('General_API',
+            $this->urlForAction('listAllAPI', array('segment' => false)),
+            6,
+            Piwik::translate('API_TopLinkTooltip')
+        );
 
-        $menu->addPlatformItem('General_API', $apiUrlParams, 6, $tooltip);
+        $menu->addPlatformItem('API_Glossary',
+            $this->urlForAction('glossary', array('segment' => false)),
+            50
+        );
     }
 
     private function addTopMenuMobileApp(MenuTop $menu)
diff --git a/plugins/API/lang/en.json b/plugins/API/lang/en.json
index 47ff86f0c8..dfd08850f7 100644
--- a/plugins/API/lang/en.json
+++ b/plugins/API/lang/en.json
@@ -8,6 +8,7 @@
         "ReportingApiReference": "Reporting API Reference",
         "TopLinkTooltip": "Access your Web Analytics data programmatically through a simple API in json, xml, etc.",
         "UserAuthentication": "User authentication",
-        "UsingTokenAuth": "If you want to %s request data within a script, a crontab, etc. %s you need to add the parameter %s to the API calls URLs that require authentication."
+        "UsingTokenAuth": "If you want to %s request data within a script, a crontab, etc. %s you need to add the parameter %s to the API calls URLs that require authentication.",
+        "Glossary": "Glossary"
     }
 }
\ No newline at end of file
diff --git a/plugins/API/templates/glossary.twig b/plugins/API/templates/glossary.twig
new file mode 100644
index 0000000000..cd12bbbff6
--- /dev/null
+++ b/plugins/API/templates/glossary.twig
@@ -0,0 +1,50 @@
+{% extends 'user.twig' %}
+
+{% set title %}{{ 'API_Glossary'|translate }}{% endset %}
+
+{% block content %}
+    {% include "@CoreHome/_siteSelectHeader.twig" %}
+
+    <div class="top_controls">
+        {% include "@CoreHome/_periodSelect.twig" %}
+    </div>
+
+
+    <h2 piwik-enriched-headline>{{ title }}</h2>
+
+    {{ 'Learn about the commonly used terms to make the most of Piwik Analytics: %s and %s.'|translate(
+                '<a href="#metrics">'~ 'General_Metrics'|translate ~ '</a>',
+                '<a href="#reports">' ~ 'General_Reports'|translate ~ '</a>')|raw
+    }}
+
+    <!-- {{ metrics|length }} metrics, {{ reports|length }} reports -->
+
+    <a id="metrics"></a>
+    <h2>{{ 'General_Metrics'|translate }}</h2>
+    <table>
+    {% for metric in metrics %}
+        <tr>
+            <td>
+                <h3>{{ metric.name }}</h3>
+            </td>
+            <td>
+                {{ metric.documentation|raw }}
+
+                <br/><span style="color: #bbb;">{{ metric.id }} (API)</span>
+            </td>
+        </tr>
+    {% endfor %}
+    </table>
+
+    <a id="reports"></a>
+    <h2>{{ 'General_Reports'|translate }}</h2>
+
+
+    {% for report in reports %}
+        <h3>{{ report.name }}</h3>
+        <p>{{ report.documentation|raw }}</p>
+    {% endfor %}
+
+
+
+{% endblock %}
\ No newline at end of file
diff --git a/plugins/Actions/Reports/GetEntryPageTitles.php b/plugins/Actions/Reports/GetEntryPageTitles.php
index e166c87cb8..7c029f4b02 100644
--- a/plugins/Actions/Reports/GetEntryPageTitles.php
+++ b/plugins/Actions/Reports/GetEntryPageTitles.php
@@ -54,7 +54,7 @@ class GetEntryPageTitles extends Base
     protected function getMetricsDocumentation()
     {
         $metrics = parent::getMetricsDocumentation();
-        $metrics['bounce_rate'] = Piwik::translate('General_ColumnBounceRateForPageDocumentation');
+        $metrics['bounce_rate'] = Piwik::translate('General_ColumnPageBounceRateDocumentation');
 
         // remove these metrics from API.getProcessedReport version of this report
         unset($metrics['avg_time_on_page']);
diff --git a/plugins/Actions/Reports/GetEntryPageUrls.php b/plugins/Actions/Reports/GetEntryPageUrls.php
index dfb3febee6..f3795db099 100644
--- a/plugins/Actions/Reports/GetEntryPageUrls.php
+++ b/plugins/Actions/Reports/GetEntryPageUrls.php
@@ -59,7 +59,7 @@ class GetEntryPageUrls extends Base
     protected function getMetricsDocumentation()
     {
         $metrics = parent::getMetricsDocumentation();
-        $metrics['bounce_rate'] = Piwik::translate('General_ColumnBounceRateForPageDocumentation');
+        $metrics['bounce_rate'] = Piwik::translate('General_ColumnPageBounceRateDocumentation');
 
         unset($metrics['bounce_rate']);
         unset($metrics['exit_rate']);