PDF rausgenommen

msd2/tracking/piwik/core/Widget/Widget.php

@@ -0,0 +1,77 @@
+<?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\Widget;
+use Piwik\View;
+
+/**
+ * Defines a new widget. You can create a new widget using the console command `./console generate:widget`.
+ * The generated widget will guide you through the creation of a widget.
+ *
+ * For an example, see {@link https://github.com/piwik/piwik/blob/master/plugins/ExamplePlugin/Widgets/MyExampleWidget.php}
+ *
+ * @api since Piwik 3.0.0
+ */
+class Widget
+{
+    /**
+     * @param WidgetConfig $config
+     * @api
+     */
+    public static function configure(WidgetConfig $config)
+    {
+    }
+
+    /**
+     * @return string
+     */
+    public function render()
+    {
+        return '';
+    }
+
+    /**
+     * Assigns the given variables to the template and renders it.
+     *
+     * Example:
+     *
+     *     public function myControllerAction () {
+     *        return $this->renderTemplate('index', array(
+     *            'answerToLife' => '42'
+     *        ));
+     *     }
+     *
+     * This will render the 'index.twig' file within the plugin templates folder and assign the view variable
+     * `answerToLife` to `42`.
+     *
+     * @param string $template   The name of the template file. If only a name is given it will automatically use
+     *                           the template within the plugin folder. For instance 'myTemplate' will result in
+     *                           '@$pluginName/myTemplate.twig'. Alternatively you can include the full path:
+     *                           '@anyOtherFolder/otherTemplate'. The trailing '.twig' is not needed.
+     * @param array $variables   For instance array('myViewVar' => 'myValue'). In template you can use {{ myViewVar }}
+     * @return string
+     * @api
+     */
+    protected function renderTemplate($template, array $variables = array())
+    {
+        if (false === strpos($template, '@') || false === strpos($template, '/')) {
+            $aPluginName = explode('\\', get_class($this));
+            $aPluginName = $aPluginName[2];
+            $template = '@' . $aPluginName . '/' . $template;
+        }
+
+        $view = new View($template);
+
+        foreach ($variables as $key => $value) {
+            $view->$key = $value;
+        }
+
+        return $view->render();
+    }
+
+}

msd2/tracking/piwik/core/Widget/WidgetConfig.php

