Theming Help

I’ve gone through both guides to theming ( Piwik Developer - Theming[/url] and [url=http://piwik.org/blog/2014/08/create-custom-theme-piwik-introducing-piwik-platform/]How to create a custom theme in Piwik), and unfortunately they seemed to be a little lacking of covering some basic content. I did some digging and reverse engineering of the code and have some notes I wanted to post in hopes it may help others in the future.

Tracking down theme variables
Pick your browser of choice and "Inspect the Elements"
My example will be using Chrome
If I right click on an item,such as the “Countries Button” and select “Inspect Element” I see highlighted:


Countries

On the right side of the Window I see:
element.style {
}
.tableIcon.activeIcon {
background: #cccccc;
}
If I click on the #cccccc and change it to #cc00cc I see the element change on the screen to a purple color verifying this is the element that I want to manipulate.

From the plugins directory run the command sudo grep -r “.activeIcon” *
One of the results should be Morpheus/stylesheets/general/_typography.less &.activeIcon {
If you view ./Morpheus/stylesheets/general/_typography.less
You will see that the background is defined as @color-silver-l80
(Note: if there is an at sign @ it means that is a variable, if there is a colon : it means you are assigning a value to the variable)
If inside the plugins directory you run the command grep -r “@color-silver-l80:” *
You will find that Morpheus/stylesheets/less/_colors.less contains @color-silver-l80: lighten(@color-black, 80%);
Which tells Piwik to make a variable called color-silver-l80 and assign it the color which is 80% lighter than "black"
This lets us know that we need to add to our _colors.less file the command @color-silver-l80: #cc00cc; so ours will be purple.
If inside the plugins directory I run the command grep -r “@color-silver-l80” * I see that the color-silver-l80 is used in numerous places throughout the theme.
To force Piwik to recompile the LESS files and see the change immediately run the command sudo ./console development:enable then reload the webpage in your browser.

Include other LESS files
In the above example we saw that the color was used in many, many places, and perhaps we didn’t want to change the color everywhere.
To avoid that problem copy plugins/Morpheus/stylesheets/general/_topography.less to plugins/YourTheme/stylesheets/general/_topography.less
Modify the background color to #cc00cc:
.tableIcon {
background: none;
padding: 2px 4px 4px 4px;
&.activeIcon {
background: #cc00cc;
}
Save the changes
Modify and save plugins/YourTheme/stylesheets/theme.less to include a line:
@import “general/_typography”;
Force Piwik to recompile the LESS files to see the change

LESS complexity
In the above example we had found out that the color in the HTML was actually #cccccc however if you did a grep on the entire piwik installation directory for #cccccc you would have never found it defined. The reason is that the way the colors are defined can be very complex. Here’s how that “color” was defined in the Morpheus Theme
In plugins/Morpheus/stylesheets/_colors.less there is a line defining a variable for the color black:
@color-black: #000;
If you use a three digit code of 000 it actually is the same as 000000 with the first two numbers representing the Red Value in Hexadecimal, The second two numbers as the Green Value, and the third two numbers as the Blue Value. In the above line, we’ve defined black as pure black, or more correctly the absence of all Red, Green and Blue values.
Now if you look at plugins/Morpheus/stylesheets/general/_topography.less there is a line defining a color silver l80 which the piwik developers apparently named for being a silver color that is black lightened by 80%
@color-silver-l80: lighten(@color-black, 80%);
The way this line of code works is it defines the variable color-silver-l80 as making the color black 80% lighter.

In RGB to lighten a color means to move it from a value of 00 towards FF. So if we “lighten” 00 by 80 % means we are going to have 80% of the FF value.

Remember Hexadecimal FF equals decimal 255
80% of 255 or (255 * .8) is 204
204 in Hexadecimal is CC
This is how the #cccccc is generated.

Hi Treser,

THank you for your notes and feedback! at the moment we don’t have enough resource to update the guide, but we hope to work on this in a few months. I created an issue at: Improve documentation for Theming · Issue #58 · matomo-org/developer-documentation · GitHub to keep track of your feedback. Cheers

Excellent. Thanks for putting it on a list about the Basic Theming / Skinning of Piwik. I went back and spent a little time to color code my post in hopes it will make things clearer for others. I also am hoping that this post being on the official forums will be easy to find for users trying to use Piwik.

I’ve been very impressed with Piwik’s capabilities, and as a developer wanted to provide some insight from my perspective, and an interim self-help guide since I saw online that many other people had questions about theming and were struggling with it.

Please feel free to plagiarize anything from my post when you get time to modify your documentation and/or guides.

Most of the colors for controlling the “All Visits” dropdown are in segmentation.less
Most of the colors for controlling the “Widgets & Dashboard” are in the dashboard.less