Refs #1823, many changes including:

  * Add warning if old GeoIP plugin is used.
  * Display links to installation instructions for different providers if they are not installed.
  * Add report documentation for country, region, continent and city reports, round latitude/longitude.
  * Increase 'Done' timeout when switching providers
  * Display quick start instructions for GeoIP if no GeoIP provider is currently working.
  * Add script to geolocate old data.



git-svn-id: http://dev.piwik.org/svn/trunk@7186 59fd770c-687e-43c8-a1e3-f5a4ff64c105

8 files changed, 114 insertions, 10 deletions

diff --git a/plugins/UserCountry/Controller.php b/plugins/UserCountry/Controller.php
index a2e2d7495f..fc13e5155a 100644
--- a/plugins/UserCountry/Controller.php
+++ b/plugins/UserCountry/Controller.php
@@ -40,6 +40,18 @@ class Piwik_UserCountry_Controller extends Piwik_Controller
 			$newline = '<br/>', $includeExtra = true);
 		$view->currentProviderId = Piwik_UserCountry_LocationProvider::getCurrentProviderId();
 		$view->thisIP = Piwik_IP::getIpFromHeader();
+		
+		// check if there is a working provider (that isn't the default one)
+		$view->isThereWorkingProvider = false;
+		foreach ($view->locationProviders as $id => $provider)
+		{
+			if ($id != Piwik_UserCountry_LocationProvider_Default::ID
+				&& $provider['status'] == Piwik_UserCountry_LocationProvider::INSTALLED)
+			{
+				$view->isThereWorkingProvider = true;
+				break;
+			}
+		}
 
 		$this->setBasicVariablesView($view);
 		Piwik_Controller_Admin::setBasicVariablesAdminView($view);
@@ -108,6 +120,7 @@ class Piwik_UserCountry_Controller extends Piwik_Controller
 		$view = $this->getStandardDataTableUserCountry(__FUNCTION__, "UserCountry.getCountry");
 		$view->setLimit( 5 );
 		$view->setColumnTranslation('label', Piwik_Translate('UserCountry_Country'));
+		$view->setReportDocumentation(Piwik_Translate('UserCountry_getCountryDocumentation'));
 		return $this->renderView($view, $fetch);
 	}
 
@@ -117,6 +130,7 @@ class Piwik_UserCountry_Controller extends Piwik_Controller
 		$view->disableSearchBox();
 		$view->disableOffsetInformationAndPaginationControls();
 		$view->setColumnTranslation('label', Piwik_Translate('UserCountry_Continent'));
+		$view->setReportDocumentation(Piwik_Translate('UserCountry_getContinentDocumentation'));
 		return $this->renderView($view, $fetch);
 	}
 	
@@ -131,6 +145,8 @@ class Piwik_UserCountry_Controller extends Piwik_Controller
 		$view = $this->getStandardDataTableUserCountry(__FUNCTION__, "UserCountry.getRegion");
 		$view->setLimit(5);
 		$view->setColumnTranslation('label', Piwik_Translate('UserCountry_Region'));
+		$view->setReportDocumentation(Piwik_Translate('UserCountry_getRegionDocumentation').'<br/>'
+			. $this->getGeoIPReportDocSuffix());
 		return $this->renderView($view, $fetch);
 	}
 	
@@ -145,9 +161,21 @@ class Piwik_UserCountry_Controller extends Piwik_Controller
 		$view = $this->getStandardDataTableUserCountry(__FUNCTION__, "UserCountry.getCity");
 		$view->setLimit(5);
 		$view->setColumnTranslation('label', Piwik_Translate('UserCountry_City'));
+		$view->setReportDocumentation(Piwik_Translate('UserCountry_getCityDocumentation').'<br/>'
+			. $this->getGeoIPReportDocSuffix());
 		return $this->renderView($view, $fetch);
 	}
 	