@@ -0,0 +1,368 @@
+<?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\Widget;
+
+use Piwik\Piwik;
+use Exception;
+
+/**
+ * Configures a widget. Use this class to configure a {@link Piwik\Widget\Widget`} or to
+ * add a widget to the WidgetsList via {@link WidgetsList::addWidget}.
+ *
+ * @api since Piwik 3.0.0
+ */
+class WidgetConfig
+{
+    protected $categoryId = '';
+    protected $subcategoryId = '';
+    protected $module = '';
+    protected $action = '';
+    protected $parameters = array();
+    protected $middlewareParameters = array();
+    protected $name   = '';
+    protected $order  = 99;
+    protected $isEnabled = true;
+    protected $isWidgetizable = true;
+    protected $isWide = false;
+
+    /**
+     * Set the id of the category the widget belongs to.
+     * @param  string $categoryId  Usually a translation key, eg 'General_Visits', 'Goals_Goals', ...
+     * @return static
+     */
+    public function setCategoryId($categoryId)
+    {
+        $this->categoryId = $categoryId;
+
+        return $this;
+    }
+
+    /**
+     * Get the id of the category the widget belongs to.
+     * @return string
+     */
+    public function getCategoryId()
+    {
+        return $this->categoryId;
+    }
+
+    /**
+     * Set the id of the subcategory the widget belongs to. If a subcategory is specified, the widget
+     * will be shown in the Piwik reporting UI. The subcategoryId will be used as a translation key for
+     * the submenu item.
+     *
+     * @param  string $subcategoryId  Usually a translation key, eg 'General_Overview', 'Actions_Pages', ...
+     * @return static
+     */
+    public function setSubcategoryId($subcategoryId)
+    {
+        $this->subcategoryId = $subcategoryId;
+
+        return $this;
+    }
+
+    /**
+     * Get the currently set category ID.
+     * @return string
+     */
+    public function getSubcategoryId()
+    {
+        return $this->subcategoryId;
+    }
+
+    /**
+     * Set the module (aka plugin name) of the widget. The correct module is usually detected automatically and
+     * not needed to be configured manually.
+     *
+     * @param string $module eg 'CoreHome'
+     * @return static
+     */
+    public function setModule($module)
+    {
+        $this->module = $module;
+
+        return $this;
+    }
+
+    public function getModule()
+    {
+        return $this->module;
+    }
+
+    /**
+     * Set the action of the widget that shall be used in the URL to render the widget.
+     * The correct action is usually detected automatically and not needed to be configured manually.
+     *
+     * @param string $action eg 'renderMyWidget'
+     * @return static
+     */
+    public function setAction($action)
+    {
+        $this->action = $action;
+
+        return $this;
+    }
+
+    /**
+     * Get the currently set action.
+     * @return string
+     */
+    public function getAction()
+    {
+        return $this->action;
+    }
+
+    /**
+     * Sets (overwrites) the parameters of the widget. These parameters will be added to the URL when rendering the
+     * widget. You can access these parameters via `Piwik\Common::getRequestVar(...)`.
+     *
+     * @param array $parameters eg. ('urlparam' => 'urlvalue')
+     * @return static
+     */
+    public function setParameters($parameters)
+    {
+        $this->parameters = $parameters;
+
+        return $this;
+    }
+
+    /**
+     * Add new parameters and only overwrite parameters that have the same name. See {@link setParameters()}
+     *
+     * @param  array $parameters eg. ('urlparam' => 'urlvalue')
+     * @return static
+     */
+    public function addParameters($parameters)
+    {
+        $this->parameters = array_merge($this->parameters, $parameters);
+
+        return $this;
+    }
+
+    /**
+     * Get all URL parameters needed to render this widget.
+     * @return array  Eg ('urlparam' => 'urlvalue').
+     */
+    public function getParameters()
+    {
+        $defaultParams = array(
+            'module' => $this->getModule(),
+            'action' => $this->getAction()
+        );
+
+        return $defaultParams + $this->parameters;
+    }
+
+    /**
+     * Set the name of the widget.
+     *
+     * @param string $name Usually a translation key, eg 'VisitTime_ByServerTimeWidgetName'
+     * @return static
+     */
+    public function setName($name)
+    {
+        $this->name = $name;
+
+        return $this;
+    }
+
+    /**
+     * Get the name of the widget.
+     *
+     * @return string
+     */
+    public function getName()
+    {
+        return $this->name;
+    }
+
+    /**
+     * Set the order of the widget.
+     *
+     * @param int $order eg. 5
+     * @return static
+     */
+    public function setOrder($order)
+    {
+        $this->order = (int) $order;
+
+        return $this;
+    }
+
+    /**
+     * Returns the order of the widget.
+     * @return int
+     */
+    public function getOrder()
+    {
+        return $this->order;
+    }
+
+    /**
+     * Defines whether a widget is enabled or not. For instance some widgets might not be available to every user or
+     * might depend on a setting (such as Ecommerce) of a site. In such a case you can perform any checks and then
+     * return `true` or `false`. If your report is only available to users having super user access you can do the
+     * following: `return Piwik::hasUserSuperUserAccess();`
+     * @return bool
+     */
+    public function isEnabled()
+    {
+        return $this->isEnabled;
+    }
+
+    /**
+     * Enable / disable the widget. See {@link isEnabled()}
+     *
+     * @param bool $isEnabled
+     * @return static
+     */
+    public function setIsEnabled($isEnabled)
+    {
+        $this->isEnabled = (bool) $isEnabled;
+        return $this;
+    }
+
+    /**
+     * Enables the widget. See {@link isEnabled()}
+     */
+    public function enable()
+    {
+        $this->setIsEnabled(true);
+    }
+
+    /**
+     * Disables the widget. See {@link isEnabled()}
+     */
+    public function disable()
+    {
+        $this->setIsEnabled(false);
+    }
+
+    /**
+     * This method checks whether the widget is available, see {@link isEnabled()}. If not, it triggers an exception
+     * containing a message that will be displayed to the user. You can overwrite this message in case you want to
+     * customize the error message. Eg.
+     * ```
+     * if (!$this->isEnabled()) {
+     *     throw new Exception('Setting XYZ is not enabled or the user has not enough permission');
+     * }
+     * ```
+     * @throws \Exception
+     */
+    public function checkIsEnabled()
+    {
+        if (!$this->isEnabled()) {
+            throw new Exception(Piwik::translate('General_ExceptionWidgetNotEnabled'));
+        }
+    }
+
+    /**
+     * Returns the unique id of an widget based on module, action and the set parameters.
+     *
+     * @return string
+     */
+    public function getUniqueId()
+    {
+        $parameters = $this->getParameters();
+        unset($parameters['module']);
+        unset($parameters['action']);
+
+        return WidgetsList::getWidgetUniqueId($this->getModule(), $this->getAction(), $parameters);
+    }
+
+    /**
+     * Sets the widget as not widgetizable {@link isWidgetizeable()}.
+     *
+     * @return static
+     */
+    public function setIsNotWidgetizable()
+    {
+        $this->isWidgetizable = false;
+        return $this;
+    }
+
+    /**
+     * Sets the widget as widgetizable {@link isWidgetizeable()}.
+     *
+     * @return static
+     */
+    public function setIsWidgetizable()
+    {
+        $this->isWidgetizable = true;
+        return $this;
+    }
+
+    /**
+     * Detect whether the widget is widgetizable meaning it won't be able to add it to the dashboard and it won't
+     * be possible to export the widget via an iframe if it is not widgetizable. This is usually not needed but useful
+     * when you eg want to display a widget within the Piwik UI but not want to have it widgetizable.
+     *
+     * @return bool
+     */
+    public function isWidgetizeable()
+    {
+        return $this->isWidgetizable;
+    }
+
+    /**
+     * If middleware parameters are specified, the corresponding action will be executed before showing the
+     * actual widget in the UI. Only if this action (can be a controller method or API method) returns JSON `true`
+     * the widget will be actually shown. It is similar to `isEnabled()` but the specified action is performed each
+     * time the widget is requested in the UI whereas `isEnabled` is only checked once on the inital page load when
+     * we load the inital list of widgets. So if your widget's visibility depends on archived data
+     * (aka idSite/period/date) you should specify middle parameters. This has mainly two reasons:
+     *
+     * - This way the inital page load time is faster as we won't have to request archived data on the initial page
+     * load for widgets that are potentially never shown.
+     * - We execute that action every time before showing it. As the initial list of widgets is loaded on page load
+     * it is possible that some archives have no data yet, but at a later time there might be actually archived data.
+     * As we never reload the initial list of widgets we would still not show the widget even there we should. Example:
+     * On page load there are no conversions, a few minutes later there might be conversions. As the middleware is
+     * executed before showing it, we detect correctly that there are now conversions whereas `isEnabled` is only
+     * checked once on the initial Piwik page load.
+     *
+     * @param array $parameters URL parameters eg array('module' => 'Goals', 'action' => 'Conversions')
+     * @return static
+     */
+    public function setMiddlewareParameters($parameters)
+    {
+        $this->middlewareParameters = $parameters;
+        return $this;
+    }
+
+    /**
+     * Get defined middleware parameters (if any).
+     *
+     * @return array
+     */
+    public function getMiddlewareParameters()
+    {
+        return $this->middlewareParameters;
+    }
+
+    /**
+     * Marks this widget as a "wide" widget that requires the full width.
+     *
+     * @return $this
+     */
+    public function setIsWide()
+    {
+        $this->isWide = true;
+        return $this;
+    }
+
+    /**
+     * Detect whether the widget should be shown wide or not.
+     * @return bool
+     */
+    public function isWide()
+    {
+        return $this->isWide;
+    }
+}

