Opened 4 years ago

Closed 16 months ago

Last modified 16 months ago

#1253 closed New feature (fixed)

Create annotations in the Graphs and list all Text notes for a given date range

Reported by: vipsoft Owned by: capedfuzz
Priority: major Milestone: 1.10 - Piwik 1.10
Component: UI - UX (AngularJS, twig, less) Keywords:
Cc: Sensitive: no

Description (last modified by matt)

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.

Change History (23)

comment:1 Changed 4 years ago by rschilt

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?

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

  • Summary changed from Annotations - event descriptions to Create annotations in the Graphs (or calendar?) - event descriptions

comment:3 Changed 3 years ago by mjpowersjr

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.

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

  • Description modified (diff)

comment:7 Changed 2 years ago by AIWebSystems

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.

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

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

capedfuzz, what would be your take on this one?

comment:9 Changed 19 months ago by mstenz

This would be a good feature for me.

comment:10 Changed 18 months ago by matt (mattab)

  • Component changed from Core to UI - UX (tpl, js, css)
  • Milestone changed from 1.x - Piwik 1.x to 1.9.2 - Piwik 1.9.2
  • Priority changed from normal to major

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 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)

Last edited 17 months ago by matt (previous) (diff)

comment:11 Changed 17 months ago by matt (mattab)

  • Description modified (diff)
  • Summary changed from Create annotations in the Graphs (or calendar?) - event descriptions to Create annotations in the Graphs and list all Text notes for a given date range

comment:12 Changed 17 months ago by capedfuzz (diosmosis)

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

(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.

comment:13 Changed 17 months ago by matt (mattab)

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

comment:14 Changed 16 months ago by capedfuzz (diosmosis)

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

comment:15 Changed 16 months ago by capedfuzz (diosmosis)

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

comment:16 Changed 16 months ago by capedfuzz (diosmosis)

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

comment:17 Changed 16 months ago by capedfuzz (diosmosis)

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

comment:18 Changed 16 months ago by capedfuzz (diosmosis)

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

comment:19 Changed 16 months ago by matt (mattab)

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.

comment:20 Changed 16 months ago by matt (mattab)

  • Annotations blue link should be in the same tooltip as the icon preceding it "View notes for this date range"

comment:21 Changed 16 months ago by matt (mattab)

  • Resolution fixed deleted
  • Status changed from closed to reopened

comment:22 Changed 16 months ago by capedfuzz (diosmosis)

  • Resolution set to fixed
  • Status changed from reopened to closed

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

comment:23 Changed 16 months ago by capedfuzz (diosmosis)

(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.

Note: See TracTickets for help on using tickets.