%META:TOPICINFO{author="TWikiContributor" date="1420676674" format="1.1" version="$Rev$"}%
---+!! Where-Is Plugin
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/WhereIsPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/WhereIsPluginDev.
   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" depth="2" }%
</div></sticky>
%SHORTDESCRIPTION%

---++ Introduction

<div style="float:left; margin-right: 20px; width: 64px;">
<img src="%ATTACHURLPATH%/whereis-64.png" alt="whereis-64.png" width="64" height="64" />
</div>
It it is useful to know where members of an organization are, especially with employees traveling between offices and visiting clients. This plugin makes it easy to see where users are, or where they have been recently while accessing the TWiki site.

Locations are tracked by IP address. A location can be named, such as "Cupertino office", "Tokyo office", "Brian's home office", etc. A new location is automatically established if the %IF{ "istopic 'GeoLookupPlugin'" else="TWiki:Plugins." }%GeoLookupPlugin is installed and enabled.

---++ User Interface

<div style="float:right; margin-left: 20px; width: 379px;">
<img src="%PUBURLPATH%/%WEB%/%TOPIC%/whereis-dialog2.png" alt="whereis-dialog2.png" width="379" height="217" />
</div>
A dialog is shown when a user visits the TWiki site from an unknown location. The user can specify a name for the location.

The location data is shown as follows:

   * User profile pages show the user's last location and time next to the person's name.
   * %ATTACHURL%/whereis-left-button-gray.png button in the left topic margin, linking to the WhereIs topic.
   * The WhereIs topic shows user location data.

The *[[WhereIs]]* topic has two tabs:

   * The "Recently Seen" tab shows recent user locations.
   * The "Locations" tab shows known locations.

<div style="float:right; margin-left: 20px; width: 474px;">
<img src="%PUBURLPATH%/%WEB%/%TOPIC%/recently-seen.png" alt="recently-seen.png" width="474" height="428" />
</div>
The "Recently Seen" tab shows the locations of the 20 most recent users. The limit can be changed.

The "Locations" tab shows a table with known locations and users last seen at each location. Users can update their current location; site administrators can update all locations and can add new locations. Hover over a row to update the location.

---++ Syntax Rules

There is none for end users. Site administrators can customize the functionality.

#SiteAdminDocumentation
---++ Site Admin Documentation

Read this if you want to customize the functionality of the plugin.
%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

This plugin handles a WHEREIS variable. All interaction is done via this variable. The functionality is determined by an action parameter.

---+++ WHEREIS{ action="recordlocation" } - record the location

=%<nop>WHEREIS{ action="recordlocation" }%= records the location of the logged in user. No additional parameters are supported. No action is done if the user is not authenticated.

This variable needs to be called to record user location. It can be done by enabling the =whereis= skin template, which contains the variable. Example setting in %LOCALSITEPREFS%:

   * Set <nop>SKIN = whereis, topmenu, pattern

Alternatively, add the variable anywhere to a skin template within the body tags.

Please note that the =whereis= skin template and the =tagme= skin template clash and can't be used together. If you want to use tagging and this plugin you need to manually merge the content of =template/view.tagme.tmpl= into =template/view.whereis.tmpl=, and set the SKIN to =whereis, topmenu, pattern=.

---+++ WHEREIS{ action="setlocation" } - set location name

=%<nop>WHEREIS{ action="setlocation" }%= sets the name of a location associated with the IP address of the logged in user. Additional parameters:

| *Parameter* | *Explanation* | *Default* |
| =address="..."= | IP address | IP address of logged in user |
| =location="..."= | Location name |  |

---+++ WHEREIS{ action="showlocation" } - show user location

=%<nop>WHEREIS{ action="showlocation" }%= shows the location and time of a user. Additional parameters:

