Place Locator

Place Locator

Asset Version: 1.0.0
  • Version 1.0.0
Last Published: Apr 28, 2017 By: Kony Team
478 4 0 61
The component has a powerful map interface that allows user to search for points of interest near a specified location. It comes preconfigured with Google Places API as backend services; you can easily map it to backend data source of your choice.

Requirements

  • Visualizer Enterprise
  • MobileFabric
 

Devices

 

Platforms

Features

  • Map interface to search for nearby places
  • Comes preconfigured with Google Places backend servcies with 8 place types to search for
  • Get Directions using Google/Apple maps
  • Easily configurable- customize as per your requiement
  • Connect with any backend data source 

Platforms Supported

  • Android Phone Native
  • iPhone Native

Prerequisites

  • Kony account
  • Kony Visualizer Enterprise 7.3
  • Kony MobileFabric 7.3
  • A Kony Reference Architecture app created in Kony Visualizer

PlaceLocator is a component that provides you the capability of locating the selected category of places nearby the specified location. The PlaceLocator component searches for places in the specified location and displays the results in the map view and in the list view along with place images. In the component, you have an option to define the default search range, so that PlaceLocator searches for the places within the specified range from the location point.

The PlaceLocator component contains a set of search menu icons (Bank, Restaurant, and so on) to search for a particular category of places. The app users can tap any one of the icons, and get the results of places of the selected category in the specified location. The search results also provide contact and address details of the places. After fetching the search results, the component allows users to filter the results based on the ratings of the place. The component also retains upto five recent search results for later references. The search result in the map view is capable to move to a different map area, and display the results in that area using the Search this area option available on the map.

You can import the PlaceLocator component into your app (created in Kony Visualizer), and achieve the feature to search for particular places in specific location. The PlaceLocator component also facilitates a set of properties, an event and an API that helps you customize the fields and functionality if required.

The following sections help you use the PlaceLocator component in your app.

Prerequisites

Before you start using the PlaceLocator component, ensure the following:

  1. Kony account
  2. Kony Visualizer Enterprise 7.3
  3. Kony MobileFabric 7.3
  4. A Kony Reference Architecture app in Visualizer. You can create a Kony Reference Architecture app in Visualizer using the following procedure:
    1. Open Kony Visualizer.
    2. On the File Menu, click New Project. The New Project dialog appears.
    3. In the Project Name box, type a name for your project.
    4. Select Kony Reference Architecture, and click Create.
  5. Configure map widget key in your app in Kony Visualizer. For more information, see Generating and Configuring Map API Keys.
  6. For Android apps, add the location related permissions under Manifest Properties in Kony Visualizer.
    1. Open the application, and click Project Settings icon. The Project Settings dialog appears.
    2. Click the Native tab, and then click the Android sub-tab.
    3. Under Manifest Properties, click the Permissions tab.

      placelocator_mappermission.png
    4. Select the following options from the left pane, and click Add. Make sure that the options are moved to the right pane.
      • ACCESS_COARSE_LOCATION
      • ACCESS_FINE_LOCATION
      • ACCESS_LOCATION_EXTRA_COMMANDS
    5. Click Finish.

Importing the PlaceLocator Component

Before you start importing the component to Kony Visualizer, you must download the component from the Kony Marketplace website. You can import the marketplace components only into the apps that are of the Kony Reference Architecture type.

  1. Open your app project in Kony Visualizer.
  2. On the File menu, point to Import, and click Component. The Open dialog appears.
  3. Navigate to the location where you downloaded the component (zip file) on your computer, select the component, and click Open. The Import Marketplace Item dialog appears.
    placelocator_import.png
  4. In the Library Name box, type a name if you want to create a new library. Otherwise, you can select the existing library name.
  5. In the Collection Name box, type a name if you want to create a new collection. Otherwise, you can select the existing collection name.
  6. In the Component Name box, the com.konymp.placelocator name is displayed by default. If you want, you can rename it.

When you import a component, the component is imported to Visualizer's workspace, but not directly into your app. So after importing a component, you must add the component to your app.

Adding a PlaceLocator Component to your App

You can add a PlaceLocator component to FlexForm, FlexContainer, and FlexScrollContainer widgets. Before you add a component to your app, ensure that you are logged on to your Kony account.

To add a PlaceLocator component, do the following:

  1. Open your app, and then the form to which you want to add the component.
  2. From the Collections tab, drag the component onto the form on the Visualizer canvas. The component will be added to the form.
    Once you drag the component to a form, you will see the component added to the form. You will also see a new set of elements under the Components section on the Templates tab.