+	private function getGeoIPReportDocSuffix()
+	{
+		return Piwik_Translate('UserCountry_GeoIPDocumentationSuffix', array(
+			'<a href="http://www.maxmind.com/?rId=piwik">',
+			'</a>',
+			'<a href="http://www.maxmind.com/en/city_accuracy?rId=piwik">',
+			'</a>'
+		));
+	}
+	
 	protected function getStandardDataTableUserCountry( $currentControllerAction, 
 												$APItoCall,
 												$defaultDatatableType = null )
diff --git a/plugins/UserCountry/LocationProvider.php b/plugins/UserCountry/LocationProvider.php
index 34124f0d23..744bc24fe1 100755
--- a/plugins/UserCountry/LocationProvider.php
+++ b/plugins/UserCountry/LocationProvider.php
@@ -35,6 +35,8 @@ abstract class Piwik_UserCountry_LocationProvider
 	
 	const CURRENT_PROVIDER_OPTION_NAME = 'usercountry.location_provider';
 	
+	const GEOGRAPHIC_COORD_PRECISION = 3;
+	
 	const CONTINENT_CODE_KEY = 'continent_code';
 	const CONTINENT_NAME_KEY = 'continent_name';
 	const COUNTRY_CODE_KEY = 'country_code';
@@ -322,6 +324,8 @@ abstract class Piwik_UserCountry_LocationProvider
 	 * This method will try to set the continent code, continent name and country code
 	 * using other information.
 	 * 
+	 * Note: This function must always be called by location providers in getLocation.
+	 * 
 	 * @param array $location The location information to modify.
 	 */
 	public function completeLocationResult( &$location )
@@ -349,6 +353,32 @@ abstract class Piwik_UserCountry_LocationProvider
 			$countryCode = strtolower($location[self::COUNTRY_CODE_KEY]);
 			$location[self::COUNTRY_NAME_KEY] = Piwik_Translate('UserCountry_country_'.$countryCode);
 		}