msd2/tracking/piwik/core/Widget/WidgetContainerConfig.php

@@ -0,0 +1,141 @@
+<?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\Widget;
+
+/**
+ * Defines a new widget container. Widget containers are useful when you want to combine several widgets
+ * into one unique widgets. For example you could combine an evolution graph widget with a sparklines widget
+ * and combine them to a single "overview widget". It also allows you to specify layouts meaning you can
+ * define a layout that will group multiple widgets into one widget displaying a menu on the left side for each
+ * widget and the actual widget on the right side. By default widgets within a container are displayed vertically
+ * one after another.
+ *
+ * To define a widget container just place a subclass within the `Widgets` folder of your plugin.
+ *
+ * @api since Piwik 3.0.0
+ */
+class WidgetContainerConfig extends WidgetConfig
+{
+    /**
+     * @var WidgetConfig[]
+     */
+    protected $widgets = array();
+    protected $layout = '';
+    protected $id = '';
+
+    protected $module = 'CoreHome';
+    protected $action = 'renderWidgetContainer';
+    protected $isWidgetizable = false;
+
+    /**
+     * Sets (overwrites) the id of the widget container.
+     *
+     * The id can be used by any plugins to add more widgets to this container and it will be also used for the unique
+     * widget id and in the URL to render this widget.
+     *
+     * @param string $id eg 'Products' or 'Contents'
+     * @return static
+     */
+    public function setId($id)
+    {
+        $this->id = $id;
+        return $this;
+    }
+
+    /**
+     * Get the id of the widget.
+     * @return string
+     */
+    public function getId()
+    {
+        return $this->id;
+    }
+
+    /**
+     * Sets the layout of the container widget.
+     *
+     * By default widgets within a container are displayed one after another. In case you want to change this
+     * behaviour you can specify a layout that will be recognized by the UI. It is not yet possible to define
+     * custom layouts.
+     *
+     * @param string $layout eg 'ByDimension' see {@link Piwik\Plugins\CoreHome\CoreHome::WIDGET_CONTAINER_LAYOUT_BY_DIMENSION}
+     * @return static
+     */
+    public function setLayout($layout)
+    {
+        $this->layout = $layout;
+        return $this;
+    }
+
+    /**
+     * Gets the currently set layout.
+     * @return string
+     */
+    public function getLayout()
+    {
+        return $this->layout;
+    }
+
+    /**
+     * Adds a new widget to the container widget.
+     *
+     * @param WidgetConfig $widget
+     * @return static
+     */
+    public function addWidgetConfig(WidgetConfig $widget)
+    {
+        $this->widgets[] = $widget;
+
+        return $this;
+    }
+
+    /**
+     * Set (overwrite) widget configs.
+     *
+     * @param WidgetConfig[] $configs
+     */
+    public function setWidgetConfigs($configs)
+    {
+        $this->widgets = $configs;
+    }
+
+    /**
+     * Get all added widget configs.
+     *
+     * @return WidgetConfig[]
+     */
+    public function getWidgetConfigs()
+    {
+        return $this->widgets;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getUniqueId()
+    {
+        $parameters = $this->getParameters();
+        unset($parameters['module']);
+        unset($parameters['action']);
+        unset($parameters['containerId']);
+
+        return WidgetsList::getWidgetUniqueId($this->id, '', $parameters);
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getParameters()
+    {
+        $params = parent::getParameters();
+        $params['containerId'] = $this->getId();
+        return $params;
+    }
+
+}

msd2/tracking/piwik/core/Widget/WidgetsList.php

@@ -0,0 +1,249 @@
+<?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\Widget;
+
+use Piwik\Cache as PiwikCache;
+use Piwik\Container\StaticContainer;
+use Piwik\Development;
+use Piwik\Piwik;
+use Piwik\Report\ReportWidgetFactory;
+
+/**
+ * Manages the global list of reports that can be displayed as dashboard widgets.
+ *
+ * Widgets are added through the {@hook WidgetsList.addWidgets} and filtered through the {@hook Widgets.filterWidgets}
+ * event. Observers for this event should call the {@link addWidget()} method to add widgets or use any of the other
+ * methods to remove widgets.
+ *
+ * @api since Piwik 3.0.0
+ */
+class WidgetsList
+{
+    /**
+     * List of widgets
+     *
+     * @var WidgetConfig[]
+     */
+    private $widgets = array();
+
+    /**
+     * @var WidgetContainerConfig[]
+     */
+    private $container;
+
+    /**
+     * @var array
+     */
+    private $containerWidgets;
+
+    /**
+     * Adds a new widget to the widget config. Please make sure the widget is enabled before adding a widget as
+     * no such checks will be performed.
+     *
+     * @param WidgetConfig $widget
+     */
+    public function addWidgetConfig(WidgetConfig $widget)
+    {
+        if ($widget instanceof WidgetContainerConfig) {
+            $this->addContainer($widget);
+        } elseif (Development::isEnabled()) {
+            $this->checkIsValidWidget($widget);
+        }
+
+        $this->widgets[] = $widget;
+    }
+
+    /**
+     * Add multiple widget configs at once. See {@link addWidgetConfig()}.
+     *
+     * @param WidgetConfig[] $widgets
+     */
+    public function addWidgetConfigs($widgets)
+    {
+        foreach ($widgets as $widget) {
+            $this->addWidgetConfig($widget);
+        }
+    }
+
+    private function addContainer(WidgetContainerConfig $containerWidget)
+    {
+        $widgetId = $containerWidget->getId();
+
+        $this->container[$widgetId] = $containerWidget;
+
+        // widgets were added to this container, but the container did not exist yet.
+        if (isset($this->containerWidgets[$widgetId])) {
+            foreach ($this->containerWidgets[$widgetId] as $widget) {
+                $containerWidget->addWidgetConfig($widget);
+            }
+            unset($this->containerWidgets[$widgetId]);
+        }
+    }
+
+    /**
+     * Get all added widget configs.
+     *
+     * @return WidgetConfig[]
+     */
+    public function getWidgetConfigs()
+    {
+        return $this->widgets;
+    }
+
+    private function checkIsValidWidget(WidgetConfig $widget)
+    {
+        if (!$widget->getModule()) {
+            Development::error('No module is defined for added widget having name "' . $widget->getName());
+        }
+
+        if (!$widget->getAction()) {
+            Development::error('No action is defined for added widget having name "' . $widget->getName());
+        }
+    }
+
+    /**
+     * Add a widget to a widget container. It doesn't matter whether the container was added to this list already
+     * or whether the container is added later. As long as a container having the same containerId is added at
+     * some point the widget will be added to that container. If no container having this id is added the widget
+     * will not be recognized.
+     *
+     * @param string $containerId  eg 'Products' or 'Contents'. See {@link WidgetContainerConfig::setId}
+     * @param WidgetConfig $widget
+     */
+    public function addToContainerWidget($containerId, WidgetConfig $widget)
+    {
+        if (isset($this->container[$containerId])) {
+            $this->container[$containerId]->addWidgetConfig($widget);
+        } else {
+            if (!isset($this->containerWidgets[$containerId])) {
+                $this->containerWidgets[$containerId] = array();
+            }
+
+            $this->containerWidgets[$containerId][] = $widget;
+        }
+    }
+
+    /**
+     * Removes one or more widgets from the widget list.
+     *
+     * @param string $widgetCategoryId The widget category id. Can be a translation token eg 'General_Visits'
+     *                                 see {@link WidgetConfig::setCategoryId()}.
+     * @param string|false $widgetName The name of the widget to remove eg 'VisitTime_ByServerTimeWidgetName'.
+     *                                 If not supplied, all widgets within that category will be removed.
+     */
+    public function remove($widgetCategoryId, $widgetName = false)
+    {
+        foreach ($this->widgets as $index => $widget) {
+            if ($widget->getCategoryId() === $widgetCategoryId) {
+                if (!$widgetName || $widget->getName() === $widgetName) {
+                    unset($this->widgets[$index]);
+                }
+            }
+        }
+    }
+
+    /**
+     * Returns `true` if a widget exists in the widget list, `false` if otherwise.
+     *
+     * @param string $module The controller name of the widget.
+     * @param string $action The controller action of the widget.
+     * @return bool
+     */
+    public function isDefined($module, $action)
+    {
+        foreach ($this->widgets as $widget) {
+            if ($widget->getModule() === $module && $widget->getAction() === $action) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Get all widgets defined in the Piwik platform.
+     * @ignore
+     * @return static
+     */
+    public static function get()
+    {
+        $list = new static;
+
+        $widgets = StaticContainer::get('Piwik\Plugin\WidgetsProvider');
+
+        $widgetContainerConfigs = $widgets->getWidgetContainerConfigs();
+        foreach ($widgetContainerConfigs as $config) {
+            if ($config->isEnabled()) {
+                $list->addWidgetConfig($config);
+            }
+        }
+
+        $widgetConfigs = $widgets->getWidgetConfigs();
+        foreach ($widgetConfigs as $widget) {
+            if ($widget->isEnabled()) {
+                $list->addWidgetConfig($widget);
+            }
+        }
+
+        $reports = StaticContainer::get('Piwik\Plugin\ReportsProvider');
+        $reports = $reports->getAllReports();
+        foreach ($reports as $report) {
+            if ($report->isEnabled()) {
+                $factory = new ReportWidgetFactory($report);
+                $report->configureWidgets($list, $factory);
+            }
+        }
+
+        /**
+         * Triggered to filter widgets.
+         *
+         * **Example**
+         *
+         *     public function removeWidgetConfigs(Piwik\Widget\WidgetsList $list)
+         *     {
+         *         $list->remove($category='General_Visits'); // remove all widgets having this category
+         *     }
+         *
+         * @param WidgetsList $list An instance of the WidgetsList. You can change the list of widgets this way.
+         */
+        Piwik::postEvent('Widget.filterWidgets', array($list));
+
+        return $list;
+    }
+
+    /**
+     * CAUTION! If you ever change this method, existing updates will fail as they currently use that method!
+     * If you change the output the uniqueId for existing widgets would not be found anymore
+     *
+     * Returns the unique id of an widget with the given parameters
+     *
+     * @param $controllerName
+     * @param $controllerAction
+     * @param array $customParameters
+     * @return string
+     */
+    public static function getWidgetUniqueId($controllerName, $controllerAction, $customParameters = array())
+    {
+        $widgetUniqueId = 'widget' . $controllerName . $controllerAction;
+
+        foreach ($customParameters as $name => $value) {
+            if (is_array($value)) {
+                // use 'Array' for backward compatibility;
+                // could we switch to using $value[0]?
+                $value = 'Array';
+            }
+            $value = urlencode($value);
+            $value = str_replace('%', '', $value);
+            $widgetUniqueId .= $name . $value;
+        }
+
+        return $widgetUniqueId;
+    }
+
+}