How to create a plugin from scratch within Matomo Analytics?
A huge thanks to Lukas Winkler for his help for the development of this plugin, mostly dealing with the icon part.
Disclaimer: this tutorial is before all a tutorial explaining how to create a plugin. I am not a developer so high chances that the ended results may be buggy on live installation. So that's really for your local test installation and for education
only.
The example I am going to take here is the one of shortcuts, the idea is to have a shortcut feature similar to the one Google Analytics in the past, nowadays they renamed it as "Saved reports":
What does this feature do?
It is saving a configuration of a known report. The typical use case is the following one, you would like to see the evolution of a given keyword over time or a page and that you are feed up to always apply a filter to it.
Shortcuts will allow you to save those preferences in order to have an easy access to it.
Let's create our plugin
The first step is about creating a plugin, in fact in Matomo, almost everything is a plugin, from templates to widgets... so you need first to access to the console of your server and then perform:
sudo ./console generate:plugin --name="Shortcuts"
Then, the console will ask you some questions. The first one is about the description, I wrote:
This feature allows you to access easily to standard reports on which filters are applied according to your preferences.
Then the console is asking you for a version, i left this part empty and pressed enter.
In order to start using the plugin, you need to activate it so perform:
sudo ./console plugin:activate Shortcuts
So, now you have a plugin, but as previously mentioned, a plugin means a lot of things in Matomo, in our case, this plugin is a category which hold reports, so we need to create reports. In order to create one just perform:
sudo ./console generate:report
It will ask you some questions, here are my answers:
Name of the plugin: Shortcuts
Name of the report: Whatever you want, though give it a name which is explicit, in fact this name corresponds to the name of your custom report. In my case I named it France, as I would like to have a report tailored for this country.
Enter the report Category: Shortcuts (in our case the plugin and the main category have exactly the same name).
Enter a documentation that describes the data of your report: A report showing only the number of visits for the country France.
Enter the report dimension: Country (as in my case I want to work with this dimension).
At this step, you have a report but it does not yet appear within the UI so you need to edit your plugin with:
sudo nano /matomo/plugins/Shortcuts/Reports/GetYourReportName.php
then you uncomment the following line:
$this->subcategoryId = 'Shortcuts_YourReportName';
Ok, so at this step, what you should have is this:
So we have a category displayed but without any icon on it and we have an empty report.
Let's fix the part with the report first.
Making saved reports
To make saved reports I modified the file named API.php, the part you need to replace is the following:
which corresponds to the default static example report, I changed it into:
public function getFrance($idSite, $period, $date, $segment = false){
$report = \Piwik\API\Request::processRequest('UserCountry.getCountry', array(
'idSite' => $idSite,
'period' => $period,
'date' => $date,
'label' => 'France'
));
return $report;
}
At this step, here is what I am getting:
That's nice, that's what I expected, though it would be greater if I had an example of another report.
Let's create another report
So for this I will call:
sudo ./console generate:report
So the plugin to assign it to is still "Shortcuts", the name of the plugin is going to be "My partners" (I will follow in there the traffic from my partners only). The report dimension will be Referrer.
Ok, great my report is created so let's no modify it by uncommenting the line to assign it to the right category.
$this->subcategoryId
and now let's modify the API.php file exactly like before by having this part replacing the example:
public function getMypartners($idSite, $period, $date, $segment = false)
{
$report = \Piwik\API\Request::processRequest('Referrers.getAll', array(
'idSite' => $idSite,
'period' => $period,
'date' => $date,
'label' => 'www.gibson.com'
));
return $report;
}
and now we have a second saved reports:
Adding an icon to a category within Matomo
This part is not trivial, and unfortunately I did not take enough time to finish it properly. First you need to create a menu as a widget:
sudo ./console generate:widget
Then you need to answer questions, I did it like this:
Enter the name of your plugin: Shortcuts
Enter the name of your Widget, for instance "Browser Families": Shortcuts category
Enter the widget category, for instance "Visitor" (you can reuse any existing category or define a new
one): Shortcuts
This part of the plugin has not been done by myself but by Lukas as there is no easy way to do it. What he did was this, he added a folder at the level of my plugin named Categories. Within it he added two files named 'ShortcutsCategory.php' and 'ShortcutsSubcategory.php'
Content of ShortcutsCategory.php
<?php
/**
* Matomo - free/libre analytics platform
*
* @link https://matomo.org
* @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
*
*/
namespace Piwik\Plugins\Shortcuts\Categories;
use
Piwik\Category\Category;
class ShortcutsCategory extends Category
{
protected $id = 'Shortcuts_Shortcuts';
protected $order = 10;
protected $icon = 'icon-custom-shortcuts';
}
Content of ShortcutsSubcategory.php
<?php
/**
* Matomo - free/libre analytics platform
*
* @link https://matomo.org
* @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
*
*/
namespace Piwik\Plugins\Shortcuts\Categories;
use
Piwik\Category\Subcategory;
class ShortcutsSubcategory extends Subcategory
{
protected $categoryId = 'Shortcuts_Shortcuts';
protected $id = 'Shortcuts_Overview';
protected
$order = 2;
}
Then he added a folder named assets containing the icon that I wanted to display.
Then he added a CSS folder named stylesheets with one file named icon.css with the following content:
span.icon-custom-shortcuts {
background-image: url("/plugins/Shortcuts/assets/call_made-24px.svg");
background-size: cover;
width: 13px;
display: inline-block;
height: 14px;
margin-right:
13px;
padding: 0;
}
and he modified the main file accordingly.
Modifying Shorcuts.php
In order for all those files to be syncronized you need to edit Shorcuts.php like this:
<?php
/**
* Piwik - free/libre analytics platform
*
* @link https://matomo.org
* @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
*/
namespace Piwik\Plugins\Shortcuts;
class
Shortcuts extends \Piwik\Plugin
{
public function registerEvents()
{
return array(
'AssetManager.getStylesheetFiles' => 'getStylesheetFiles',
);
}
public function getStylesheetFiles(&$files)
{
$files[] = "plugins/Shortcuts/stylesheets/icon.css";
}
}
Modifying GetShortcutscategory.php
Change the widget content like this:
<?php
namespace Piwik\Plugins\Shortcuts\Widgets;
use Piwik\Widget\Widget;
use Piwik\Widget\WidgetConfig;
use Piwik\View;
class GetShortcutscategory extends Widget
{
public static function configure(WidgetConfig
$config)
{
$config->setCategoryId('Shortcuts_Shortcuts');
$config->setSubcategoryId('Shortcuts_Overview');
$config->setName('Shortcuts_Shortcutscategory');
$config->setOrder(99);
}
public function render()
{
return '<div class="widgetBody">My Widget Text</div>';
}
}