New subject: [xwiki-devs] [Statistics][Proposal] Improve the statistics page

16 Oct 2007

Hi all,

The statistics page needs improvement. See
http://jira.xwiki.org/jira/browse/XE-37 for a brief introduction. I
propose we take the following steps:

1) Extend the xwiki core api with:

package com.xpn.xwiki.api;

/**
 * Statistics api
 */
public class StatsService extends Api{
 /**
  * Retrieve all-time statistics for top pages
  *
  * @param action Can be "view", "save", etc.
  * @param space The space from which to consider pages. If space is the
empty string or null then the whole wiki is considered.
  * @param count The number of page stats to retrieve.
  *
  * @return a list of document stats
  */
 List<DocumentStats> getTopPages(String action, String space, int count){}
List<DocumentStats> getMonthTopPages(String action, String space, Date
month, int count){}
 List<DocumentStats> getDayTopPages(String action, String space, Date day,
int count){}

 /**
  * Retrieve all-time statistics for top contributors
  *
  * @param space The space in which to look for contributions. If space is
the empty string or null then the whole wiki is considered. NOTE:
currently the database stores statistics regarding only the whole wiki
(e.g. the number of saves a user has made in the entire wiki, but not at
space level). To implement space-level contributor statistics I need to
consider page history, which is time-consuming (e.g. for each page in
space, for each history entry ...). I go for offering (at least for the
moment) user stats only at wiki level by removing this parameter.
  * @param count The number of user stats to retrieve
  *
  * @return The list of user stats
  */
 List<VisitStats> getTopContributors(String space, int count){}
 List<VisitStats> getMonthTopContributors(String space, Date month, int
count){}
 List<VisitStats> getDayTopContributors(String space, Date day, int
count){}

 /**
  * Retrieve the evolution of the specified activity over a period of time
*
  * @param action Can be "view", "save", etc.
  * @param docOrSpace The (full)name of a document or space or the empty
string / null for the whole wiki
  * @param startDay The start date
  * @param endDay The end date
  * @param dayInterval The sample rate (e.g. at every 2 days)
  *
  * @return A map of (date, action count) pairs.
  */
 Map<Date, Integer> getActivityPerDay(String action, String docOrSpace,
Date startDay, Date endDay, int dayInterval){}
 Map<Date, Integer> getActivityPerMonth(String action, String docOrSpace,
Date startMonth, Date endMonth, int monthInterval){}
 Map<Date, Integer> getActivityPerYear(String action, String docOrSpace,
Date startYear, Date endYear, int yearInterval){}
}

2) Add in the com.xpn.xwiki.api.XWiki the following method:

public StatsService getStatsService(){}

3) Extend the com.xpn.xwiki.stats.api.XWikiStatsService with:

List<DocumentStats> getTopPages(String action, String space, int count,
XWikiContext context){}

List<DocumentStats> getMonthTopPages(String action, String space, Date
month, int count, XWikiContext context){}

List<DocumentStats> getDayTopPages(String action, String space, Date day,
int count, XWikiContext context){}

List<VisitStats> getTopContributors(String space, int count, XWikiContext
context){}

List<VisitStats> getMonthTopContributors(String space, Date month, int
count, XWikiContext context){}

List<VisitStats> getDayTopContributors(String space, Date day, int count,
XWikiContext context){}

Map<Date, Integer> getActivityPerDay(String action, String docOrSpace,
Date startDay, Date endDay, int dayInterval, XWikiContext context){}

Map<Date, Integer> getActivityPerMonth(String action, String docOrSpace,
Date startMonth, Date endMonth, int monthInterval, XWikiContext context){}

Map<Date, Integer> getActivityPerYear(String action, String docOrSpace,
Date startYear, Date endYear, int yearInterval, XWikiContext context){}

4) Adjust the com.xpn.xwiki.stats.impl.XWikiStatsServiceImpl

5) In com.xpn.xwiki.api.XWiki there are 2 methods related to statistics:

* getCurrentMonthXWikiStats
* getRefererText

We could duplicate this methods in the StatsService and deprecate them in
XWiki.

6) Currently the xwiki chart macro doesn't support hidden (aka not visible
in page) data sources. This is how the char macro is used now:

{chart:type=time|source=type:table;table_number:4;...}

I propose to extend the macro to allow the following usage:

{chart:type=time|source=type:table;...}
{table}
       | Series1 | Series2
2001-2 |   181.8 | 129.6
2001-3 |   167.3 | 123.2
2001-4 |   153.8 | 117.2
{table}
{chart}

This extension consists in:
* add chart macro's content to the parameters map given to the data source
* adjust the TableDataSource to use this content when no table_number is
specified

7) Create the xwiki-platform-applications/statistics application to host
the statistics related pages. Different stats will be displayed using
special panels that can be inserted into a page (see
http://llunati.xwiki.com/xwiki/bin/view/Albatross/PanelInPage for a
sample). I propose to use the Panels space for this pages (e.g use the
path src/main/resources/Panels). Vincent could help me with this.

8) Create the Stats page (aka the UI). The Stats page is now in the XWiki
space, meaning it is not accessible for the regular user (event when the
statistics module is enabled). I don't really like this. I like more how
jira.xwiki.org shows me its stats even when I'm not logged in. In the
future, I think it would be great if the users could see page/space/wiki
stats much the same they see now the xwiki code of the page (e.g. Show >
Stats). For the moment I propose to make only a single stats page
(XWiki.Stats).

That's all. WDYT?
-Marius