Maps

Blog
Maps
Friday, September 23, 2016PrintSubscribe
Calculating Driving Distance Between Points

In businesses that require a lot of driving and tracking packages, it is invaluable to estimate a driving distance between two different addresses or sets of latitude/longitude. Starting in release 8.5.11.0, C# and Visual Basic business rules now have access to the CalculateDistance() method. This method will query the Google Distance Matrix API to estimate driving distance.

The results from the CalculateDistance() business rule method displayed in a messsage.

It is required to obtain and add a Maps API Identifier to your project in order to use this feature.

Please make sure to follow Google Maps APIs Terms Of Service. Of note is section 10.5.d, which restricts long-term storage of Content.

Let’s add a custom action to the Employees page that, when pressed, will display how far the employee lives from the main office using a code business rule.

First, we need to add an action that will be accessible to the user in order to trigger the code.

Start the Project Designer. In the Project Explorer, switch to the Controllers tab. Right-click on “Employees / Actions / ag1 (Grid)” node, and press New Action.

Adding an action to grid scope of Employees controller.

Enter the following settings:

Property Value
Command Name Custom
Command Argument DistanceFromHQ
Header Text Distance From HQ
When Key Selected Yes

Press OK to save. Next, let’s create a business rule that will be triggered when the user presses the action. Right-click on “Employees / Business Rules”, and press New Business Rule.

Adding a business rule to Employees controller.

Enter the following properties:

Property Value
Type C# / Visual Basic
Command Name Custom
Command Argument DistanceFromHQ
Phase Execute

Press OK to save the business rule. On the toolbar, press Browse to generate the application and create the rule file.

When generation is complete, press “Edit Rule” on the action bar to open the file in Visual Studio.

Editing the rule in Visual Studio.

Replace the contents with the following:

C#:

using System.Data;
using MyCompany.Data;
using MyCompany.Models;

namespace MyCompany.Rules
{
    public partial class EmployeesBusinessRules : MyCompany.Data.BusinessRules
    {
        
        /// <summary>
        /// This method will execute in any view for an action
        /// with a command name that matches "Custom" 
        /// and argument that matches "DistanceFromHQ".
        /// </summary>
        [Rule("r100")]
        public void r100Implementation(EmployeesModel instance)
        {
            // combine address pieces with ","
            string sourceAddress = string.Join(",", instance.Address, instance.City,
                instance.Region, instance.PostalCode, instance.Country);
            string destinationAddress = "1 Microsoft Way,Redmond,Washington";

            // get distance and calculate miles
            decimal meters = CalculateDistance(sourceAddress, destinationAddress);
            decimal miles = meters * 0.00062137m;

            // show result
            if (meters == 0)
                Result.ShowAlert("No path found.");
            else
                Result.ShowAlert("Distance from HQ is " + meters 
                    + " meters, or " + miles + " miles");
        }
    }
}

Visual Basic:

Imports MyCompany.Data
Imports MyCompany.Models