After adding a component to a form, you can configure the component the way you want it using the Look, Skin, and Action tabs on the Properties pane. Configuring the properties on the Properties pane is similar to configuring the properties of any widget in Kony Visualizer. For example, refer Button Widget.

You can also see a new tab, Component, is added on the Properties pane. The Component tab contains assorted properties relevant to the component that allow you to customize the component as required. The properties on the Component tab are categorized as Pass Through and Custom properties. The Pass Through properties are the default properties of individual widgets in the component. Custom Properties are user-defined properties based on the use case of the component.

Note:

Changes made to the Custom properties are reflected only during run time, but not during design time (Visualizer Canvas).

You can also add a PlaceLocator component dynamically. To do so,

  1. In the Project Explorer, on the Projects tab, click the context menu arrow of Modules, and then click New JS module. A new JavaScript file opens in the Code Editor.
  2. Copy and paste the following code snippet in the JavaScript file.
    /** Creating component's object **/
    			var placeLocator = new com.konymp.placelocator({
                    "clipBounds": true,
                    "height": "100%",
                    "id": "placeLocator",
                    "isVisible": true,
                    "layoutType": kony.flex.FREE_FORM,
                    "masterType": constants.MASTER_TYPE_USERWIDGET,
                    "skin": "sknFlexffffff",
                    "width": "100%",
                    "zIndex": 1
                }, {}, {});
    			/** Adding custom and passthrough propeties **/
                placeLocator.googleAPIKey = "AIzaSyD7hjE1bn-nGXWMuqlb-0wFc1Yr8FE0JvI";
                placeLocator.defaultSearchRadius = "2000";
                placeLocator.currentLocationLabelText = "Current Location";
                placeLocator.currentLocationImage = "current_location_mark.png";
    			/** Adding Custom event **/
                placeLocator.getPlaceDetails = this.functionName.bind(this);
    			/** Adding component to form **/
                this.add(placeLocator);

    In the code snippet, you can edit the properties of the component as per your requirement. For more information, see Properties.

  3. Save the file.

Setting Properties

The Properties provided on the Component tab allow you to customize the UI elements and set constraints for fields in the PlaceLocator component. You can set the properties directly on the Component tab or by writing a JavaScript. This section provides information about how to set the properties by writing a JavaScript.

Search Suggestion text for Current Location
Category: Custom
Description: Specifies a placeholder text to be displayed in the search location text field.
Syntax: currentLocationLabelText
Type: String
Read/Write:

Read + Write

Remarks:

The default value of the property is "Current Location".

Example:
this.view.ComponentID.currentLocationLabelText = "Location";

Replace the "ComponentID" with the ID of the component in all examples in this document.
You can find the ID of the component on the Look tab.
You can find the ID of the component on the Look tab.

Default Search Radius
Category: Custom
Description:

Specifies the radius (search range) in meters from the location point.

Syntax: defaultSearchRadius
Type: Number
Read/Write:

Read + Write

Remarks: The search is performed within the specified range (radius). The radius for the Search this area option is determined based on the visible region of the device, but not using the Default Search Radius property.
Example:
this.view.ComponentID.defaultSearchRadius = 5000;
Current Location map Pin image
Category: Custom
Description: Specifies the file name of the image to be set as location icon on the search location text field.
Syntax: currentLocationImage
Type: String
Read/Write:

Read + Write

Remarks:

Before setting the property:

  • ensure that the image file exists in the workspace\resources\common directory.
  • The file name of the image should not contain any upper case characters.
  • Specify the image’s file name along with extension.
  • Only PNG format images are supported.
Example:
this.view.ComponentID.currentLocationImage= "locIcon.png";
Google API Key
Category: Custom
Description: Specifies a Google API key to authenticate to obtain the search results from Google location services.
Syntax: googleAPIKey
Type: String
Read/Write:

Read + Write

Remarks:

The default value of the property is null. If you do not specify the key, the services fail to work. To learn how to get a Google API key, see Get API Key.

Using single key, you can make 1000 free requests per 24 hours. For more information, refer Usage Limits and Billing.

Search Button text
Category: Pass Through
Description: Specifies a text to be displayed on the Search button.
Syntax: searchButtonText
Type: String
Read/Write:

Read + Write

Remarks: The default value of the property is "Search".
Example:
this.view.ComponentID.searchButtonText  = "Search";
Place Categories heading
Category: Pass Through
Description: Specifies a text to be displayed on top of the search menu items.
Syntax: suggestedPlaceTypesHeading
Type: String
Read/Write:

