Almost new location article.

bindings.md

@@ -161,7 +161,7 @@ A great way of using bindings is the option to create a custom expression (that
 ```
 
 As seen from the example adding an expression extends a binding syntax a little bit. Actually it is a full binding syntax - first parameter is the source property (which will be listened for changes), second parameter is the expression that will be evaluated, there is one more (third) parameter which states if the binding is twoWay or not (as mentioned earlier by default xml declaration creates a `twoWay` binding). The result of the upper example is a TextField element that will display the value of the `sourceProperty` followed by " some static text" string.
-Speaking of a `twoWay` binding there is a common problem that origins in the different way of storing and displaying data. For example date objects are generally stored as number or a sequence of numbers and this is not the best possible option for displaying date to the end user. Also there is another problem end user could type a date (in a way convenient to its culture for example using a `DD.MM.YYYY` format) and underlying data should convert it to a correct value. Lets see how this could be handled with NativeScript binding.
+Speaking of a `twoWay` binding there is a common problem that origins in the different way of storing and displaying data. Probably the best example here is the date and time objects. Generally date and time information is stored as a number or a sequence of numbers (very useful for indexing, searching and other database operations), but this is not the best possible option for displaying date to the application user. Also there is another problem when user inputs a date (in our example user types into a TextField). The result of user input will be a string (TextField.text property) - representation of a date in a convenient to user's culture way usually using the same format as for display `DD.MM.YYYY`. This string should be converted to a correct date object. Lets see how this could be handled with NativeScript binding.
 
 ``` XML
 <Page>

location.md

@@ -1,14 +1,112 @@
 ---
-nav-title: Location in NativeScript 
+nav-title: Location in NativeScript
 title: "App: Location"
 description: How to work with geographical location data in NativeScript.
 position: 11
 ---
 
 # Location
 
-The NativeScript location module uses an accuracy criteria approach to deliver geolocation. This means that getting (or monitoring) a location is powered by the most accurate location provider that is available (for example if GPS signal is available and the GPS provider is enabled, then it will be used; if GPS is not connected, the device falls back to other available providers such as Wi-Fi networks or cell towers). 
+The NativeScript location module uses an accuracy criteria approach to deliver geolocation. This means that getting (or monitoring) a location is powered by the most accurate location provider that is available (for example if GPS signal is available and the GPS provider is enabled, then it will be used; if GPS is not connected, the device falls back to other available providers such as Wi-Fi networks or cell towers).
 
 This approach does not limit location monitoring only to a specific location provider; it can still work with all of them.
 
-More information about the NativeScript location module can be found in the [API Reference](./ApiReference/location/location.md). You are advised to start with the [How-to](./ApiReference/location/HOW-TO.md) article.
+It is a good idea to start with the [How-to](./ApiReference/location/HOW-TO.md) article. Here are some further explanations of how API is designed to work.
+
+### Getting an information about location service
+
+NativeScript has an universal way to check if location service is turned on. This can be done by static `isEnabled` method of the LocationManager class.
+
+> Note: This method will get an information about if the location service is enabled (in android) (any accuracy level), or if the location service is enabled for the application (iOS) (either for foreground or background use).
+
+### Request a permission to use location service
+
+Unfortunately here NativeScript cannot give a common approach, since Android and iOS platforms differ significantly on that.
+The good thing is that you can always use native API from NativeScript.
+
+``` JavaScript
+var buttonModule = require("ui/button");
+var appModule = require("application");
+var platformModule = require("platform");
+
+var onRequestButtonTap = function(args: observable.EventData) {
+    var button = <buttonModule.Button>(args.object);
+    if (button.android) {
+        console.log("Application run on Android");
+        (<android.app.Activity>appModule.android.currentContext).startActivityForResult(new android.content.Intent(android.provider.Settings.ACTION_LOCATION_SOURCE_SETTINGS), 0);
+    }
+    else if (button.ios) {
+        console.log("Application run on iOS");
+        if (platformModule.device.osVersion.indexOf("8") === 0) {
+            console.log("iOS version is greater or equal to 8.0");
+            var iosLocationManager = CLLocationManager.alloc().init();
+            iosLocationManager.requestWhenInUseAuthorization();
+        }
+    }
+}
+```
+``` TypeScript
+import buttonModule = require("ui/button");
+import appModule = require("application");
+import platformModule = require("platform");
+
+var onRequestButtonTap = function(args: observable.EventData) {
+    var button = <buttonModule.Button>(args.object);
+    if (button.android) {
+        console.log("Application run on Android");
+        (<android.app.Activity>appModule.android.currentContext).startActivityForResult(new android.content.Intent(android.provider.Settings.ACTION_LOCATION_SOURCE_SETTINGS), 0);
+    }
+    else if (button.ios) {
+        console.log("Application run on iOS");
+        if (platformModule.device.osVersion.indexOf("8") === 0) {
+            console.log("iOS version is greater or equal to 8.0");
+            var iosLocationManager = CLLocationManager.alloc().init();
+            iosLocationManager.requestWhenInUseAuthorization();
+        }
+    }
+}
+```
+
+> Note (iOS): For iOS there is a change introduced in 8.0 version that changes the way location service is requested. There are two modes for using location service from an application (`WhenInUse` - denotes using location service only when application is running, and `Always` mode which allows using location service in a background application). According to business scenario location service request could be done via `requestWhenInUseAuthorization` or `requestAlwaysAuthorization` methods. Both methods require a specific setting in your application to be set in `application.plist` file. Application `plist` file should contain `NSLocationWhenInUseUsageDescrition` or `NSLocationAlwaysUsageDescription` string values respectively. For iOS versions below 8.0 there is a similar string value named `NSLocationUsageDescription` which is not mandatory.
+
+> Note (Android): In order to request a location service in android a special permission should be set - either `android.permission.ACCESS_COARSE_LOCATION` or `android.permission.ACCESS_FINE_LOCATION`. Fine location permission enables usage of the GPS sensor, so this is the recommended option.
+
+### Getting a location
+For getting a location information NativeScript provides two different approaches.
+
+* First approach is available using the `location` module, where there is a `getLocation` method which can be used to get a single location. This method accepts [`location options`](./ApiReference/location/Options.md) parameter. The `timeout` parameter denotes the time in milliseconds when location monitoring will be stopped (default value is 20 seconds). When `timeout` is set to 0 (zero), then last known location (if is newer than maximum age) will be returned.
+
+* Second approach is using the location manager `startLocationMonitoring` method. The difference here is that location monitoring will not be stopped automatically (useful for a GPS log like application). `stopLocationMonitoring` method is used to stop location monitoring.
+
+``` JavaScript
+var locationModule = require("location");
+var locationManager = new locationModule.LocationManager();
+var locationOptions = {
+    desiredAccuracy: 3,
+    updateDistance: 0,
+    minimumUpdateTime: 5000,
+    maximumAge: 20000
+};
+locationManager.startLocationMonitoring(function(location){
+    console.log("Location received: " + location);
+    }, function (error) {
+        console.log("Location error received: " + error);
+    }, locationOptions);
+```
+``` TypeScript
+import locationModule = require("location");
+var locationManager = new locationModule.LocationManager();
+var locationOptions = {
+    desiredAccuracy: 3,
+    updateDistance: 0,
+    minimumUpdateTime: 5000,
+    maximumAge: 20000
+};
+locationManager.startLocationMonitoring(function(location){
+    console.log("Location received: " + location);
+    }, function (error) {
+        console.log("Location error received: " + error);
+    }, locationOptions);
+```
+
+More information about the NativeScript location module can be found in the [API Reference](./ApiReference/location/location.md).