#format wiki
#language en
#pragma section-numbers off
#acl IanRiley:read,write,delete,revert,admin All:read
#pragma supplementation-page on

<<ContentsAndAppendices>>

= ViewLog, ViewLogs, ViewHistory and Views =

== Background and rationale ==

MoinMoin logs page events and edits, but only records user information for edits. The macro, `<<Hits>>`, can insert the number of views or saves for a page or the whole wiki, but cannot exclude views/saves from the current user. Also, all views are recorded even if they occur within a short period after a previous view, such as before and after clearing a wiki message, so these do not represent separate reading activity.

It would be useful in a number of situations to have a record of page views by viewer and for that record not to include duplicate views made within the timeframe of typical reading activity. This could be useful for pages maintained by a single user who wants to know the number of views by other users. Also, for a page shared among a group of users, it might be useful to check if all members of the group have viewed the page. 

== Description ==

!ViewLog is a macro that establishes and updates a log file for page views recording user details. The macro inserts a datestamp and user name into the page, unless set to silent. It can be controlled to log all views, or only views that do not occur within a defined interval (10 minutes by default). A transient record of page views is created in the user's session, with the timestamp and revision number of the last logged page view. These data are compared the time and revision of the current view to decide if it should be logged. A list of up to 100 pages can be recorded within a session. If viewed pages exceed 100, the earliest viewed page is deleted from the list. The list only lasts as long as the session and is renewed if the user logs off. It can also be cleared by the macro itself.

The log file, `view-log`, is stored locally in the page folder. It is created and accessed using the `viewlog.py` module imported from `wiki/data/plugin/logfile` (see under prerequisites below).

!ViewLogs is a macro to display a list of pages with view logs. The list is by default a comma separated list, or if requested, a list in regex format to be use in the !ViewHistory macro.

!ViewHistory is a macro to display a table of page views for each user, giving the date of the most recent logged view. A specific page or a group of pages can be specified.

Views is a macro to insert a count of page views for the current, other or all users.

== Prerequisite ==

For these macros to work the !ViewLog class is imported from `viewlog.py` in `wiki/data/plugin/logfile`. This folder must also contain the standard `__init__.py` for plugin modules. The file is provided for download as `viewlog-logfile-1.0.py` and must be renamed to `viewlog.py` when installing.

This plugin parallels the inbuilt logfile modules `eventlog.py` and `editlog.py` found in `MoinMoin/logfile`. 
        
`<<ViewLog>>` marco must run on the page for the `view-log` file to be created and for views to be logged. Without this, the macros `<<ViewLogs>>` `<<ViewHistory>>` and `<<Views>>` will not function.

== Usage ==

=== <<ViewLog>> ===

{{{

<<ViewLog>>; <<ViewLog()>>
       
<<ViewLog([silent]|[[silent=]"1"|"true"|"silent"], 
          [all]|[[all=]"1"|"true"|"all"],
          [clear]|[[clear=]"1"|"true"|"clear"],
          [[offset=]integer])>>'

silent or silent="arg": If set or arg equal to '1', 'true' or 'silent', no information is inserted. If unset, defaults to false, and view information is inserted.

all or all="arg": If set or arg equal to '1', 'true' or 'all', all views are recorded. If unset, defaults to false and the view is only recorded if page has not been viewed before within the users session, or the view as more the 10 minutes ago (600 seconds or as set by offset). 

clear or clear="arg": If set or arg equal  to '1', 'true' or 'clear', session records are cleared (only used during testing). If unset, defaults to false and no action is taken.

offest=integer: Time offset, an integer greater than 0 in seconds, during which repeat page views for a user within a session are not logged. Defaults to 600 (i.e 10 minutes).

}}}

=== <<ViewLogs>> ===

{{{

<<ViewLogs>>; <<VieLogs()>>

<<ViewLogs([[page=]pagename][[regex=]"true"|"1"|"regex"]

page=pagename: See <<ViewHistory>> below for setting pagename. Setting it gives a list of matching pages with a view log initiated by <<ViewLog>> macro. By default this isa comma separated list, unless regex parameter is set.

regex=arg: Can be set to "true", "1" or "regex" to give list of pages as a regex expression that can be used in page=pagename in <<ViewHistory>> macro or, in this macro.

}}}

=== <<ViewHistory>> ===

{{{

<<ViewHistory>>; <<ViewHistory()>>

<<ViewHistory([[page=]pagename])>>

page=pagename: A target pagename can be specified, or if unset, defaults to the current page. Pagename can be set to a reqex to specify multiple pages, in which case the parameter string must begin with '^'. If a single page (specified or default) does not have a view log initiated by <<ViewLog>> macro, a advice to this effect is inserted. If multiple pages are specified then only pages with view logs are include, unless no logs are found and then the advisory message is inserted. Views history can only be summarised for pages for which the user has admin rights.

}}}

=== <<Views>> ===

{{{

<<Views>>; <<Views()>>
       
<<Views([[viewers=]"self"|"other"|"all")>>

viewers=arg: Can be set to "self" to insert number of views logged for current user, "other" to insert number of views for users other than the current user, or "all" to insert total number of views.

}}}


== Download & Release Notes ==
|| Download || Release Version || Moin Version || Release Notes ||
|| [[attachment:viewlog-logfile-1.0.py]] || 1.0 || 1.9.2  ||  ||
|| [[attachment:ViewLog-1.2.py]] || 1.2 || 1.9.2  ||  ||
|| [[attachment:ViewLogs-1.0.py]] || 1.0 || 1.9.2  ||  ||
|| [[attachment:ViewHistory-1.4.py]] || 1.4 || 1.9.2  ||  ||
|| [[attachment:Views-1.2.py]] || 1.2 || 1.9.2  ||  ||

For installation, rename files to remove version number (e.g. `-1.0`).

== Examples ==

{{{
<<ViewLog()>>
}}}

<<ViewLog(silent)>>
Viewed 2013-01-15 18:41:32 by !IanRiley.


{{{
<<ViewLogs('^View.', regex)>>
}}}

##<<ViewLogs('^View.', regex)>>

'^(!ViewLog.py)'

{{{
<<ViewHistory()>>
}}}

##<<ViewHistory()>>

'''Page view history'''

Page views by user with time of most recently logged view.

||'''Page'''||'''User'''||'''Viewed'''||'''Views'''||
||!ViewLog.py||!IanRiley||2013-01-15 18:34:16||20||
||!ViewLog.py||anon||2012-12-19 19:50:04||1||

{{{
Views by the current user = <<Views(self)>>
}}}

##Views by the current user = <<Views(self)>>
Views by the current user = 20

== History ==

See individual source files for details of version history.

Developed with inspiration and MoinMoin code from:

 . @copyright: 2006-2008 MoinMoin:ThomasWaldmann,
 . @copyright: 2007 MoinMoin:ReimarBauer
 . @copyright: 2000-2004 Juergen Hermann <jh@web.de>
 . @copyright: 2000-2001 Richard Jones <richard@bizarsoftware.com.au>

== Copyright ==

 . @copyright: 2012 Ian Riley <ian@riley.asia>

== License ==

GNU GPL, see COPYING for details.

== Known issues and limitations ==

 * None known

-----

 Hits:: <<Hits>>