Read + Write

Remarks:

The default value of the property is “WHAT ARE YOU LOOKING FOR?”.

Example:
this.view.ComponentID.suggestedPlaceTypesHeading= “Searching for?”;

Defining Events

You can define events to be executed when an action is performed. You can configure the events directly on the Actions tab or by writing a JavaScript. To configure the events on the Actions tab, click Edit against each event. For more information, refer Add Actions.

This section provides details about each event that help you define the actions by writing a JavaScript.

getPlaceDetails
Description: The event is invoked when a user clicks a place in the list view or in the map view, which is displayed at the bottom of the map when map pin is clicked. In the event, you can define actions to be executed when user clicks a place.
Syntax: getPlaceDetails

PlaceLocator MobileFabric App

When you import the component into your app project (Kony Visualizer), a set of services are also imported to the MobileFabric app associated with your project. If no MobileFabric app is associated with your project, a new MobileFabric app with same name as your project's name is created and PlaceLocator services gets imported into that app.

If the import of MobileFabric service fails, delete the PlaceLocator component and import it again.

Note:

Ensure that you are logged on to your Kony account.

The PlaceLocator MobileFabric app contains a set of integration, orchestration, and objects services by default. Using these services, the PlaceLocator component is configured with Google Places APIs, which helps in locating the places of a specific location. Using the MobileFabric console, you can view and modify these services and also create new services. If you want, you can also decouple the component with Google Map APIs and configure with other Map API services.

Integration Service

The PlaceLocator MobileFabric app contains the GoogleService integration service. By default, the GoogleService integration service is configured to connect the PlaceLocator component to the Google Places APIs.

To view the GoogleService integration service, do the following:

  1. Log on to your Kony account. the Dashboard page appears by default.
  2. In the left pane, click the Apps menu. The Custom Apps page appears.
  3. Find and click your <Visualizer Project Name> app. The <Your Project Name> MobileFabric app appears along with the Configure Services tab and the Identity sub-tab opened by default.
    Note:

    You can find the app by typing the app's name in the Search box.

  4. Click the Integration sub-tab. The Integration tab opens with the GoogleService integration service.
  5. Click GoogleService. The Service Definition tab of the selected integration service opens by default.
    placelocator_integration.png

You can edit the GoogleService integration service or create a new integration service as you require. For more information, see Integration Service.

The GoogleService integration service contains the following operations:

  1. getAutoSuggestions operation suggests a list of places that start with the letter(s) entered in the location search box in the PlaceLocator component.
    • searchText: The value entered by user in the Location Searchbox.
    • key: Google Places API key provided by the developer in Visualizer Property Panel.
  2. getPlaceCoordinates operation obtains the latitude and longitude values of the location. The obtained values are based on the location name specified in the search box in the PlaceLocator component.
  • placeID: place ID of the location entered by the user in the Location Searchbox.
  • key: Google Places API key provided by the developer in Visualizer Property Panel.
searchNearBy operation searches for the places within a specified area.

Input Parameters

  • location: the latitude and longitude of the location in which you want search for the places. For example, "17.4474,78.3762" (response of getPlaceCoordinates operation).
  • radius: defines the distance (in meters) within which places need to be searched (value is provided by the developer in Visualizer property panel).
  • type: the type of place that a user selects to search.
  • key: Google Places API key provided by the developer in Visualizer Property Panel.
getPlaceDetails operation obtains more details of each place returned in the search result. For example, address, rating, phone number, and so on.

Input Parameters

  • placeIDValue: ID of a place returned for the search result (response of searchNearBy operation).
  • key: Google Places API key provided by the developer in Visualizer Property Panel.

In the MobileFabric console, you can execute the above operations by specifying the values for the parameters in the boxes under the TEST VALUE and DEFAULT VALUE columns and view the responses of each operation.

The following procedure explains how to execute the getPlaceCoordinates operation and view the response:

  1. Click the Integration sub-tab. The Integration tab opens with the GoogleService integration service.
  2. Click GoogleService. The Service Definition tab of the selected integration service opens by default.
  3. Click Operations List tab. The Operations List tab opens.
  4. In the Configured Operations section, click getPlaceCoordinates. The getPlaceCoordinates tab opens with the Request Input sub-tab and Body section opened by default.
    placelocator_getplacelocator.png
  5. In the box under the TEST VALUE column, type the ID of a place of which you want to view the latitude and longitude values. You can find the ID of a place from PlaceID Finder.
  6. Click Fetch Response. The Output Result dialog appears with the response.

