Opened 6 years ago

Closed 9 months ago

Last modified 5 months ago

#177 closed New feature (duplicate)

Build "theming" feature in Piwik.

Reported by: matt Owned by: vipsoft
Priority: normal Milestone: Future releases
Component: Core Keywords:
Cc: Sensitive: no

Description (last modified by vipsoft)

It should be possible to create themes for . piwik to customize its design without modifiying core files.

Proposal for Piwik Themes V1

Proposal November 2011, based from all comments and feedback:

  • Themes are implemented as "plugins"
  • The theme feature in Piwik is a basic concept: CSS override
  • A new hook allows a plugin to add extra CSS file (or simply return $css;). This CSS file would be loaded after all other CSS. This should allow for most theme desired changes? ie. margins, padding, float, colors, fonts, positions, can be changed.
  • Some work / refactoring might be required on some CSS to make them all themable friendly?
  • Building this feature would mostly involve building a custom CSS file override and modify existing Piwik CSS to make it possible / easier than current.
  • See comments for other interesting concepts:
    • Allow modifying colors of Javascript charts?
    • Allow modifying colors of Charts in Email reports/Mobile app?
    • Allow override of chosen TPL files? ALlow override of CSS files? Of whole JS files? I would say that it's best not to allow any override in V1 to keep things simple... thoughts?
    • Should we use a property definition mechanism to define all colors? See #comment:23


Attachments (1)

28.08.png (84.1 KB) - added by kaystrobach 4 years ago.
XGA with Piwik in TYPO3 Backend

Download all attachments as: .zip

Change History (47)

comment:1 Changed 6 years ago by matt (mattab)

  • Description modified (diff)
  • Summary changed from Make piwik theme compatible to Build "theming" feature in Piwik.

comment:2 Changed 5 years ago by jmadsen

Hello,

Completely new to Piwik, but am going to be working with it for a company, and our first step is most likely this - setting up our own theme, and probably customizing what is available to our customer (which widgets, links, etc.)

Has any work been done on this, or does anyone have ideas on how I might start? I may as well look at building a nice, generic set of code and donating to the project, but it's my first day and I'm still stumbling through the Smarty templates and API.

Any feedback is appreciated!

comment:3 Changed 5 years ago by matt (mattab)

  • Description modified (diff)

comment:4 Changed 5 years ago by domtop

comment:5 Changed 5 years ago by spomoni

comment:6 Changed 4 years ago by vipsoft (robocoder)

  • Priority changed from major to normal
  • Sensitive unset

The Piwik "logo" is actually stylized text. While this is very low bandwidth, it means:

  • changing the default font affects the "logo"
  • re-branding Piwik requires changes to various templates

A common footer and meta tags should be added: "Powered by Piwik" with link to piwik.org (and possibly also the GPL)

comment:7 Changed 4 years ago by matt (mattab)

Adding the footer is not desired, as it would only show on the dashboard, and the dashboard has variable height (because of widgets) which looks dodgy (I tried a long time ago).

It would indeed be nice to rebrand Piwik easily, currently it requires a change to the templates.

comment:8 Changed 4 years ago by kaystrobach

hello guys,
i'm currently working on a typo3 integration of piwik
http://forge.typo3.org/wiki/extension-piwikintegration/Manual_for_20
I think it would be even impressive if piwik would use the tangoicon themes

Wordpress and CO have a different target group wordpress theming is a mess as you need header / footer and special part files.

I have some ideas on how to implement a templating feature:

  1. Refactor core css files in 2 parts
    • positions of UI components
    • layout of components (colors, background-images)
    • make it possible to add an additional custom css file which can be defined in the config file
  2. Refactor UI to use either extjs or jQueryUI (both have themes support) and use the themes the libraries offer.

The second idea has the positive side effect of reusing existing themes.

PS: Many users which evaluated piwik say "wow", but please change the menustructure.
Especially the horinzontal menu confused many of my customers, we should use vertical menus (as they are standard on many systems)

