@robocoder opened this Issue on March 29th 2010 Contributor

An annotation is a Text note set a specific date. Add the ability in Piwik to annotate reports, e.g., a spike in traffic attributed to a slashdot story.

These annotation would appear with a marker on the Graph, and would be listed below the graph on click on "Annotations" button, and could also be created/queried via the API.

@anonymous-matomo-user commented on March 29th 2010

I think the emphasis of this ticket should be on the creation of a Piwik Calendar - as per PeterB's original suggestion. The ability to annotate the calendar with known events is an addon feature.

Can I suggest that the name of ticket (Summary field) be changed to reflect this?

@anonymous-matomo-user commented on March 12th 2011

This feature would be really handy. A good starting point for the UI component might be Adam Shaw's fullcalendar jQuery plugin. It is a pretty nice calendaring interface with good documentation and a flexible api.


@mattab commented on July 8th 2011 Member

See also the request in: http://forum.piwik.org/read.php?3,79114
refs #3110

@anonymous-matomo-user commented on December 20th 2011

I second Adam Shaw's plugin. It's amazing, we have worked with it forever. This is a really great potential feature. I constantly run into cases where this would be worth it's digital weight in gold.

@mattab commented on August 21st 2012 Member

capedfuzz, what would be your take on this one?

@anonymous-matomo-user commented on October 12th 2012

This would be a good feature for me.

@mattab commented on October 27th 2012 Member

This specification is very similr to the google analytics implementation of annotations, simply because -- once more -- Google has done a great job at the UI and integration into the graph. I'm sure they havent invented it neither, but we shall copy their idea and extend it with Piwik features in mind! Here are the specifications for the actually-very-useful Annotations feature.

Annotations, Specification

Data structure & features:

  • we can simply store annotations in piwik_option for a given site, as a json structure, rather than create a new table... Thoughts?
    The annotation have a TEXT field and unlimited length.
    Annotations are recorded for a given website. There can be unlimited number of annotations per website.
    All annotations created by all users for a given site are shown to all users. ie. Users share annotations per site.
  • About the day field:
    • Annnotations can be set for a given "day". Similarly to GA, there is a Day field that opens a calendar. We dont have to open the calendar, a simple INPUT field would do as well (if calendar non trivial)
    • When looking at weekly or monthly graph, the annotations would still be set for a given day, the first day of the period.
  • It is also possible to "Star" an annotation. Indeed, it is very useful to move up annotations in the list and always see them as they can be more important.
    This is similar to GA and allows to easily spot major changes if users put annotations on every day (some users will use piwik annotations as a task tracking log for sure).


Ability for View & Admin (non anonymous) users to view, create, edit, delete Annotations.
"Admin" users for a site, can edit & delete annotations of any users to this website.

  • Super User can edit & delete all.


Annotations can be added, updated, deleted via a New Annotations API.

  • There should be a basic API to create/edit/delete annotations since I can see how it could be very useful to other clients or tools to log daily data in piwik!
  • Maybe annotations could be in a new plugin to keep things clean and simple.
  • Having a new plugin would make the API name good eg. Annotations.add Annotations.update Annotations.delete Annotations.star for example.
  • the plugin could enrich the datatable templates to add the annotation features using template hooks.
  • There will be some other code changes outside this new plugin, eg. JQPlot to display the markers on the X axis.

Annotations availability in the UI:

  • Annotations are automatically available below each Evolution Graph. Maybe we could add a new icon, on the right of the footer, on the left of the Limit selector.
    • For example this pin icon . The fact it has no background will make it look different from the others on the left, which is good because displaying annotations is a different kind of action.
    • On the right of this icon we could write "Annotations"
    • On click, it would display below the graph, above the footer icons, the list of annotations, in a table like list that will show, all annotations for all dates of the current graph. The list can be 10 or 100 elements long.
    • We do not paginate but simply display all annotations in a list.
    • If the icon is clicked again the list is hidden.
  • The list displayed would have Star, Date, Annotation text, Edit link
  • When editing, the "delete" link would be visible (similar to GA)
  • When an annotation is starred, the white icon becomes yellow.
  • when there is at least one annotation for a given date, a small icon would be displayed on the graph next to the X axis - or "over" the X axis
  • On click of this icon on a given date, display below the annotations restricted to this date only. This is different from clicking the "Annotations" link in the footer which displays all annotations for the period.
@diosmosis commented on December 14th 2012 Member

(In [7612]) Fixes #1253, added annotations plugin that allows attaching notes to different days.


  • Modified renderers so they would render arrays better. Before, arrays were added to DataTables and array keys were either lost or ignored, now they are rendered.
  • Fixed issue w/ JSON rendering that rendered arrays when the PHP arrays didn't have contiguous keys.
  • Augmented some exception messages.
  • Added utility method processRequest to Piwik_API_Request to ease use of the class.
@mattab commented on December 14th 2012 Member

(In [7617]) Refs #1253 Change API call because format=php is broken (temporarily)

@diosmosis commented on December 14th 2012 Member

(In [7619]) Refs #1253, fix regression in PHP DataTable renderer.

@diosmosis commented on December 15th 2012 Member

(In [7624]) Refs #1253, add integration test for PHP renderer w/ array value.

@diosmosis commented on December 15th 2012 Member

(In [7626]) Refs #1253, remove svn:executable.

@diosmosis commented on December 15th 2012 Member

(In [7628]) Refs #1253, if provider determined via GeoIP plugin, display link to startpage in reports and visitor log.

@diosmosis commented on December 18th 2012 Member

(In [7648]) Refs #1253, fixes #3349, fix bugs and regressions in annotations and tweaked the UI a bit.

@mattab commented on December 18th 2012 Member

Bug report:

  • On the widget in a 3 columns dashboard, the marker displays OK.
  • Then click "Maximise widget". The markers are not moved to the proper place or refreshed in the new graph.

-> It is not possible to add annotations in the recent days as the marker will not display on the right part of the axis.

@mattab commented on December 18th 2012 Member
  • Annotations blue link should be in the same tooltip as the icon preceding it "View notes for this date range"
@diosmosis commented on December 19th 2012 Member

(In [7650]) Fixes #1253, fix bug where resizing element does not reposition evolution icons and tweak translation keys.

@diosmosis commented on December 24th 2012 Member

(In [7700]) Refs #1253, display annotation text in tooltip when hovering over evolution icon if only one annotation for date range, and when hovering over an annotation, make the corresponding evolution icon bounce.

This Issue was closed on December 24th 2012
Powered by GitHub Issue Mirror