Customizeable / Extendable Visitor Profile & Visitor Log (#11579)

* move setting visitor details into own classes instead of using an event

* move manipulating actions to VisitorDetails classes

* move some more parts to plugins

* update test files as order of columns changed

* implement new VisitorDetails method to provide actions

* move rendering actions to visitordetail classes

* render visitor properties in new classes

* makes it possible to attach icons to visitor log

* moves rendering of action tooltip into new visitordetails method

* adds event for extending custom action dimension fields

* small improvements

* fetch log_link_visit_action.idpageview for actions

* improve variable name

* started to improve/change visitor profile

* show devices summary in visitor profile

* also remove empty xml tags for api tests

* hide actions in visitor profile by default

* move all icons to the middle of visitor log

* small change

* move rendering referrer information to referrers plugin

* move provider logic to provider plugin

* show content interactions in visitor log

* improve look of content interactions/impressions in visitor log / profile

* hide idpageview from tests

* update changelog

* move rendering events to Events plugin

* do not hide duplicate page views in visitor log, but show them with a refresh icon instead

* show top visited pages in visitor profile

* always show visitor profile link in visitor log

Still hidden in a widget by default, as it might overlay some other content

* Show info about not shown actions

truncated due to config setting

* use bulk queries to fetch actions instead of fetching them for each visit

* small adjustments

* improve some loops to improve memory usage

* move gathering visitor profile informations to VisitorDetails classes

* update screenshots

* update test files

* move rendering of visitor profile summary to visitor details classes

* improve templates

* Makes VisitorDetailsAbstract class api and improves comments

* show visit details in visitor profile

* improve css

* reverse enumeration of visits in visitor profile

* improve css

* Show visit id in IP tooltip

* Small CSS improvements

* further adjustments

* sort devices by count

* adds UI tests for visitor log and profile

* Show bandwidth in visitor profile test

* show actions by default and add button to toggle all together

* CSS cleanup

* remove border around refresh icon

* add tooltip for refresh icon in profile

* move first/last visit before top visited pages

* Improve text shown for unique pageviews

* link urls in top visited pages

* improve sorting of device list

* improve tests

* Improve device overview in visitor profile

* only render top pages if at least one page was visited more than once

* make visitor id non bold

* hide visitor type icon in profile, and show latest visits icons in overview

* fix search engine icon in visitor details

* small improvements

* only render view if required

* show visit icons only on hover in profile

* remove from again

* test improves

* show text besides icon in profile header

* improve tests

* Removes unused CSS and JS

* Reformats CSS

* Removes invisible paper clip

* Removes unused profile images from Live plugin

* raise test timeouts

* Improve UI tests splitting for travis

* show device type in profile header if no resolution is available

* prevent text overlapping

* no retries

* fix test

* change summary order

* fix position of export icon

* fixes tooltip text

* improve pages overview

* visitor details order

* action tooltip order

* show only ecommerce icon if no goals where converted

* show custom variables summary in profile

* show user id in same size as headline

* link referer urls for first/last visit in profile

* make profile xml compatible

* try to improve ui test

* increase bottom marign

* increase version number

* small adjustments

* CSS Rewrite for visitor profile

* center action icons in visitor log and profile

* improve widgetized visitor profile

* small layout fix

* always populate raw referrer url for visitor details

* update expected test files

* Refactor profile summaries into additional classes

* update screenshots

* submodule update

* update piwik-icons submodule (#11904)

* update piwik-icons submodule

* fix some system tests

* update screenshots

* make device list xml compatible

* improve translation

* improve icon position

* improves spacings

* update test files

* small css improvement

* update screenshots

1 files changed, 275 insertions, 0 deletions

diff --git a/plugins/Live/VisitorDetailsAbstract.php b/plugins/Live/VisitorDetailsAbstract.php
new file mode 100644
index 0000000000..19ae14f685
--- /dev/null
+++ b/plugins/Live/VisitorDetailsAbstract.php
@@ -0,0 +1,275 @@
+<?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\Live;
+
+use Piwik\DataTable;
+
+/**
+ * Class VisitorDetailsAbstract
+ *
+ * This class can be implemented in a plugin to extend the Live reports, visitor log and profile
+ *
+ * @api
+ */
+abstract class VisitorDetailsAbstract
+{
+    protected $details = array();
+
+    /**
+     * Set details of current visit
+     *
+     * @param array $details
+     */
+    public function setDetails($details)
+    {
+        $this->details = $details;
+    }
+
+    /**
+     * Makes it possible to extend the visitor details returned from API
+     *
+     * **Example**
+     *
+     *    public function extendVisitorDetails(&$visitor) {
+     *        $crmData = Model::getCRMData($visitor['userid']);
+     *
+     *        foreach ($crmData as $prop => $value) {
+     *            $visitor[$prop] = $value;
+     *        }
+     *    }
+     *
+     * @param array $visitor
+     * @return void
+     */
+    public function extendVisitorDetails(&$visitor)
+    {
+    }
+
+    /**
+     * Makes it possible to enrich the action set for a single visit
+     *
+     * **Example**
+     *
+     *    public function provideActionsForVisit(&$actions, $visitorDetails) {
+     *        $adviews = Model::getAdviews($visitorDetails['visitid']);
+     *        $actions += $adviews;
+     *    }
+     *
+     * @param array $actions List of action to manipulate
+     * @param array $visitorDetails
+     * @return void
+     */
+    public function provideActionsForVisit(&$actions, $visitorDetails)
+    {
+    }
+
+    /**
+     * Makes it possible to enrich the action set for multiple visits identified by given visit ids
+     *
+     * action set to enrich needs to have the following structure
+     *
+     * $actions = array (
+     *     'idvisit' => array ( list of actions for this visit id ),
+     *     'idvisit' => array ( list of actions for this visit id ),
+     *     ...
+     * )
+     *
+     * **Example**
+     *
+     *    public function provideActionsForVisitIds(&$actions, $visitIds) {
+     *        $adviews = Model::getAdviewsByVisitIds($visitIds);
+     *        foreach ($adviews as $idVisit => $adView) {
+     *            $actions[$idVisit][] = $adView;
+     *        }
+     *    }
+     *
+     * @param array $actions   action set to enrich
+     * @param array $visitIds  list of visit ids
+     */
+    public function provideActionsForVisitIds(&$actions, $visitIds)
+    {
+    }
+
+    /**
+     * Allows filtering the provided actions
+     *
+     * **Example:**
+     *
+     *     public function filterActions(&$actions, $visitorDetailsArray) {
+     *         foreach ($actions as $idx => $action) {
+     *             if ($action['type'] == 'customaction') {
+     *                 unset($actions[$idx]);
+     *                 continue;
+     *             }
+     *         }
+     *     }
+     *
+     * @param array $actions
+     * @param array $visitorDetailsArray
+     */
+    public function filterActions(&$actions, $visitorDetailsArray)
+    {
+    }
+
+    /**
+     * Allows extended each action with additional information
+     *
+     * @param array $action
+     * @param array $nextAction
+     * @param array $visitorDetails
+     */
+    public function extendActionDetails(&$action, $nextAction, $visitorDetails)
+    {
+    }
+
+    /**
+     * Called when rendering a single Action
+     *
+     * @param array $action
+     * @param array $previousAction
+     * @param array $visitorDetails
+     * @return string
+     */
+    public function renderAction($action, $previousAction, $visitorDetails)
+    {
+    }
+
+    /**
+     * Called for rendering the tooltip on actions
+     * returned array needs to look like this:
+     * array (
+     *          20,   // order id
+     *          'rendered html content'
+     * )
+     *
+     * @param array $action
+     * @param array $visitInfo
+     * @return array
+     */
+    public function renderActionTooltip($action, $visitInfo)
+    {
+        return [];
+    }
+
+    /**
+     * Called when rendering the Icons in visitor log
+     *
+     * @param array $visitorDetails
+     * @return string
+     */
+    public function renderIcons($visitorDetails)
+    {
+    }
+
+    /**
+     * Called when rendering the visitor details in visitor log
+     * returned array needs to look like this:
+     * array (
+     *          20,   // order id
+     *          'rendered html content'
+     * )
+     *
+     * **Example**
+     *    public function renderVisitorDetails($visitorDetails) {
+     *        $view            = new View('@MyPlugin/_visitorDetails.twig');
+     *        $view->visitInfo = $visitorDetails;
+     *        return $view->render();
+     *    }
+     *
+     * @param array $visitorDetails
+     * @return array
+     */
+    public function renderVisitorDetails($visitorDetails)
+    {
+        return array();
+    }
+
+    /**
+     * Allows manipulating the visitor profile properties
+     * Will be called when visitor profile is initialized
+     *
+     * **Example**
+     *
+     *    public function initProfile($visit, &$profile) {
+     *        // initialize properties that will be filled based on visits or actions
+     *        $profile['totalActions']         = 0;
+     *        $profile['totalActionsOfMyType'] = 0;
+     *    }
+     *
+     * @param DataTable $visits
+     * @param array $profile
+     * @return void
+     */
+    public function initProfile($visits, &$profile)
+    {
+    }
+
+    /**
+     * Allows manipulating the visitor profile properties based on included visits
+     * Will be called for every action within the profile
+     *
+     * **Example**
+     *
+     *    public function handleProfileVisit($visit, &$profile) {
+     *        $profile['totalActions'] += $visit->getColumn('actions');
+     *    }
+     *
+     * @param DataTable\Row $visit
+     * @param array $profile
+     * @return void
+     */
+    public function handleProfileVisit($visit, &$profile)
+    {
+    }
+
+    /**
+     * Allows manipulating the visitor profile properties based on included actions
+     * Will be called for every action within the profile
+     *
+     * **Example**
+     *
+     *    public function handleProfileAction($action, &$profile)
+     *    {
+     *        if ($action['type'] != 'myactiontype') {
+     *            return;
+     *        }
+     *
+     *        $profile['totalActionsOfMyType']++;
+     *    }
+     *
+     * @param array $action
+     * @param array $profile
+     * @return void
+     */
+    public function handleProfileAction($action, &$profile)
+    {
+    }
+
+    /**
+     * Will be called after iterating over all actions
+     * Can be used to set profile information that requires data that was set while iterating over visits & actions
+     *
+     * **Example**
+     *
+     *    public function finalizeProfile($visits, &$profile) {
+     *        $profile['isPowerUser'] = false;
+     *
+     *        if ($profile['totalActionsOfMyType'] > 20) {
+     *            $profile['isPowerUser'] = true;
+     *        }
+     *    }
+     *
+     * @param DataTable $visits
+     * @param array $profile
+     * @return void
+     */
+    public function finalizeProfile($visits, &$profile)
+    {
+    }
+}
\ No newline at end of file