Namespace MyCompany.Rules
    
    Partial Public Class EmployeesBusinessRules
        Inherits MyCompany.Data.BusinessRules

        ''' <summary>
        ''' This method will execute in any view for an action
        ''' with a command name that matches "Custom" 
        ''' and argument that matches "DistanceFromHQ".
        ''' </summary>
        <Rule("r100")>
        Public Sub r100Implementation(ByVal instance As EmployeesModel)
            ' combine address pieces with ","
            Dim sourceAddress = String.Join(",", instance.Address, instance.City,
                    instance.Region, instance.PostalCode, instance.Country)
            Dim destinationAddress = "1 Microsoft Way,Redmond,Washington"

            ' get distance and calculate miles
            Dim meters = CalculateDistance(sourceAddress, destinationAddress)
            Dim miles = meters * 0.00062137D

            ' show result
            If (meters = 0) Then
                Result.ShowAlert("No path found.")
            Else
                Result.ShowAlert("Distance from HQ is " & meters &
                                 " meters, or " & miles & " miles")
            End If
        End Sub
    End Class
End Namespace

Switch back to the web browser, and press the three dot menu button next to any row to reveal the grid action menu.

Activating the grid scope menu for a row in Touch UI.

Press “Distance From HQ” action, and a message box will display the distance.

The results from the CalculateDistance() business rule method displayed in a messsage.

Note that it is also possible to pass a latitude and longitude by separating the values with a comma, such as in the following example:

CalculateDistance(instance.Latitude + "," + instance.Longitude, destinationAddress)
Thursday, September 22, 2016PrintSubscribe
Geocoding

Geocoding is the process of capturing an address and converting it to exact latitude and longitude coordinates. Starting with release 8.5.11.0, apps generated with Code On Time now support automatic geocoding of address fields with the proper tags, as well as a Geocode() method available in C# or Visual Basic business rules.

Example of result from Geocode method.

Please make sure to follow Google Maps APIs Terms Of Service. Of note is section 10.5.d, which restricts long-term storage of Content.

Both methods below require addition of a Maps API Identifier. The following examples will use a modified version of the Employees table from the Northwind sample project. Use the following script to add the required columns before creating the project.

ALTER TABLE Employees
ADD Latitude decimal(9, 6) NULL,
    Longitude decimal(9, 6) NULL

If using an existing project, make sure to refresh the application after executing the script. Then, open the model for Employees and check the checkbox next to the three new fields to include them in the Employees controller.

Geocoding with Tags

The easiest way to geocode a set of address fields is to tag the source and destination data fields in the view. If the correct fields are tagged, the values will be geocoded when the user saves a new record or updates an existing record. When updating an existing record, the geocode request will only be sent if at least one of the source fields has been modified, in order to avoid extraneous API requests.

Let’s add the relevant tags to start geocoding employees.

Start the Project Designer. In the Project Explorer, double-click on “Employees / container1 / view1 (Employees, grid1) / createForm1 / c1 – New Employees / Address” data field node.

Selecting the Address data field of createForm1 view of Employees controller.

Make the following change:

Property Value
Tags geocode-address

Press OK to save the data field. Use the above procedure to make the changes below:

Data Field Tag
City geocode-city
Region geocode-region
PostalCode geocode-zip
Country geocode-country
Latitude geocode-latitude
Longitude geocode-longitude

On the toolbar, press Browse. When the application opens in the default browser, create a new employee.

Entering a new employee.

Upon pressing Save, the geocode request will be sent. If a result is returned, the new employee record will have updated Latitude and Longitude fields.

The Latitude and Longitude fields have been updated.

Geocoding in C#/Visual Basic Business Rules

The tag method explained in the previous section is convenient for automatic update of Latitude and Longitude fields. However, if the latitude and longitude need to be used in a calculation, the Geocode() business rule method can be used. Let’s add a business rule that utilizes this method to geocode the employee’s address and show an alert with the resulting latitude and longitude.

In the Project Explorer, switch to the Controllers tab. Right-click on “Employees / Actions / ag4 (ActionBar) – Edit/Delete” and press New Action.

Adding a new action to Employees controller.

Specify the following properties and press OK to save the new action.

Property Value
Command Name Custom
Command Argument ShowLatLong
Header Text Show Lat/Long
When Key Selected Yes

Next, right-click on “Employees / Business Rules” node, and press New Business Rule.

Adding a new business rule to Employees controller.

Configure the rule as following:

Property Value
Type C# / Visual Basic
Command Name Custom
Command Argument ShowLatLong
Phase Execute

Press OK to save the new business rule. Then, press Browse on the toolbar to generate the application, as well as create the relevant business rule file.

When complete, press “Edit Rule” on the action bar to open the file in Visual Studio.

Editing the rule in Visual Studio.

Replace the contents of the file with the following:

C#:

using MyCompany.Data;
using MyCompany.Models;

namespace MyCompany.Rules
{
    public partial class EmployeesBusinessRules : MyCompany.Data.BusinessRules
    {
        
        /// <summary>
        /// This method will execute in any view for an action
        /// with a command name that matches "Custom" and argument that matches "ShowLatLong".
        /// </summary>
        [Rule("r100")]
        public void r100Implementation(EmployeesModel instance)
        {

            decimal latitude;
            decimal longitude;

            // join address parts with "," separator
            string address = string.Join(",", instance.Address, instance.City, 
                instance.Region, instance.PostalCode, instance.Country);

            if (Geocode(address, out latitude, out longitude))
            {
                Result.ShowAlert("Latitude: " + latitude + ", Longitude: " + longitude);
            }
            else
            {
                Result.ShowAlert("Geocode failed to resolve address.");
            }
        }
    }
}

Visual Basic:

Imports MyCompany.Data
Imports MyCompany.Models

Namespace MyCompany.Rules
    
    Partial Public Class EmployeesBusinessRules
        Inherits MyCompany.Data.BusinessRules
        
        ''' <summary>
        ''' This method will execute in any view for an action
        ''' with a command name that matches "Custom" and argument that matches "ShowLatLong".
        ''' </summary>
        <Rule("r100")>  _
        Public Sub r100Implementation(ByVal instance As EmployeesModel)
            Dim latitude As Decimal
            Dim longitude As Decimal

            ' join address parts with "," separator
            Dim address = String.Join(",", instance.Address, instance.City,
                            instance.Region, instance.PostalCode, instance.Country)

            If (Geocode(address, latitude, longitude)) Then
                Result.ShowAlert("Latitude: " & latitude & ", Longitude: " & longitude)
            Else
                Result.ShowAlert("Geocode failed to resolve address.")
            End If
        End Sub
    End Class
End Namespace

Switch back to the application running in your default browser, and navigate to the Employees page. Ctrl+click on a row to highlight the row. On the toolbar, press  “Show Lat/Long”.

Activating the "Show Lat/Long" custom action.

A message box will be displayed with the employee’s latitude and longitude.

The popup shows the returned latitude and longitude.

Thursday, September 22, 2016PrintSubscribe
Adding a Google Maps API Key

An API key must be added to the project to use any features that depend on the Google Maps API, such as Maps presentation style, Geocode feature, or CalculateDistance() business rule method. The Google Maps API Key can be acquired here. Make sure to log into your Google account, and press the “GET A KEY” button to get started.

The button to acquire a Google Maps API key.

Once a key has been acquired, start the app generator. Click on the project name, and press Settings. Then, select Features page of the Project Wizard.

Navigating to the Features page of the Project Wizard.

Switch to the Touch UI section. If you have an API key, under “key=” plus the key in the “Google Maps API Identifier” box. If you have a client ID, enter “client=” plus the client ID in the box.

Entering the Maps API Identifier.

Press Next, and proceed to generate the application. The key will be embedded in “web.config” file of the generated application.

The API key can be accessed from any custom code or code business rules via the “ApplicationServices.MapsApiIdentifier” property. It can also be accessed from JavaScript business rules via the “__settings.mapApiIdentifier” property.

It is highly recommended to restrict access to your key to specific websites, IP address, or apps from the Google Developer Console.