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

[robocoder]

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]

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]

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.

http://arshaw.com/fullcalendar/

[mattab]

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

[anonymous-matomo-user]

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]

capedfuzz, what would be your take on this one?

[anonymous-matomo-user]

This would be a good feature for me.

[mattab]

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

Permissions:

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.

API:

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
  • I can propose this icon maybe? http://www.iconfinder.com/icondetails/14541/16/1_grey_marker_rounded_icon
  • When at least one annotation on a given day is starred, the icon would become highlighted such as: http://www.iconfinder.com/icondetails/14555/16/marker_orange_rounded_yellow_icon
• 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]

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

Notes:

• 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]

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

[diosmosis]

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

[diosmosis]

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

[diosmosis]

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

[diosmosis]

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

[diosmosis]

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

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