comment:9 Changed 4 years ago by vipsoft (robocoder)

Thanks Kay. I recently looked at various CMS packages, so I'll comment while this is somewhat fresh in my mind.

  1. Refactoring the CSS.
  • generally agree that this is a good idea; the jQueryUI CSS framework takes a similar approach to separate widget-specific classes (dimensions, visibility, positioning, margins, padding) from theme-specific classes (text colors, backgrounds, fonts, icons)
  • being able to add custom CSS files (and javascript files) will be addressed in #660
  • a CMS may allow themes to replace the "template" used by a module; in Piwik, we must take into consideration that a module may have multiple views; my thought would be to add a hook in Piwik_View::factory(), or look in the current theme's folder for a corresponding custom view (or perhaps a controller, if themes are installed as plugins)
  • wordpress's add_action() is very similar to Piwik's template_css_import and template_js_import hooks, but more granular, e.g., admin_head, admin_footer, ...
  1. Tango icon theme.
  • Assuming the icon size isn't an issue, someone would have to see what Piwik icons are missing from the base set. Missing icons are an issue if the goal is to have a uniform icon theme. It may be necessary to enlist an icon designer as it appears the Tango project hasn't been active since 2007 (although one of the contributors appears to be working on Mango, aka Tango-NG).
  • The icon naming specification could be used as the css class name when defining a css sprite, but doesn't offer guidance wrt naming the css sprite file (see #965); perhaps, "sprite-{category}.png", e.g., sprite-flags.png
  1. We already adopted jQueryUI and the 'base' theme, and replaced the jquery calendar widget with the jQueryUI datepicker widget. (To be released in Piwik 0.5.)
  • There is some functional overlap between Tango and jQueryUI's framework icons. They differ in image size -- a choice should be made depending on the size of neighboring text.
  1. Menus.
  • To be addressed in #1028.

comment:10 Changed 4 years ago by kaystrobach

if jQuery UI is already loaded piwik should use the icons of jQuery as the are easy to understand and it's very easy to theme them.

-> i think it's not the first priority to change the html templates directly, but theming with custom CSS and JS would be great and easy enough to find desingners

-> i assume, changing a view can be done in an extension by making a fork ... ;)

Oh, btw is it possible to switch piwik dashboard to 2 columns, this would be great for integration in other webapplications (as screensize is limited)

comment:11 Changed 4 years ago by kaystrobach

wordpress theming articles:

german: http://t3n.de/magazin/wenigen-schritten-individuellen-blog-design-eigene-223037/

english: http://codex.wordpress.org/Theme_Development

But i think css theming would be enough.

comment:12 Changed 4 years ago by kaystrobach

comment:13 Changed 4 years ago by kaystrobach

comment:14 Changed 4 years ago by vipsoft (robocoder)

  • Description modified (diff)

comment:15 Changed 4 years ago by kaystrobach

After taking a look into the hook list i found an easy way of theming:
http://www.kay-strobach.de/typo3conf/piwik/piwik/index.php?module=CoreHome&action=index&idSite=1&period=day&date=yesterday#module=Dashboard&action=embeddedIndex&idSite=1&period=day&date=yesterday

I've done 2 things in this example:
modified menustructure and changed css.

comment:16 Changed 4 years ago by vipsoft (robocoder)

Right, that would be an example of "... if themes are installed as plugins" that I mentioned in comment:9.

That said, those hooks may be deprecated by #660.

comment:17 Changed 4 years ago by kaystrobach

ok, so the minify group has to make a statement on hook naming and passed parameters.
(btw. i think compression should also be possible with the current hook ...)
If this is done an example plugin for templating can be released and designers can start working ;)

yes, i prefer the philosphie "every thing is a plugin" ;) this reduces management overhead.

comment:18 Changed 4 years ago by vipsoft (robocoder)

In [1642], the layout was moved from Dashboard/templates/index.tpl to Dashboard/Controller.php.

