%META:TOPICINFO{author="TWikiContributor" date="1353572759" format="1.1" version="$Rev$"}%
---+!! !RecentVisitorPlugin
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/RecentVisitorPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/RecentVisitorPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
%SHORTDESCRIPTION%

---++ Introduction

This plugin shows statistics of recent visitors to a TWiki site. The time of last visit and the IP address used can be shown of individual users. The recent report shows latest visitors in chronological order.

---++ Syntax Rules

---+++ Most recent visit of an individual

=%<nop>RECENTVISITOR{ action="user" ... }%=

| *Parameter* | *Description* | *Default* |
| ="user"= or%BR% =action="user"= | Show statistics of individual user. | (none) |
| =name="..."= | %SYSTEMWEB%.WikiName of person | (current user) |
| =format="..."= | Format of report. Supported tokens:%BB% =$date= - date of last visit%BB% =$time= - time of last visit (GMT)%BB% =$ago= - how long ago%BB% =$ip= - IP address (only shown to non-administrators if enabled in configure)%BB% =$n=, =$nop=, =$quot=, =$percnt=, =$dollar= - standard %SYSTEMWEB%.FormatTokens | ="Last seen $ago ago"= |
| =notfound="..."= | Message shown if user is not found. | ="Never seen"= |

---+++ Report of recent visitors

=%<nop>RECENTVISITOR{ action="recent" ... }%=

| *Parameter* | *Description* | *Default* |
| ="recent"= or%BR% =action="recent"= | Show statistics of most recent visitors. | (none) |
| =format="..."= | Format of each line of the report. Supported tokens:%BB% =$username= - login name of user%BB% =$wikiname= - %SYSTEMWEB%.WikiName of user%BB% =$wikusername= - !WikiName prefixed with %USERSWEB% web name%BB% =$date= - date of last visit%BB% =$time= - time of last visit (GMT)%BB% =$ago= - how long ago%BB% =$ip= - IP address (only shown to non-administrators if enabled in configure)%BB% =$n=, =$nop=, =$quot=, =$percnt=, =$dollar= - standard %SYSTEMWEB%.FormatTokens | ="   * $wikiusername%BR%      last seen $ago ago"= |
| =separator="..."= | Separator between lines. Standard %SYSTEMWEB%.FormatTokens are expanded. | ="$n"= (newline) |
| =limit="..."= | Limit the number of lines. | ="10"= |

See also VarRECENTVISITOR documentation for %SYSTEMWEB%.TWikiVariables.

---++ Examples

---+++!! Example: Show most recent visit of %USERSWEB%.TWikiAdminUser

<table border="0" cellpadding="10" cellspacing="0">
<tr bgcolor="#dddddd">
<th> *You type* </th>
<th> *You get (if installed)* </th>
<th> *Simulated example* </th>
</tr><tr bgcolor="#f4f4f8">
<td valign="top">
<verbatim>
%RECENTVISITOR{
 action="user"
 name="TWikiAdminUser"
 format="Last seen $ago ago ($date 
$time)"
}%
</verbatim>
</td><td valign="top">
%RECENTVISITOR{
 action="user"
 name="TWikiAdminUser"
 format="Last seen $ago ago ($date $time)"
}%
</td><td valign="top">
 Last seen 3 weeks ago (2012-11-03 06:22)
</td></tr></table>

---+++!! Example: Show recent visitors, default bullet list report

<table border="0" cellpadding="10" cellspacing="0">
<tr bgcolor="#dddddd">
<th> *You type* </th>
<th> *You get (if installed)* </th>
<th> *Simulated example* </th>
</tr><tr bgcolor="#f4f4f8">
<td valign="top">
<verbatim>
%RECENTVISITOR{
 action="recent"
 limit="5"
}%
</verbatim>
</td><td valign="top">
%RECENTVISITOR{
 action="recent"
 limit="5"
}%
</td><td valign="top">
   * [[%TOPIC%][NielsBohr]] last seen moments ago
   * [[%TOPIC%][KlausFuchs]] last seen 3 hours ago
   * [[%TOPIC%][AlbertEinstein]] last seen 1 day ago
   * [[%TOPIC%][EnricoFermi]] last seen 15 days ago
   * [[%TOPIC%][DavidBohm]] last seen 2 month ago
</td></tr></table>

---+++!! Example: Show recent visitors, table report

<table border="0" cellpadding="10" cellspacing="0">
<tr bgcolor="#dddddd">
<th> *You type* </th>
<th> *You get (if installed)* </th>
<th> *Simulated example* </th>
</tr><tr bgcolor="#f4f4f8">
<td valign="top">
<verbatim>
%RECENTVISITOR{
 action="recent"
 format="| $wikiusername | $date |"
 limit="5"
}%
</verbatim>
</td><td valign="top">
%RECENTVISITOR{
 action="recent"
 format="| $wikiusername | $date |"
 limit="5"
}%
</td><td valign="top">
| [[%TOPIC%][NielsBohr]] | 2012-02-03 |
| [[%TOPIC%][KlausFuchs]] | 2012-02-03 |
| [[%TOPIC%][AlbertEinstein]] | 2012-02-02 |
| [[%TOPIC%][EnricoFermi]] | 2012-01-19 |
| [[%TOPIC%][DavidBohm]] | 2011-11-27 |
</td></tr></table>