You can follow the above procedure to execute other operations of the GoogleService integration service and view the response.

Orchestration Service

Orchestration services are used to integrate multiple services and exposing them as a single service.

To view the orchestration services, do the following:

  1. After logging on to your Kony account, open your Project Name MobileFabric app.
  2. Click the Orchestration sub-tab. The Orchestration sub-tab opens with a list of services.
    placelocator_orchestration.png
  3. Click any one of the services. For example, GetPlaceDetailsLoop. The Service Definition tab of the selected orchestration service opens by default.
  4. Click Operations tab to view the operations of the selected service.
    placelocator_getdetails.png

We are using orchestration services to overcome one of the limitations of the Google Places API; The getPlaceDetails operation returns phone number of only one place at a time. So, we use orchestration services to make multiple calls to Google, to fetch phone numbers of all the places returned in the search result.

  1. GetPlaceDetailsLoop service contains the getDetails operation. The operation takes IDs of all the places returned in the search result and extracts the phone numbers of the places.
  2. NearbyUsingCoordinates service contains the getNearbyUsingCoordinates operation. The operationmaps and returns the place details of all the place results returned by the searchNearBy integration service with the phone numbers fetched by GetPlaceDetailsLoop orchestration service based on the placeID parameter.

Object Services (App Data Model)

The object services help you define the app data model and configure with relevant back end services. The PlaceLocator component comes with a predefined app data model, which is mapped with the Google Places APIs as a back end service.

Place Locator App Data Model Objects

  1. AutoSuggestions is mapped with the getAutoSuggestions operation of the GoogleSerivce integration service.
  2. GetLocationCoordinatesUsingPlaceID is mapped with the getPlaceCoordinates operation.
  3. SearchNearbyUsingCoordinates is mapped with the NearbyUsingCoordinates orchestration service.

To view the object service and the app data model, do the following:

  1. After logging on to your Kony account, open the <your project name> MobileFabric app.
  2. Click the Objects sub-tab. The Objects sub-tab displays the app data model objects.
    placelocator_object.png
  3. Click any one object, (For example, AutoSuggestions) it will expand to show its default Fields.
  4. Click Fields item to add, delete, or modify service.
    placelocator_autosuggestion.png

Configuring Place-Types

The PlaceLocator component is readily configured with following place types which a user can search for:

  1. Banks: searches and shows banks near the specified location.
  2. Restaurants: searches and shows restaurants near the specified location.
  3. Bars: searches and shows bars near the specified location.
  4. Museums: searches and shows museums near the specified location.
  5. Coffee Shops: searches and shows coffee shops near the specified location.
  6. Entertainment: searches and shows entertainment options near the specified location.
  7. Shopping: searches and shows shopping centers near the specified location.

You can also add new Place-types or edit the existing one. To add a new Place-type, use the API createDynamicMenu and provide an array of JSON with the following parameters:

  • displayText: Specify the text to be displayed to user for the Place-type (Example: Restaurants, Coffee shops etc.).
  • browseKeyword : Enter the Google Places keyword for the Place-type you are adding (the component comes readily configured with Google Places API backend service which only supports Place-types mentioned here). For more information, see Supported Types.
  • placeTypeIcon_unselected: Specify the file name of the image to be set as the Place-type icon in the search menu.
  • placeTypeIcon_selected: Specify the file name of the image that represents the selected-state of Place-type icon in the search menu.
  • mapPin: Specify the file name of the image to be set as map pin to show up in the map view for the Place-type.
  • mapPin_selected: Specify the file name of the image, which represents selected-state of the map pin of the Place-type.
Note:

You can have only upto eight Place-types in the PlaceLocator component. If you provide more than eight Place-types in JSON to the API createDynamicMenu, only the top eight Place-types will be displayed. The other Place Types in the component are ignored.

Example

[{
                "placeTypeIcon_selected" : "restaurants_selected.png",
                "placeTypeIcon_unselected" : "restaurants.png",
                "browseKeyword" : "restaurant",
                "displayText" : "Restaurants",
                "mapPin" : "restaurants_pin.png",
                "mapPin_selected" : "restaurants_pin_active.png"
            }]

The following code is the JSON array that defines existing Place-types. If you want to make any changes to the existing place-types, you can edit the parameters in the code as per your requirement. Then, define a function in your app, and add the modified code inside the function. After that, call the function using the this.view.placeLocator.createDynamicMenu API in pre show of the form on which PlaceLocator is added.