| *Parameter* | *Explanation* | *Default* |
| =user="..."= | !WikiName of user | logged in user |
| =lastseenmsg="..."= | Last seen message. Variables: %BB% =$wikiname= - !WikiName of the user, such as =JimmyNeutron= %BB% =$wikiusername= - !Web.WikiName of user, such as =%USERSWEB%.JimmyNeutron= %BB% =$spacedname= - spaced-out !WikiName of user, such as =Jimmy Neutron= %BB% =$location= - name of location %BB% =$ago= - elapsed time | ={LastSeenMsg}= configure setting |
| =notseenmsg="..."= | Not yet seen message. %BB% Same =$wikiname=, =$wikiusername= and =$spacedname= variables as above. | ={NotSeenMsg}= configure setting |

---+++ WHEREIS{ action="editlocations" } - show and edit known locations

=%<nop>WHEREIS{ action="editlocations" }%= shows a table with known locations and users last seen at each location. Hover over a row to update a location. Use the last row to add a location. Additional parameter:

| *Parameter* | *Explanation* | *Default* |
| =limit="..."= | Limit number of recent entries | ="100"= |

---+++ WHEREIS{ action="showrecent" } - show recent location

=%<nop>WHEREIS{ action="showrecent" }%= shows recent locations and times of users. Additional parameters:

| *Parameter* | *Explanation* | *Default* |
| =limit="..."= | Limit number of recent entries | ="20"= |
| =header="..."= | Table header | ="%VBAR% User %VBAR% At location %VBAR% Last seen %VBAR%"= |
| =format="..."= | Format of a table row. Variables: %BB% =$wikiname= - !WikiName of the user %BB% =$wikiusername= - !Web.WikiName of user %BB% =$spacedname= - spaced-out !WikiName of user %BB% =$location= - name of location %BB% =$ago= - elapsed time | ="%VBAR% $wikiusername %VBAR% $location %VBAR%  $ago %VBAR%"= |

---+++ Plugin data

The IP address data and user access data is stored in the plugin's working area at =twiki/working/work_areas/WhereIsPlugin=.

IP address data is stored in files named =addr-&lt;ip&gt;.txt=, e.g. one file per recorded IP address. This data is used to map from IP address to location name.

User access data is stored in files named =addr-&lt;wikiname&gt;.txt=, e.g. one file per user. This data is used to record the most recent access time and IP address of a user.

%ENDTWISTY%

---++ Plugin Installation &amp; Configuration

