How to use location services in Sapho

Audience: Developers building Sapho micro apps

Sapho is meant to be used on mobile devices as well as desktops and comes with a set of features that lets you take advantage of location-based services.

Location-based search

You can set up a search page so that your field team can find records based on their current location. Sapho uses the device’s longitude and latitude, and calls a Google API to convert the coordinates into location variables such as city, state and country. These variables can be used in a search page and as defaults in forms.

Here’s how to set it up:

  1. Go to Pages in the micro app you would like to edit and select the search page you would like to modify.
  2. Click on the list or table component that displays the search results to open up its properties.
  3. Open up the query dialog by clicking SET QUERY.
  4. Set up a constraint using the provided location variables.
  5. Click DONE. Your search page will now only display the records relevant to your actual location.

You can also configure a more advanced search to display records in a radius around your current location.

  1. Here’s how to set up a radius based on your location: Go to the search page you would like to edit, open the list or table component’s properties, and then click SET QUERY.
  2. Click on the Advanced tab and enter an SQL Where Clause to define a radius to search in by incorporating the latitude and longitude location variables.

    Here is an example SQL code for a radius of 5 miles:
    (
    6371 *
    acos(
    cos(radians({{locationLatitude}})) *
    cos(radians(`latitude`)) *
    cos(radians(`longitude`)
    - radians({{locationLongitude}})) +
    sin(radians({{locationLatitude}})) *
    sin(radians(`latitude`))
    )
    ) < 5
  3. Click DONE. Your search page will now display any records located within a 5-mile radius of your current position.

Map component

When you create a list or search over list page, you can also add a Map component to display the results in a Google Maps iframe based on the location of your records.

  1. Go to Pages and click the search or list page you would like to edit.
  2. Add a Map component to the page.
  3. Configure the location-based fields according to your data model. You can use Address, City, State/Province, Zip, and Country fields. The more fields you use, the more accurate the map results will be.
  4. You can also set an action to open a new page when a user clicks on one of the markers on the map. Click Action and then SET QUERY.

Map components can also be used on a detail page in your micro app.

  1. Go to Pages and open the detail page you would like to edit.
  2. Add a Map component to the page.
  3. Configure the location-based fields according to your data model. Use the DB Column field for your configuration.
  4. If you would like to limit the height of your map, you can edit this setting in Map Properties.

Save location-based data

Sapho not only allows you to read location-based variable data but also let’s you save it to your database.

  1. Go to Pages and open up an add or update page that you would like to edit.
  2. Select the add or update button.
  3. Click SET ACTION under Custom Add or Update in the button properties.
  4. Add the DB columns where you would like to save location-based variables. You can select City, State/Province, and Country.
  5. Click SAVE.