=== Plugin Name ===
Contributors: rdconnell
Tags: location, ios, find my phone, iphone, google, distance, geolocation
Requires at least: 3.3
Tested up to: 3.4
Stable tag: trunk
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

Finds the distance between the visitor to your site and your iPhone or a fixed location. Uses Find My Phone and Browser Geolocation to do so.

== Description ==

Finds the distance between the visitor to your site and your iOS device or a fixed location. Uses Find My Phone and Browser Geolocation to do so. Find my Phone is accessed using the Sosumi library (https://github.com/tylerhall/sosumi/).

The widget either tries to find your location using 'Find my Phone' and then works out the distance between you and the location provided by the site visitors browser. Alternatively you can enter the co-ordinates to use instead of using 'Find my Phone'. For example you could set your location as your place of business to let site visitors know how far away they are from you.

== Installation ==

1. Upload `distancefromme` to the `/wp-content/plugins/` directory
1. Activate the plugin through the 'Plugins' menu in WordPress
1. Configure the widget through the 'Widget' menu in WordPress to display it on your page

= What do the widget configuration values do ? =

* Title : The title that will appear at the top of the widget
* Use Find My Phone : If 'Yes' then the widget will use Find My Phone to get your current location. If set to 'No' then the widget will use the values provided for 'Home Lat' and 'Home Lng'.
* Show Device Name : If 'Yes' then the widget display the name of the device that it has retrieved the location for. If this is set to 'No' then the details from 'Home Name' will be displayed. If 'Home Name' field is empty then the text 'my current location.' will be used.
* Find My Phone Username : You Apple Id username for Find My Phone
* Find My Phone Password : You Apple Id password for Find My Phone
* Device No : If you have multiple devices on your Find My Phone account then you can change which one is used by changing this number. Accepts values from 0 to 100. Defaults to 0 if no value is entered.
* Timeout : How long in seconds the widget should spend looking for the Find My Phone device. Defaults to 300 if no value is entered.
* Google Maps V2 API: Your Google Maps V2 API Key
* Home Name: The name of your 'home' location. This wil be displayed to the site visitor.
* Home Lat:  The latitude of your 'home' location. This will not be displayed to the site visitor.
* Home Lng:  The longitude of your 'home' location. This will not be displayed to the site visitor.

== Frequently Asked Questions ==

= Do I need to use Find My Phone ? =

No. You can enter a set of co-ordinates and use these instead of our current location. This is useful if you want to let site visitors know how far away they are from a fixed point, your place of business for example.

= How does it find my phone ? =

Find my Phone is accessed using the Sosumi library (https://github.com/tylerhall/sosumi/) using your Find My Phone username and password.

= What do the widget configuration values do ? =

* Title : The title that will appear at the top of the widget
* Use Find My Phone : If 'Yes' then the widget will use Find My Phone to get your current location. If set to 'No' then the widget will use the values provided for 'Home Lat' and 'Home Lng'.
* Show Device Name : If 'Yes' then the widget display the name of the device that it has retrieved the location for. If this is set to 'No' then the details from 'Home Name' will be displayed. If 'Home Name' field is empty then the text 'my current location.' will be used.
* Find My Phone Username : You Apple Id username for Find My Phone
* Find My Phone Password : You Apple Id password for Find My Phone
* Device No : If you have multiple devices on your Find My Phone account then you can change which one is used by changing this number. Accepts values from 0 to 100. Defaults to 0 if no value is entered.
* Timeout : How long in seconds the widget should spend looking for the Find My Phone device. Defaults to 300 if no value is entered.
* Google Maps V2 API: Your Google Maps API
* Home Name: The name of your 'home' location. This wil be displayed to the site visitor.
* Home Lat:  The latitude of your 'home' location. This will not be displayed to the site visitor.
* Home Lng:  The longitude of your 'home' location. This will not be displayed to the site visitor.

= Disclaimer =

This was hacked together over a weekend to keep me entertained. It works for me on my site and I have tested it with a couple of installations but your milage may vary.

= Potential Enhancements =

* Display iOS last location update accuracy/timestamp
* Tidy up widget configuration
* Take a place name and lookup lat/lng instead of manually adding values in configuration 
* Better exception handling and error messages
* Support for expressing distance in miles or km
* Update Google API to 3

== Screenshots ==

1. This screen shot description corresponds to screenshot-1.(png|jpg|jpeg|gif). Note that the screenshot is taken from
the directory of the stable readme.txt, so in this case, `/tags/4.3/screenshot-1.png` (or jpg, jpeg, gif)
2. This is the second screen shot

== Changelog ==

= 0.2 =
* You can now specify the device id to search for if you have multiple devices configured in Find My Phone
* Added 'timeout', 'device no' and 'show device name' parameters to configuration
* Slightly better error handling

= 0.1 =
* Initial development



== Upgrade Notice ==

N/A