You do not need to install anything on the browser to use this plugin. These instructions are for the administrator who installs the plugin on the TWiki server.
%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section.
      * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.

   * 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/WhereIsPlugin.txt== | Plugin topic |
        | ==data/TWiki/WhereIs.txt== | Report topic |
        | ==pub/TWiki/WhereIsPlugin/*.gif== and ==*.png== | Image files |
        | ==templates/view.whereis.tmpl== | Skin template |
        | ==templates/whereisdialog.tmpl== | New location dialog box template |
        | ==templates/whereiseditlocations.tmpl== | Edit location table template |
        | ==lib/TWiki/Plugins/WhereIsPlugin.pm== | Plugin Perl module |
        | ==lib/TWiki/Plugins/WhereIsPlugin/Core.pm== | Plugin Perl module |
        | ==lib/TWiki/Plugins/WhereIsPlugin/Config.spec== | Configure spec file |
      * Set the ownership of the extracted directories and files to the webserver user.

   * Plugin configuration:
      * Run the [[%SCRIPTURL{configure}%][configure]] script and enable the plugin in the __Plugins__ section.
      * Configure additional plugin settings in the __Extensions__ section if desired.

   * Enable location tracking:
      * Add the =whereis= skin template to the SKIN path. Example setting in %LOCALSITEPREFS%:
         * Set <nop>SKIN = whereis, topmenu, pattern
      * There are alternatives, see [[#SiteAdminDocumentation][site admin docs]] above

   * Show location in user profiles:
      * Edit %USERSWEB%.UserProfileHeader and add the user location next to the user's name:
        %BR% =---+!! %<nop>FORMFIELD{ "FirstName" topic="%<nop>INCLUDINGTOPIC%" }% %<nop>FORMFIELD{ "LastName" topic="%<nop>INCLUDINGTOPIC%" }% &lt;span style="font-size: 60%"&gt; %<nop>FORMFIELD{ "StatusUpdate" topic="%<nop>INCLUDINGTOPIC%" }% &amp;mdash; [<nop>[%<nop>SYSTEMWEB%.WhereIs][&lt;img src="%<nop>PUBURLPATH%/%<nop>SYSTEMWEB%/WhereIsPlugin/whereis.gif" alt="" title="Where is?" width="16" height="16" border="0" /&gt;]] %<nop>WHEREIS{ user="%BASETOPIC%" }%&lt;/span&gt;=

   * Test if the configuration is successful:
      * Visit your user profile topic - it should show your location.
      * Visit WhereIs - it should show locations of recent users.

   * Optional: Install the TWiki:Plugins.GeoLookupPlugin to map automatically from IP address to location

%ENDTWISTY%

---++ Plugin Info

   * One line description, is shown in the %SYSTEMWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = Where is a person? Show where and when TWiki users were last seen

%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Plugin Author: | TWiki:Main.PeterThoeny |
|  Copyright: | &copy; 2014-2015 Wave Systems Corp. %BR% &copy; 2014-2015 TWiki:Main.PeterThoeny %BR% &copy; 2014-2015 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Sponsor: | [[http://www.wave.com/][Wave Systems Corp.]] |
|  Plugin Version: | 2015-01-07 |
%TWISTY{
 mode="div"
 showlink="Show Change History %ICONURL{toggleopen}%"
 hidelink="Hide Change History %ICONURL{toggleclose}% "
}%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  2015-01-07: | TWikibug:Item7568: Add Help tab to WhereIs topic |
|  2014-09-24: | TWikibug:Item7527: Web-based deletion of locations; allow broader IP address ranges x.x in addition to x.x.x and x.x.x.x |
|  2014-07-03: | TWikibug:Item7527: Update names of known locations; add new location in WhereIs topic; performance tuning |
|  2014-07-02: | TWikibug:Item7527: Show known locations in WhereIs topic; doc improvements |
|  2014-07-01: | TWikibug:Item7527: Show dialog box prompting user to specify a name for unknown locations |
|  2014-06-30: | TWikibug:Item7527: Initial version |
%ENDTWISTY%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.2 |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  [[TWiki:Plugins.Benchmark][Plugin Benchmark]]: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/WhereIsPlugin |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/WhereIsPluginDev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/WhereIsPluginAppraisal |

__Related Topics:__ WhereIs, %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.AdminDocumentationCategory, %SYSTEMWEB%.TWikiPreferences

%META:FILEATTACHMENT{name="whereis-left-button-gray.png" attachment="whereis-left-button-gray.png" attr="h" comment="" date="1404110344" path="whereis-left-button-gray.png" size="381" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="whereis-left-button.png" attachment="whereis-left-button.png" attr="h" comment="" date="1404110344" path="whereis-left-button.png" size="718" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="whereis.gif" attachment="whereis.gif" attr="h" comment="" date="1404110344" path="whereis.gif" size="973" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="recently-seen.png" attachment="recently-seen.png" attr="h" comment="" date="1404184643" path="recently-seen.png" size="76944" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="whereis-dialog.png" attachment="whereis-dialog.png" attr="h" comment="" date="1404263140" path="whereis-dialog.png" size="46116" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="whereis-dialog2.png" attachment="whereis-dialog2.png" attr="h" comment="" date="1404263140" path="whereis-dialog2.png" size="37152" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="whereis-128.png" attachment="whereis-128.png" attr="h" comment="" date="1404345355" path="whereis-128.png" size="6145" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="whereis-64.png" attachment="whereis-64.png" attr="h" comment="" date="1404345355" path="whereis-64.png" size="3692" user="TWikiContributor" version="1"}%