---+++!! Example: Show recent visitors with geolocation

This example uses the TWiki:Plugins.GeoLookupPlugin to resolve IP addresses to [[Wikipedia:Geolocation][geolocations]].

<table border="0" cellpadding="10" cellspacing="0">
<tr bgcolor="#dddddd">
<th> *You type* </th>
<th> *You get (if installed)* </th>
<th> *Simulated example* </th>
</tr><tr bgcolor="#f4f4f8">
<td valign="top">
<verbatim>
| *Name* | *Last seen* | *Where* |
%RECENTVISITOR{
 action="recent"
 limit="5"
 format="| $wikiusername | $ago ago
 | $percntGEOLOOKUP{$ip}$percnt |"
}%
</verbatim>
</td><td valign="top">
| *Name* | *<span style="white-space:nowrap">Last seen</span>* | *Where* |
%RECENTVISITOR{
 action="recent"
 limit="5"
 format="| $wikiusername | $ago ago | $percntGEOLOOKUP{$ip}$percnt |"
}%
</td><td valign="top">
| *Name* | *<span style="white-space:nowrap">Last seen</span>* | *Where* |
| [[%TOPIC%][NielsBohr]] | moments ago | Oak Ridge, TN, USA |
| [[%TOPIC%][KlausFuchs]] | 3 hours ago | Cupertino, CA, USA |
| [[%TOPIC%][AlbertEinstein]] | 1 day ago | Oak Ridge, TN, USA |
| [[%TOPIC%][EnricoFermi]] | 15 days ago | Los Alamos, TN, USA |
| [[%TOPIC%][DavidBohm]] | 2 month ago | Los Alamos, NM, USA |
</td></tr></table>

---++ Plugin Installation &amp; Configuration

__Note:__ You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section.

   * Or, follow these __manual installation__ steps:
      * Download the ZIP file from the Plugins home (see below).
      * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
        | *File:* | *Description:* |
        | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
        | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
      * Set the ownership of the extracted directories and files to the webserver user.
      * Install the dependencies (if any).

   * Plugin __configuration and testing__:
      * Run the [[%SCRIPTURL{configure}%][configure]] script and enable the plugin in the __Plugins__ section.
      * Configure additional plugin settings in the __Extensions__ section if needed:
        %BR% =$TWiki::cfg{Plugins}{RecentVisitorPlugin}{Debug} = 0;      # debug flag, 0 or 1=
        %BR% =$TWiki::cfg{Plugins}{RecentVisitorPlugin}{ShowIP} = 0;     # show IP address, 0 or 1=
        %BR% =$TWiki::cfg{Plugins}{RecentVisitorPlugin}{OnlyAdmins} = 0; # show reports to administrators only, 0 or 1=
      * Test if the installation was successful: See example above.

---++ Plugin Info

   * One line description, is shown in the %SYSTEMWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = Show statistics of recent visitors to the TWiki site

|  Plugin Author: | TWiki:Main.PeterThoeny, [[http://twiki.org/][TWiki.org]] |
|  Copyright: | &copy; 2011-2012 TWiki:Main.PeterThoeny <br /> &copy; 2011-2012 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2012-11-22 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  2012-11-22: | TWikibug:Item7020: Categorize RECENTVISITOR TWiki Variable; doc enhancements |
|  2011-06-06: | TWikibug:Item6725: Plugins: Change global package variables from "use vars" to "our" -- TWiki:Main.PeterThoeny |
|  2011-05-14: | TWikibug:Item6701: Small fix in Config.spec -- TWiki:Main.PeterThoeny |
|  2011-05-01: | TWikibug:Item6701: Fix small warning issue if plugin is run by a shell script |
|  2011-02-03: | TWikibug:Item6646: Initial version |
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.1 |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  TWiki:Plugins.Benchmark: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/RecentVisitorPlugin |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/RecentVisitorPluginDev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/RecentVisitorPluginAppraisal |

__Related Topics:__ VarRECENTVISITOR, %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.DeveloperDocumentationCategory, %SYSTEMWEB%.AdminDocumentationCategory, %SYSTEMWEB%.TWikiPreferences

%META:FILEATTACHMENT{name="twiki-logo-80x40-t.gif" attachment="twiki-logo-80x40-t.gif" attr="h" comment="" date="1296756257" path="twiki-logo-80x40-t.gif" size="1999" user="TWikiContributor" version="1"}%