In a theme-able environment, it might make sense to move the layout into a separate view file (e.g., layout.tpl). This depends on whether the View factory hook idea will fly. Otherwise, we could always add a getDefaultLayout hook.

comment:19 Changed 4 years ago by kaystrobach

I think the normal way for theming will be to change the css and add some JS.
This will allow a maximum of compatibility.

In my opinion less then 5% of the users want to change the html structure, most of them just wanna customize the look - and adding custom css files will fit there needs.

What do you think about making a survey about this? - Just add a new message in the next piwik release which asks the user about feature whiches - and theming in special?

comment:20 Changed 4 years ago by matt (mattab)

I agree with the general ideas proposed in the thread:

  • Focus on CSS refactoring: CSS defining layout (dimensions, visibility, positioning, margins, padding) and presentation (text colors, backgrounds, fonts, icons) are in specific CSS classes. This requires significant CSS refactoring work on Piwik, as well as modifications of JS scripts.
  • Have the theme be limited in scope at first: possible to add CSS, modify the layout file, add JS files. As themes are built, we can increase the scope of themes and accomodate theme designers
  • Build themes as plugins at first, as this makes sense and reduces complexity. If this is a limitation later, we can re-assess.

Thoughts?

comment:21 Changed 4 years ago by kaystrobach

comment:22 Changed 4 years ago by matt (mattab)

  • Priority changed from normal to critical

Increasing priority, one of the most requested features.

comment:23 Changed 4 years ago by greg (gka)

I just wanted to note that the non-html plugins like the charts or maps also are affected by theming. They're displaying labels and tooltips, and it should be able to customize those to the themes fonts and colors. Since flash widgets can't be styled via CSS in most cases, we have to think about some common properties for each theme, that can be inserted into PHP or templates.

Possible properties are:

  • page background color
  • text color
  • base font + size
  • tooltip colors (bg, border, text)
  • chart element colors (pie,bar,line), color scale (map)

This reminds me a bit of the theming of operating systems like windows.

To me, there are three options in dealing with these theme properties:

  • property definition in css that follows a special semantics which can be parsed via PHP and then be used in controllers and templates if necessary. for instance we define a css class .piwik-tooltip-layout that contains the colors and fonts used in chart tooltips
  • property definition in the main css-file, but inside a block comment on top of the file, like /* @tooltip-background #F4F0F0 */
  • property definition in some kind of config.php that lays inside the theme directory

comment:24 Changed 4 years ago by kaystrobach

mhmm thats, why i asked to use extjs for the backend of piwik ....

comment:25 Changed 4 years ago by matt (mattab)

kaystrobach, please take a look at piwik codebase. Moving to something like extjs is not something we will consider in the near future considering the large amount of code that would have to be rewritten.

greg, good points. Also one must have customization is the logo (replace Piwik logo in header + PDF reports).

comment:26 Changed 4 years ago by vipsoft (robocoder)

I propose we add an ExampleTheme plugin, and add the following hooks:

  • theme-specific layout - see comment:18; this provides a theme with the general ability to substitute their own .tpl files at runtime
    • Piwik_View::factory
    • Smarty function replacement for {include} tags
  • theme-specific AssetManager - see #1527; this provides a theme with the general ability to replace .css and .js files, order them in a specific manner, etc.

If we then create a logo.tpl that other .tpl files can include, then a theme can substitute its own logo.tpl at runtime.

(PluginsManager.php already triggers the deletion of assets and compiled templates when plugins are activated/deactivated.)

comment:27 Changed 4 years ago by vipsoft (robocoder)

  • Milestone changed from Features requests - after Piwik 1.0 to 5 - Piwik 1.1
  • Owner set to vipsoft

Changed 4 years ago by kaystrobach

XGA with Piwik in TYPO3 Backend

comment:28 Changed 4 years ago by kaystrobach

as seen in the screenshot, putting piwik into a cms backend needs some more space. Is there any way to set the column count in the dashboard to 2?

comment:29 Changed 4 years ago by vipsoft (robocoder)