+		
+		// deal w/ improper latitude/longitude & round proper values
+		if (!empty($location[self::LATITUDE_KEY]))
+		{
+			if (is_numeric($location[self::LATITUDE_KEY]))
+			{
+				$location[self::LATITUDE_KEY] = round($location[self::LATITUDE_KEY], self::GEOGRAPHIC_COORD_PRECISION);
+			}
+			else
+			{
+				unset($location[self::LATITUDE_KEY]);
+			}
+		}
+		
+		if (!empty($location[self::LONGITUDE_KEY]))
+		{
+			if (is_numeric($location[self::LONGITUDE_KEY]))
+			{
+				$location[self::LONGITUDE_KEY] = round(
+					$location[self::LONGITUDE_KEY], self::GEOGRAPHIC_COORD_PRECISION);
+			}
+			else
+			{
+				unset($location[self::LONGITUDE_KEY]);
+			}
+		}
 	}
 	
 	/**
@@ -418,7 +448,7 @@ abstract class Piwik_UserCountry_LocationProvider
 			
 			if (!empty($locationInfo[self::ORG_KEY]))
 			{
-				$lines[] = "Org: ".$locationInfo[self::ORG_KEY]; // TODO (translate)
+				$lines[] = "Org: ".$locationInfo[self::ORG_KEY];
 			}
 			
 			if (!empty($locationInfo[self::ISP_KEY]))
diff --git a/plugins/UserCountry/LocationProvider/Default.php b/plugins/UserCountry/LocationProvider/Default.php
index dcf99dec3a..a9d1e0d706 100755
--- a/plugins/UserCountry/LocationProvider/Default.php
+++ b/plugins/UserCountry/LocationProvider/Default.php
@@ -98,7 +98,10 @@ class Piwik_UserCountry_LocationProvider_Default extends Piwik_UserCountry_Locat
 	{
 		$desc = Piwik_Translate('UserCountry_DefaultLocationProviderDesc1') . ' '
 			  . Piwik_Translate('UserCountry_DefaultLocationProviderDesc2',
-			  		array('<strong>', '<em>', '</em>', '</strong>'));
+			  		array('<strong>', '<em>', '</em>', '</strong>'))
+	  		  . '<p><em><a href="http://piwik.org/faq/troubleshooting/#toc-how-do-i-get-the-geoip-databases">'
+	  		  . Piwik_Translate('UserCountry_HowToInstallGeoIPDatabases')
+	  		  . '</em></a></p>';
 		return array('id' => self::ID, 'title' => self::TITLE, 'description' => $desc, 'order' => 1);
 	}
 }
diff --git a/plugins/UserCountry/LocationProvider/GeoIp/Pecl.php b/plugins/UserCountry/LocationProvider/GeoIp/Pecl.php
index 3fbbb52625..b5722e354d 100755
--- a/plugins/UserCountry/LocationProvider/GeoIp/Pecl.php
+++ b/plugins/UserCountry/LocationProvider/GeoIp/Pecl.php
@@ -231,7 +231,16 @@ class Piwik_UserCountry_LocationProvider_GeoIp_Pecl extends Piwik_UserCountry_Lo
 	{
 		$desc = Piwik_Translate('UserCountry_GeoIpLocationProviderDesc_Pecl1') . '<br/><br/>'
 			  . Piwik_Translate('UserCountry_GeoIpLocationProviderDesc_Pecl2');
-		return array('id' => self::ID, 'title' => self::TITLE, 'description' => $desc, 'order' => 2);
+		$installDocs = '<em>'
+					 . '<a href="http://piwik.org/faq/how-to/#faq_164">'
+					 . Piwik_Translate('UserCountry_HowToInstallGeoIpPecl')
+					 . '</a>'
+					 . '</em>';
+		return array('id' => self::ID,
+					  'title' => self::TITLE,
+					  'description' => $desc,
+					  'install_docs' => $installDocs,
+					  'order' => 2);
 	}
 	
 	/**
diff --git a/plugins/UserCountry/LocationProvider/GeoIp/Php.php b/plugins/UserCountry/LocationProvider/GeoIp/Php.php
index 459998bc67..dc404f93fc 100755
--- a/plugins/UserCountry/LocationProvider/GeoIp/Php.php
+++ b/plugins/UserCountry/LocationProvider/GeoIp/Php.php
@@ -232,9 +232,15 @@ class Piwik_UserCountry_LocationProvider_GeoIp_Php extends Piwik_UserCountry_Loc
 	{
 		$desc = Piwik_Translate('UserCountry_GeoIpLocationProviderDesc_Php1') . '<br/><br/>'
 			  . Piwik_Translate('UserCountry_GeoIpLocationProviderDesc_Php2',
-			  		array('<strong>', '</strong>', '<strong><em>', '</em></strong>',
-			  			  '<strong><em>', '</em></strong>'));
-		return array('id' => self::ID, 'title' => self::TITLE, 'description' => $desc, 'order' => 4);
+			  		array('<strong><em>', '</em></strong>', '<strong><em>', '</em></strong>'));
+		$installDocs = '<em><a href="http://piwik.org/faq/how-to/#faq_163">'
+	  		  . Piwik_Translate('UserCountry_HowToInstallGeoIPDatabases')
+	  		  . '</em></a>';
+		return array('id' => self::ID,
+					  'title' => self::TITLE,
+					  'description' => $desc,
+					  'install_docs' => $installDocs,
+					  'order' => 4);
 	}
 	
 	/**
diff --git a/plugins/UserCountry/LocationProvider/GeoIp/ServerBased.php b/plugins/UserCountry/LocationProvider/GeoIp/ServerBased.php
index d39aba6756..2b59061025 100755
--- a/plugins/UserCountry/LocationProvider/GeoIp/ServerBased.php
+++ b/plugins/UserCountry/LocationProvider/GeoIp/ServerBased.php
@@ -186,7 +186,18 @@ class Piwik_UserCountry_LocationProvider_GeoIp_ServerBased extends Piwik_UserCou
 			  . '<br/><br/>'
 			  . Piwik_Translate('UserCountry_GeoIpLocationProviderDesc_ServerBased2',
 			  		array('<strong><em>', '</em></strong>', '<strong><em>', '</em></strong>'));
+		$installDocs =
+			  '<em><a href="http://piwik.org/faq/how-to/#faq_165">'
+			. Piwik_Translate('UserCountry_HowToInstallApacheModule')
+			. '</a></em><br/><em>'
+			. '<a href="http://piwik.org/faq/how-to/#faq_166">'
+			. Piwik_Translate('UserCountry_HowToInstallNginxModule')
+			. '</a></em>';
 		
-		return array('id' => self::ID, 'title' => $title, 'description' => $desc, 'order' => 3);
+		return array('id' => self::ID,
+					  'title' => $title,
+					  'description' => $desc,
+					  'order' => 3,
+					  'install_docs' => $installDocs);
 	}
 }
diff --git a/plugins/UserCountry/templates/admin.js b/plugins/UserCountry/templates/admin.js
index 0acc247984..b01d019c24 100755
--- a/plugins/UserCountry/templates/admin.js
+++ b/plugins/UserCountry/templates/admin.js
@@ -31,7 +31,7 @@ $(document).ready(function() {
 				ajaxSuccess.fadeIn(1000, function() {
 					setTimeout(function() {
 						ajaxSuccess.fadeOut(1000);
-					}, 500);
+					}, 2000);
 				});
 			}
 		});
diff --git a/plugins/UserCountry/templates/adminIndex.tpl b/plugins/UserCountry/templates/adminIndex.tpl
index 1d8eb9236b..b12b41f89e 100755
--- a/plugins/UserCountry/templates/adminIndex.tpl
+++ b/plugins/UserCountry/templates/adminIndex.tpl
@@ -2,12 +2,26 @@
 {assign var=showPeriodSelection value=false}
 {include file="CoreAdminHome/templates/header.tpl"}
 
-<h2>{'UserCountry_Geolocation'|translate}</h2>
+<h2 id="location-providers">{'UserCountry_Geolocation'|translate}</h2>
 
 <div style="width:900px">
 
 <p>{'UserCountry_GeolocationPageDesc'|translate}</p>
 
+{if !$isThereWorkingProvider}
+<h3 style="margin-top:0">{'UserCountry_HowToSetupGeoIP'|translate}</h3>
+<p>{'UserCountry_HowToSetupGeoIPIntro'|translate}</p>
+
+<ul style="list-style:disc;margin-left:2em">
+	<li>{'UserCountry_HowToSetupGeoIP_Step1'|translate:'<a href="http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz">':'</a>':'<a href="http://www.maxmind.com/?rId=piwik">':'</a>'}</li>
+	<li>{'UserCountry_HowToSetupGeoIP_Step2'|translate:"'GeoLiteCity.dat'":'<strong>':'</strong>'}</li>
+	<li>{'UserCountry_HowToSetupGeoIP_Step3'|translate:'<strong>':'</strong>':'<span style="color:green"><strong>':'</strong></span>'}</li>
+	<li>{'UserCountry_HowToSetupGeoIP_Step4'|translate}</li>
+</ul>
+
+<p>&nbsp;</p>
+{/if}
+
 <table class="adminTable">
 	<tr>
 		<th>{'UserCountry_LocationProvider'|translate}</th>
@@ -36,7 +50,10 @@
 			</p>
 		</td>
 		<td>
-			{$provider.description|translate}
+			<p>{$provider.description|translate}</p>
+			{if $provider.status neq 1 && isset($provider.install_docs)}
+			<p>{$provider.install_docs}</p>
+			{/if}
 		</td>
 		<td width="164">
 		{if $provider.status eq 1}