Updating documentation (#20)

* Create readme.md

* Update main readme.md

* Added initial sections

* Deleting as unnecessary. Replaced by Readme.md

* Removed reference to BotBuilder samples

* Added more information and Getting started sections, and made edits to other sections

* Rename LICENSE to LICENSE.md

* Added Images folder and screenshot for basic scenario

* Added screenshot for basic scenario

* Delete skype_singleresult.png

* new screenshot for basic scenario

* re-adding image for single address scenario

* Edits and Example sections

* Added images for Examples section

* Fixed relative paths for CSharp and Node

* Added example images

* added multi address image

* Added Messenger screenshot for examples

CSharp/README.md

@@ -1,50 +1,67 @@
-# Microsoft Bot Builder Location Control
+# Bing Location Control for Microsoft Bot Framework
 
-This dialog provides a location control, powered by Bing's Maps REST Services, to make the process of getting the user's location easy and consistent across all messaging channels supported by the bot framework. 
+## Overview
+The following examples demonstrate how to use the Bing location control to collect and validate the user's location with your Microsoft Bot Framework bot in C#. 
 
-## Examples
+## Prerequisites
+To start using the control, you need to obtain a Bing Maps API subscription key. You can sign up to get a free key with up to 10,000 transactions per month in [Azure Portal](https://azure.microsoft.com/en-us/marketplace/partners/bingmaps/mapapis/).
 
-The following examples demonstrate how to use [LocationDialog](BotBuilderLocation/LocationDialog.cs) to achieve different scenarios:
+## Code Highlights
 
-#### Calling with default parameters:
+### Usage
+Import the BotBuilder-Location library from nuGet and add the following namespace. 
+
+````C#
+using Microsoft.Bot.Builder.Location;
+````
+
+### Calling the location control with default parameters
+The example initiates the location control with default parameters, which returns a custom prompt message asking the user to provide an address. 
 
 ````C#
 var apiKey = WebConfigurationManager.AppSettings["BingMapsApiKey"];
-var prompt = "Hi, where would you like me to ship to your widget?";
+var prompt = "Where should I ship your order? Type or say an address.";
 var locationDialog = new LocationDialog(apiKey, message.ChannelId, prompt);
 context.Call(locationDialog, (dialogContext, result) => {...});
 ````
 
-#### Using channel's native location widget if available (e.g. Facebook):
+### Using FB Messenger's location picker GUI dialog 
+FB Messenger supports a location picker GUI dialog to let the user select an address. If you prefer to use FB Messenger's native dialog,  pass the `LocationOptions.UseNativeControl` option in the location control's constructor.  
 
 ````C#
 var apiKey = WebConfigurationManager.AppSettings["BingMapsApiKey"];
-var prompt = "Hi, where would you like me to ship to your widget?";
+var prompt = "Where should I ship your order? Type or say an address.";
 var locationDialog = new LocationDialog(apiKey, message.ChannelId, prompt, LocationOptions.UseNativeControl);
 context.Call(locationDialog, (dialogContext, result) => {...});
 ````
 
-#### Using channel's native location widget if available (e.g. Facebook) and having Bing try to reverse geo-code the provided coordinates to automatically fill-in address fields:
+FB Messenger by default returns only the lat/long coordinates for any address selected via the location picker GUI dialog. You can additionally use the `LocationOptions.ReverseGeocode` option to have Bing reverse geocode the returned coordinates and automatically fill in the remaining address fields. 
 
 ````C#
 var apiKey = WebConfigurationManager.AppSettings["BingMapsApiKey"];
-var prompt = "Hi, where would you like me to ship to your widget?";
+var prompt = "Where should I ship your order? Type or say an address.";
 var locationDialog = new LocationDialog(apiKey, message.ChannelId, prompt, LocationOptions.UseNativeControl | LocationOptions.ReverseGeocode);
 context.Call(locationDialog, (dialogContext, result) => {...});
 ````
 
-#### Specifying required fields to have the dialog prompt the user for if missing from address:
+**Note**: Reverse geocoding is an inherently imprecise operation. For that reason, when the reverse geocode option is selected, the location control will collect only the `PostalAddress.Locality`, `PostalAddress.Region`, `PostalAddress.Country` and `PostalAddress.PostalCode` fields and ask the user to provide the desired street address manually. 
+
+### Specifying required fields 
+You can specify required location fields that need to be collected by the control. If the user does not provide values for one or more required fields, the control will prompt him to fill them in. You can specify required fields by passing them in the location control's constructor using the `LocationRequiredFields` enumeration. The example specifies the street address and postal (zip) code as required. 
+
 ````C#
 var apiKey = WebConfigurationManager.AppSettings["BingMapsApiKey"];
-var prompt = "Hi, where would you like me to ship to your widget?";
+var prompt = "Where should I ship your order? Type or say an address.";
 var locationDialog = new LocationDialog(apiKey, message.ChannelId, prompt, LocationOptions.None, LocationRequiredFields.StreetAddress | LocationRequiredFields.PostalCode);
 context.Call(locationDialog, (dialogContext, result) => {...});
 ````
 
-#### Example on how to handle the returned place:
+### Handling returned location
+The following example shows how you can leverage the location object returned by the location control in your bot code. 
+
 ````C#
 var apiKey = WebConfigurationManager.AppSettings["BingMapsApiKey"];
-var prompt = "Hi, where would you like me to ship to your widget?";
+var prompt = "Where should I ship your order? Type or say an address.";
 var locationDialog = new LocationDialog(apiKey, message.ChannelId, prompt, LocationOptions.None, LocationRequiredFields.StreetAddress | LocationRequiredFields.PostalCode);
 context.Call(locationDialog, (context, result) => {
     Place place = await result;
@@ -58,20 +75,18 @@ context.Call(locationDialog, (context, result) => {
     }
     else
     {
-        await context.PostAsync("OK, I won't be shipping it");
+        await context.PostAsync("OK, cancelled");
     }
 }
 ````
 
-## Use [LocationOptions](BotBuilderLocation/LocationOptions.cs) to customize the location experience:
+## Sample Bot
+You can find a sample bot that uses the Bing location control in the [BotBuilderLocation.Sample](BotBuilderLocation.Sample) directory. Please note that you need to obtain a Bing Maps API subscription key from [Azure Portal](https://azure.microsoft.com/en-us/marketplace/partners/bingmaps/mapapis/) to run the sample.
 
-*UseNativeControl:*
+## More Information
+Read these resources for more information about the Microsoft Bot Framework, Bot Builder SDK and Bing Maps REST Services:
 
-Some of the channels (e.g. Facebook) has a built in location widget. Use this option to indicate if you want the `LocationDialog` to use it when available.
-
-
-*ReverseGeocode:*
-
-Use this option if you want the location dialog to reverse lookup geo-coordinates before returning. This can be useful if you depend on the channel location service or native control to get user location but still want the control to return to you a full address.
-
-Note: Due to the inheritably lack of accuracy of reverse geo-coders, we only use it to capture: `PostalAddress.Locality, PostalAddress.Region PostalAddress.Country and PostalAddress.PostalCode`.
+* [Microsoft Bot Framework Overview](https://docs.botframework.com/en-us/)
+* [Microsoft Bot Framework Bot Builder SDK](https://github.com/Microsoft/BotBuilder)
+* [Microsoft Bot Framework Samples](https://github.com/Microsoft/BotBuilder-Samples)
+* [Bing Maps REST Services Documentation](https://msdn.microsoft.com/en-us/library/ff701713.aspx)

Contributing.md

@@ -31,10 +31,10 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
 
 ## Contributing bug fixes and features
 
-BotBuilder Samples is currently accepting contributions in the form of bug fixes and new features. Any submission must have an issue tracking it in the issue tracker that has been approved by the BotBuilder team. Your pull request should include a link to the bug that you are fixing. If you've submitted a PR for a bug, please post a comment in the bug to avoid duplication of effort.
+We are currently accepting contributions in the form of bug fixes and new features. Any submission must have an issue tracking it in the issue tracker that has been approved by the BotBuilder team. Your pull request should include a link to the bug that you are fixing. If you've submitted a PR for a bug, please post a comment in the bug to avoid duplication of effort.
 
 ## Legal
 
 If your contribution is more than 15 lines of code, you will need to complete a Contributor License Agreement (CLA). Briefly, this agreement testifies that you are granting us permission to use the submitted change according to the terms of the project's license, and that the work being submitted is under appropriate copyright.
 
-Please submit a Contributor License Agreement (CLA) before submitting a pull request. You may visit https://cla.azure.com to sign digitally. Alternatively, download the agreement ([Microsoft Contribution License Agreement.docx](https://www.codeplex.com/Download?ProjectName=typescript&DownloadId=822190) or [Microsoft Contribution License Agreement.pdf](https://www.codeplex.com/Download?ProjectName=typescript&DownloadId=921298)), sign, scan, and email it back to <cla@microsoft.com>. Be sure to include your github user name along with the agreement. Once we have received the signed CLA, we'll review the request. 
+Please submit a Contributor License Agreement (CLA) before submitting a pull request. You may visit https://cla.azure.com to sign digitally. Alternatively, download the agreement ([Microsoft Contribution License Agreement.docx](https://www.codeplex.com/Download?ProjectName=typescript&DownloadId=822190) or [Microsoft Contribution License Agreement.pdf](https://www.codeplex.com/Download?ProjectName=typescript&DownloadId=921298)), sign, scan, and email it back to <cla@microsoft.com>. Be sure to include your github user name along with the agreement. Once we have received the signed CLA, we'll review the request. 

LICENSE.md

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

Node/Readme.md

@@ -0,0 +1,130 @@
+# Bing Location Control for Microsoft Bot Framework
+
+## Overview
+The following examples demonstrate how to use the Bing location control to collect and validate the user's location with your Microsoft Bot Framework bot in Node.js.
+
+## Prerequisites
+To start using the control, you need to obtain a Bing Maps API subscription key. You can sign up to get a free key with up to 10,000 transactions per month in [Azure Portal](https://azure.microsoft.com/en-us/marketplace/partners/bingmaps/mapapis/).
+
+## Code Highlights
+
+### Usage
+Install the BotBuilder and Restify modules using npm.
+
+    npm install --save botbuilder-location
+       
+    var locationDialog = require('botbuilder-location');
+
+### Calling the location control with default parameters
+The example initiates the location control with default parameters, which returns a custom prompt message asking the user to provide an address. 
+
+````JavaScript
+locationDialog.getLocation(session,
+ { prompt: "Where should I ship your order? Type or say an address." });
+````
+
+### Using FB Messenger's location picker GUI dialog 
+FB Messenger supports a location picker GUI dialog to let the user select an address. If you prefer to use FB Messenger's native dialog,  pass the `useNativeControl: true` option.
+
+````JavaScript
+var options = {
+    prompt: "Where should I ship your order? Type or say an address.",
+    useNativeControl: true
+};
+locationDialog.getLocation(session, options);
+````
+
+FB Messenger by default returns only the lat/long coordinates for any address selected via the location picker GUI dialog. You can additionally use the `reverseGeocode: true` option to have Bing reverse geocode the returned coordinates and automatically fill in the remaining address fields. 
+
+````JavaScript
+var options = {
+    prompt: "Where should I ship your order? Type or say an address.",
+    useNativeControl: true,
+    reverseGeocode: true
+};
+locationDialog.getLocation(session, options);
+````
+
+Note: Due to the inheritably lack of accuracy of reverse geo-coders, we only use it to capture: `PostalAddress.Locality, PostalAddress.Region PostalAddress.Country and PostalAddress.PostalCode`.
+
+**Note**: Reverse geocoding is an inherently imprecise operation. For that reason, when the reverse geocode option is selected, the location control will collect only the `locality`, `region`, `country` and `postalCode` fields and ask the user to provide the desired street address manually. 
+
+### Specifying required fields 
+You can specify required location fields that need to be collected by the control. If the user does not provide values for one or more required fields, the control will prompt him to fill them in. You can specify required fields by passing them in the `requiredFields` parameter. The example specifies the street address and postal (zip) code as required. 
+
+````JavaScript
+var options = {
+    prompt: "Where should I ship your order? Type or say an address.",
+    requiredFields:
+        locationDialog.LocationRequiredFields.streetAddress |
+        locationDialog.LocationRequiredFields.postalCode
+}
+locationDialog.getLocation(session, options);
+````
+
+### Handling returned location
+The following example shows how you can leverage the location object returned by the location control in your bot code. 
+
+````JavaScript
+locationDialog.create(bot);
+
+bot.dialog("/", [
+    function (session) {
+        locationDialog.getLocation(session, {
+            prompt: "Where should I ship your order? Type or say an address.",
+            requiredFields: 
+                locationDialog.LocationRequiredFields.streetAddress |
+                locationDialog.LocationRequiredFields.locality |
+                locationDialog.LocationRequiredFields.region |
+                locationDialog.LocationRequiredFields.postalCode |
+                locationDialog.LocationRequiredFields.country
+        });
+    },
+    function (session, results) {
+        if (results.response) {
+            var place = results.response;
+            session.send(place.streetAddress + ", " + place.locality + ", " + place.region + ", " + place.country + " (" + place.postalCode + ")");
+        }
+        else {
+            session.send("OK, I won't be shipping it");
+        }
+    }
+]);
+````
+
+## Location Control Options
+The following options are supported today by the location control. 
+
+````JavaScript
+export interface ILocationPromptOptions {
+    prompt: string;
+    requiredFields?: requiredFieldsDialog.LocationRequiredFields;
+    useNativeControl?: boolean,
+    reverseGeocode?: boolean
+}
+````
+#### Parameters
+
+*prompt*    
+The prompt shown  to the user when the location control is initiated. 
+
+*requiredFields*    
+Required location fields to be collected by the control. Available options include: streetAddress, locality, region, postalCode, country
+
+*useNativeControl*    
+Boolean to indicate if the control will use FB Messenger's location picker GUI dialog. It does not have any effect on other messaging channels. 
+
+*reverseGeocode*    
+Boolean to indicate if the control will try to reverse geocode the lat/long coordinates returned by FB Messenger's location picker GUI dialog. It does not have any effect on other messaging channels.
+
+## Sample Bot
+You can find a sample bot that uses the Bing location control in the [Sample](sample/) directory. Please note that you need to obtain a Bing Maps API subscription key from [Azure Portal](https://azure.microsoft.com/en-us/marketplace/partners/bingmaps/mapapis/) to run the sample.
+
+## More Information
+Read these resources for more information about the Microsoft Bot Framework, Bot Builder SDK and Bing Maps REST Services:
+
+* [Microsoft Bot Framework Overview](https://docs.botframework.com/en-us/)
+* [Microsoft Bot Framework Bot Builder SDK](https://github.com/Microsoft/BotBuilder)
+* [Microsoft Bot Framework Samples](https://github.com/Microsoft/BotBuilder-Samples)
+* [Bing Maps REST Services Documentation](https://msdn.microsoft.com/en-us/library/ff701713.aspx)
+

Node/core/Readme.md

@@ -1,54 +1,60 @@
-# Microsoft Bot Builder Location Control
+# Bing Location Control for Microsoft Bot Framework
 
-This dialog provides a location control, powered by Bing's Maps REST Services, to make the process of getting the user's location easy and consistent across all messaging channels supported by the bot framework.
+## Overview
+The following examples demonstrate how to use the Bing location control to collect and validate the user's location with your Microsoft Bot Framework bot in Node.js.
 
-## Usage
-Get the BotBuilder and Restify modules using npm.
+## Prerequisites
+To start using the control, you need to obtain a Bing Maps API subscription key. You can sign up to get a free key with up to 10,000 transactions per month in [Azure Portal](https://azure.microsoft.com/en-us/marketplace/partners/bingmaps/mapapis/).
+
+## Code Highlights
+
+### Usage
+Install the BotBuilder and Restify modules using npm.
 
     npm install --save botbuilder-location
-
-From your bot, use the location control
-        
+       
     var locationDialog = require('botbuilder-location');
 
-You can refer to [this sample](../sample/app.js) that demonstrates usage.
-
-## Examples
-
-The following examples demonstrate how to use LocationDialog to achieve different scenarios: 
-
-#### Calling LocationDialog with default parameters 
+### Calling the location control with default parameters
+The example initiates the location control with default parameters, which returns a custom prompt message asking the user to provide an address. 
 
 ````JavaScript
 locationDialog.getLocation(session,
- { prompt: "Hi, where would you like me to ship to your widget?" });
+ { prompt: "Where should I ship your order? Type or say an address." });
 ````
 
-#### Using channel's native location widget if available (e.g. Facebook) 
+### Using FB Messenger's location picker GUI dialog 
+FB Messenger supports a location picker GUI dialog to let the user select an address. If you prefer to use FB Messenger's native dialog,  pass the `useNativeControl: true` option.
 
 ````JavaScript
 var options = {
-    prompt: "Hi, where would you like me to ship to your widget?",
+    prompt: "Where should I ship your order? Type or say an address.",
     useNativeControl: true
 };
 locationDialog.getLocation(session, options);
 ````
 
-#### Using channel's native location widget if available (e.g. Facebook) and having Bing try to reverse geo-code the provided coordinates to automatically fill-in address fields.
+FB Messenger by default returns only the lat/long coordinates for any address selected via the location picker GUI dialog. You can additionally use the `reverseGeocode: true` option to have Bing reverse geocode the returned coordinates and automatically fill in the remaining address fields. 
 
 ````JavaScript
 var options = {
-    prompt: "Hi, where would you like me to ship to your widget?",
+    prompt: "Where should I ship your order? Type or say an address.",
     useNativeControl: true,
     reverseGeocode: true
 };
 locationDialog.getLocation(session, options);
 ````
 
-#### Specifying required fields to have the dialog prompt the user for if missing from address.
+Note: Due to the inheritably lack of accuracy of reverse geo-coders, we only use it to capture: `PostalAddress.Locality, PostalAddress.Region PostalAddress.Country and PostalAddress.PostalCode`.
+
+**Note**: Reverse geocoding is an inherently imprecise operation. For that reason, when the reverse geocode option is selected, the location control will collect only the `locality`, `region`, `country` and `postalCode` fields and ask the user to provide the desired street address manually. 
+
+### Specifying required fields 
+You can specify required location fields that need to be collected by the control. If the user does not provide values for one or more required fields, the control will prompt him to fill them in. You can specify required fields by passing them in the `requiredFields` parameter. The example specifies the street address and postal (zip) code as required. 
+
 ````JavaScript
 var options = {
-    prompt: "Hi, where would you like me to ship to your widget?",
+    prompt: "Where should I ship your order? Type or say an address.",
     requiredFields:
         locationDialog.LocationRequiredFields.streetAddress |
         locationDialog.LocationRequiredFields.postalCode
@@ -56,14 +62,16 @@ var options = {
 locationDialog.getLocation(session, options);
 ````
 
-#### Example on how to handle the returned place. For more info, see [place](src/place.ts)
+### Handling returned location
+The following example shows how you can leverage the location object returned by the location control in your bot code. 
+
 ````JavaScript
 locationDialog.create(bot);
 
 bot.dialog("/", [
     function (session) {
         locationDialog.getLocation(session, {
-            prompt: "Hi, where would you like me to ship to your widget?",
+            prompt: "Where should I ship your order? Type or say an address.",
             requiredFields: 
                 locationDialog.LocationRequiredFields.streetAddress |
                 locationDialog.LocationRequiredFields.locality |
@@ -84,7 +92,8 @@ bot.dialog("/", [
 ]);
 ````
 
-## Location Dialog Options
+## Location Control Options
+The following options are supported today by the location control. 
 
 ````JavaScript
 export interface ILocationPromptOptions {
@@ -94,20 +103,27 @@ export interface ILocationPromptOptions {
     reverseGeocode?: boolean
 }
 ````
-
 #### Parameters
 
 *prompt*    
-The prompt posted to the user when dialog starts. 
+The prompt shown  to the user when the location control is initiated. 
 
 *requiredFields*    
-Determines the required fields. The required fields are: streetAddress, locality, region, postalCode, country
+Required location fields to be collected by the control. Available options include: streetAddress, locality, region, postalCode, country
 
 *useNativeControl*    
-Some of the channels (e.g. Facebook) has a built in location widget. Use this option to indicate if you want the LocationDialog to use it when available.
+Boolean to indicate if the control will use FB Messenger's location picker GUI dialog. It does not have any effect on other messaging channels. 
 
 *reverseGeocode*    
-Use this option if you want the location dialog to reverse lookup geo-coordinates before returning. 
-This can be useful if you depend on the channel location service or native control to get user location
-but still want the control to return to you a full address.
+Boolean to indicate if the control will try to reverse geocode the lat/long coordinates returned by FB Messenger's location picker GUI dialog. It does not have any effect on other messaging channels.
 
+## Sample Bot
+You can find a sample bot that uses the Bing location control in the [Sample](../sample) directory. Please note that you need to obtain a Bing Maps API subscription key from [Azure Portal](https://azure.microsoft.com/en-us/marketplace/partners/bingmaps/mapapis/) to run the sample.
+
+## More Information
+Read these resources for more information about the Microsoft Bot Framework, Bot Builder SDK and Bing Maps REST Services:
+
+* [Microsoft Bot Framework Overview](https://docs.botframework.com/en-us/)
+* [Microsoft Bot Framework Bot Builder SDK](https://github.com/Microsoft/BotBuilder)
+* [Microsoft Bot Framework Samples](https://github.com/Microsoft/BotBuilder-Samples)
+* [Bing Maps REST Services Documentation](https://msdn.microsoft.com/en-us/library/ff701713.aspx)

README.md

@@ -0,0 +1,52 @@
+# Bing Location Control for Microsoft Bot Framework
+
+## Overview
+The Bing location control for Microsoft Bot Framework makes the process of collecting and validating the user's desired location in a conversation easy and reliable. The control is available for C# and Node.js and works consistently across all channels supported by Bot Framework. 
+
+![Location Control Top Screenshot](Images/skype_multiaddress_1.png)
+
+## Use Case and Features
+Bots often need the user's location to complete a task. For example, a Taxi bot requires the user's pickup and destination address before requesting a ride. Similarly, a Pizza bot must know the user's delivery address to submit the order, and so on. Normally, bot developers need to use a combination of location or place APIs, and have their bots engage in a multi-turn dialog with users to get their desired location and subsequently validate it. The development steps are usually complicated and error-prone.  
+
+The Bing location control makes this process easy by abstracting away the tedious coding steps to let the user pick a location and reliably validate it. The control offers the following capabilities: 
+
+- Address look up and validation using Bing's Maps REST services. 
+- User location returned as strongly-typed object complying with schema.org.
+- Address disambiguation when more than one address is found.
+- Support for declaring required location fields.
+- Support for FB Messenger's location picker GUI dialog.
+- Open-source code (C# and Node.js) with customizable dialog strings. 
+
+## Prerequisites
+To start using the control, you need to obtain a Bing Maps API subscription key. You can sign up to get a free key with up to 10,000 transactions per month in [Azure Portal](https://azure.microsoft.com/en-us/marketplace/partners/bingmaps/mapapis/).
+
+## Getting Started
+Navigate to the [C#](/CSharp) or [Node.js](/Node) folder and follow the guide to add the control to your Bot Framework bot. 
+
+## Examples
+The examples show different location selection scenarios supported by the Bing location control. 
+
+### Address selection with single result returned
+
+![Single Address](Images/skype_singleaddress_2.png)
+
+### Address selection with multiple results returned
+
+![Multiple Addresses](Images/skype_multiaddress_1.png)
+
+### Address selection with required fields filling
+
+![Required Fields](Images/skype_requiredaddress_1.png)
+
+### Address selection using FB Messenger's location picker GUI dialog
+
+![Messenger Location Dialog](Images/messenger_locationdialog_1.png)
+
+## More Information
+Read these resources for more information about the Microsoft Bot Framework, Bot Builder SDK and Bing Maps REST Services:
+
+* [Microsoft Bot Framework Overview](https://docs.botframework.com/en-us/)
+* [Microsoft Bot Framework Bot Builder SDK](https://github.com/Microsoft/BotBuilder)
+* [Microsoft Bot Framework Samples](https://github.com/Microsoft/BotBuilder-Samples)
+* [Bing Maps REST Services Documentation](https://msdn.microsoft.com/en-us/library/ff701713.aspx)
+