[
              {
                "placeTypeIcon_selected" : "restaurants_selected.png",
                "placeTypeIcon_unselected" : "restaurants.png",
                "browseKeyword" : "restaurant",
                "displayText" : "Restaurants",
                "mapPin" : "restaurants_pin.png",
                "mapPin_selected" : "restaurants_pin_active.png"
              },
              {
                "placeTypeIcon_selected" : "coffee_shops_selected.png",
                "placeTypeIcon_unselected" : "coffee_shops.png",
                "browseKeyword" : "cafe",
                "displayText" : "Coffee Shops",
                "mapPin" : "coffee_shops_pin.png",
                "mapPin_selected" : "coffee_shops_pin_active.png"
              },
              {
                "placeTypeIcon_selected" : "bars_selected.png",
                "placeTypeIcon_unselected" : "bars.png",
                "browseKeyword" : "bar",
                "displayText" : "Bars",
                "mapPin" : "bars_pin.png",
                "mapPin_selected" : "bars_pin_active.png"
              },
              {
                "placeTypeIcon_selected" : "entertainment_selected.png",
                "placeTypeIcon_unselected" : "entertainment.png",
                "browseKeyword" : "movie_theater",
                "displayText" : "Entertainment",
                "mapPin" : "entertainment_pin.png",
                "mapPin_selected" : "entertainment_pin_active.png"
              },
              {
                "placeTypeIcon_selected" : "shopping_selected.png",
                "placeTypeIcon_unselected" : "shopping.png",
                "browseKeyword" : "shopping_mall" ,
                "displayText" : "Shopping",
                "mapPin" : "shopping_pin.png",
                "mapPin_selected" : "shopping_pin_active.png"
              },
              {
                "placeTypeIcon_selected" : "museums_selected.png",
                "placeTypeIcon_unselected" : "museums.png",
                "browseKeyword" : "museum",
                "displayText" : "Museums",
                "mapPin" : "museums_pin.png",
                "mapPin_selected" : "museums_pin_active.png"
              },
              {
                "placeTypeIcon_selected" : "banks_selected.png",
                "placeTypeIcon_unselected" : "banks.png",
                "browseKeyword" : "bank",
                "displayText" : "Banks",
                "mapPin" : "banks_pin.png",
                "mapPin_selected" : "banks_pin_active.png"
              }
            ];

APIs

The following API pertains to the PlaceLocator component.

createDynamicMenu

The API creates menu items on the screen dynamically. You can invoke the API in pre show of the form on which the placeLocator component is placed.

Syntax
createDynamicMenu(menuJSONArray)
Parameters
true [Boolean]:

Enables the rememberMe functionality.
Return Value

None

Remarks

Use the API only if you want to change the menu items.

Example
this.view.ComponentID.createDynamicMenu(menuJSONArray);

Modifying the Existing UI

If the existing UI doesn’t match your requirement, then you can easily modify it by following the instructions given below.

To modify the PlaceLocator UI, do the following:

  1. In the Project explorer, click the Template tab. A list of templates is displayed.
  2. Go to Mobile >> Segments >> datacontainer (segRowTemplate)
  3. Modify/ Delete/ Add widgets to the datacontainer template as per your requirement.
  4. You can also configure data mapped to a widget. See Mapping UI with Data from Object Services.

Example:

The following screen shots illustrate how to remove “timing” label widget from the row-template: tempListView- for the visibility property select off.

placelocator_Modify_UI.png

placelocator_ModifyUI_Property.png

Similarly, you can easily re-arrange Rating flex: in the row template- tempListView; go to flxHolder >> flxHolder1 >> flxContainer >> flxTopCard >> flexRightPane >> flxRating and choose “move up” option in context menu. The following screen shots explains the procedure in detail.

placelocator_ModifyUI_Prop.png

placelocator_ModifyUI_Prop1.png

placelocator_ModifyUI_Prop2.png

Mapping UI with Data from Object Services

You can easily map UI widgets with object services (app data model). Following example illustrates the process of a mapping data with the list view segment.

placelocator_Mapping_UI.png

placelocator_MappingUI_code.png

For example, in the above data, we are fetching the Place Name, Address, Phone Number as Name, Vicinity, Phone fields from the respective Object Services. If you want to map a different field, you can do it by pushing the respective field to the “segmentData” and then adding it to the widgetDataMap as shown below.

placelocator_MappingUI_code1.png

Note:

In our mobile app, we are fetching the entire data from SearchNearbyUsingCoordinates operation of PlaceLocatorObjectServices (which is an orchestration service to fetch all the place details along with phone number). You can change the back end service and map it to the SearchNearbyUsingCoordinates operation.