Kay: The number of columns in the dashboard is intertwined with the default dashboard layout.  Changing the logic behind it isn't something I plan to (nor do I think we should) change via theming.

In your case, the site selector/creator takes up a lot of screen real estate as a static pane.  I would make it slide out when needed.

comment:30 Changed 4 years ago by kaystrobach

i didn't thought, that this should be done with a theme ;)
I thought that there could be an option in the config file. (I know a somehow likely option from netvibes - not a statistic tools, but a rss reader and dashboard).

I added an option to open the iframe in a new Ext.JS window with the size of the complete browser window. (Ext.JS is part of TYPO3 and so available for me ;'))

comment:31 Changed 4 years ago by vipsoft (robocoder)

I'll create a new ticket for the dashboard enhancements.

comment:32 Changed 4 years ago by vipsoft (robocoder)

Ticket already exists #1559.

comment:33 Changed 4 years ago by kaystrobach

thanks

comment:34 Changed 4 years ago by vipsoft (robocoder)

  • Priority changed from critical to major

comment:35 Changed 4 years ago by vipsoft (robocoder)

  • Milestone changed from 1.1 - Piwik 1.1 to 1.2 - Piwik 1.2
  • Priority changed from major to normal

Moving this to 1.2.

comment:36 Changed 3 years ago by matt (mattab)

  • Milestone changed from 1.2 - Piwik 1.2 to Piwik 1.x

comment:37 Changed 3 years ago by matt (mattab)

Maybe, to implement theming, we will have to reorganize assets in consistent folders: #1385

comment:38 Changed 3 years ago by matt (mattab)

  • Milestone changed from 1.x - Piwik 1.x to Feature requests

comment:39 Changed 3 years ago by vipsoft (robocoder)

Ok, let's roll #1385 into this ticket. If we implements themes as plugins:

  • Move contents of themes/default/ into plugins/CoreHome/ (or CoreTheme)
  • Reorganize static assets for consistency:
    • plugins/X/css
    • plugins/X/js
    • plugins/X/images
    • plugins/X/templates

comment:40 Changed 2 years ago by matt (mattab)

  • Description modified (diff)

Updating ticket description with proposed implementation plan for the THEME feature in Piwik.

If you are a CSS designer, please post a comment here. we plan to build Themes as simple plugins that would return extra CSS to change colors and positions. Comment here if you'd like to build such a theme!

comment:41 Changed 2 years ago by vipsoft (robocoder)

  • Description modified (diff)

For discussion once the ball starts rolling on this feature:

  • clarify "are themes GPL too?" (Depends on the theme)
  • how to determine theme compatibility?
  • what happens if core css and/or templates change? (Eg graceful degradation)


comment:42 Changed 19 months ago by AlberT

My opinion is to make the theme's plugin override everything related to the View .. not only JS ans CSS .. templates also matter ... A simple graceful degradation will make a template override the core default one, otherwise the core is used ..

It looks simple and versatile

Last edited 19 months ago by AlberT (previous) (diff)

comment:43 Changed 9 months ago by matt (mattab)

  • Resolution set to duplicate
  • Status changed from new to closed

We are implementing Theming for Piwik 2.0! to achieve this, we have migrated to Twig, we are improving the CSS and templates, and making Theming the easiest possible (while allow full customization including graphs colors etc.). we also migrated to LESS #4052

comment:44 Changed 9 months ago by matt (mattab)

The new ticket for Theming is #3942

comment:45 Changed 8 months ago by matt (mattab)

Piwik 2 supports theming. Please use Piwik from GIT. Then go to Settings>Themes> and try enable PleineLune theme.

For help on how to create themes, see: https://github.com/piwik/piwik/tree/master/plugins/PleineLune#create-a-theme-for-piwik

We are looking forward to seeing your themes!

comment:46 Changed 5 months ago by matt (mattab)

see follow up ticket (VERY exciting!!) #4127 New Default Theme for Piwik

Note: See TracTickets for help on using tickets.