You can use the Address Map control (pxAddressMap) to view and interact with location points in Google Maps from either a desktop application or a mobile app using the Pega 7 mobile app. Map points are generated from data that is sourced from a Property, Data page, Clipboard page, or Report definition. Information about a specific location is shown in a pop-up window when the corresponding map point is clicked or tapped.

Obtaining a Google API key

To ensure that pxAddressMap is correctly displayed at run time, you need to obtain a Google API key. In a production environment, it is recommended that you use an enterprise key, because it allows for a greater number of geocoding hits per IP each day.

To obtain a Google API key:

1. Access the Google Developer Console at https://console.developers.google.com and log in to your account.
2. Select your project. (If no project currently exists, create a project.)
3. In the APIs section, turn on Google Maps JavaScript API v3​ and Google Maps Geocoding API.
4. In the Credentials section, create a browser key to use for Public API access.
   • For information about configuring allowed referrers, see the Google Developer documentation.
5. After the key is generated, take note of the API key. You need to set this value in a PRPC Dynamic System Setting in the next procedure.

Setting a Google API key

After you generate the Google API key, you must update this information in a PRPC Dynamic System Setting.

To set the Google API key:

1. Access the Pega 7 Platform.
2. In the Pega 7 Search field, enter googleapikey
3. Click Dynamic System Setting | Pega-EndUserUI | uiengine/map/googleapikey.
4. Enter the value for the previously generated Google API key in the Value field.
5. Click Save.
6. Restart the server.

Configuring the Address Map control

1. In Designer Studio, add the pxAddressMap control to a section or layout by clicking Advanced > Address Map.

The control can be added in a cell in a dynamic or smart layout, to a section, or directly into a harness.

Adding this control to a section or layout displays a static image of a map to indicate the location of the control.

2. Click the Gear icon to open the Cell Properties window for the Address Map control.
3. When you finish configuring the control, click OK, andthen click Save in Designer Studio to apply any changes.

Customizing map functionality

In the Cell Properties window, the General tab displays various configuration settings for how the map is displayed.

• Show User Location - When selected, shows the user's current location on the map with a blue marker pin. This pin is prioritized and is displayed even if the Starting Lat, Long field also contains any values.
• Starting Lat, Long - A point without a pin that is generated by Google Maps as a starting point when mapping a location.​
  • You can either hardcode the starting point into the field by enclosing coordinates within double quotation marks, for example:
    “42.366200, -71.076936”
    or you can use a property reference such as:
    ​.OfficeLocation, SomePage.HomeAddress, EmployeeList.pxResults(1).Location
  • This location does not always displayed as the starting point, because the map initially zooms in or out as it attempts to fit all pins and the user’s current location (if geolocation is active) in the same window.
  • This field is ignored if the Markers Source Type is selected as Property, Data page, Clipboard page, or Report definition.​​

• Visibility- Select the conditions for whether the map is displayed based on user input.

Using the Markers Source section

In the Markers Source section, select the data source to use to display points on the map.

For list-based controls, data in the Marker info section field runs in the current pin’s context. Additionally, the Applies To class of the Marker info section field must be the same for each record that is displayed as a pin on the map.

• In a report definition, the Applies To class must be the same as the Applies To class of a record definition.
• In a data page, the Applies To class must be the Applies To class of pxResults
• In a clipboard page or group, the Applies To class must be the Applies To class of pxResults

The Type menu in this section defaults to "None," but you can select one of the following options from the list:

• Property- If this option is selected, you can also specify the Source (Value or As defined on property), you must specify the Address property (required), and you can specify the Marker info section.
  
  • Value- The value of the property at run time. You can either hardcode the value into the field by enclosing coordinates within double quotation marks, for example:​
    “42.366200, -71.076936”
    or use a property reference such as:
    .OfficeLocation, SomePage.HomeAddress, EmployeeList.pxResults(1).Location

• As defined on property - The local/prompt list as defined on the property rule form, which is in sync with the other list-based controls.
• Allow marker repositioning to change the address value - Changes the address whenever the user updates the current location by dragging the map marker to a new position. The value bound to the Address property field is automatically updated to the new position or, if the new location on the map does not correspond to a human-readable address, the property containing the latitude/longitude coordinates is updated.
• Report lat long in property - Used to track the latitude/longitude coordinates of the marker position on the map. Specified as an optional single-value property.
• Report incorrect address - Enables an error message to be displayed when the address at the new location cannot be found. The text of the error message is configured in the Error message field.
• Error message - An optional error message to display when the address at the new location is not found.
• Data page - If this option selected, you must also specify the Data page (required).
  

  • After specifying the data page to use, the Property for location field must be filled using a list record or by pxResults.

  • For data pages, the Markers Source section runs in the context of each row.

• Clipboard page - If selected, you must also specify the Clipboard page (required).
  

  • The clipboard page can be either an Activity or a Data transform.

  • After you specify the clipboard page to use, the Property for location field must be filled by using a list record or by pxResults.

  • For clipboard pages, the Markers Source section runs in the context of each row.

• Report definition - If this option is selected, you must also specify the Applies to and Report definition (both required fields).
  

  • After specifying the report definition to use, the Property for location field must be filled by using a list record.

  • For report definitions, the Markers Source section runs in the context of each row.

Customizing map size

In the Cell Properties window, the Presentation tab allows you to set the height of the map either automatically or with a custom setting. The custom setting (as shown selected below) provides a text field to enter a number, along with a menu to select px, em, or %.

Customizing marker pin information

At run time, locations on a map are indicated with either a blue pin or a red pin.

If geolocation is active for your web browser or mobile device, and the check box for Show User Location is selected in the control's Cell Properties window, your current location is indicated with a blue pin:

User locations on a map are indicated with a red pin. You can click or tap a location to view location details:

Pop-up height/width can be customized by using Dynamic Layouts. The width depends on the content length and on the dynamic layout’s max-width setting.

The information that is displayed in a pop-up window is generated based on data from one of the following Markers Source types: Property, Data page, Clipboard page, and Report definition. The pop-up information section runs in the location pin’s context.

For example, the following data page has two records to map:

D_MyFriends (Code-Pega-List)

pxResults

pxResults(1) (Test-Work-MyFriends)

Name: John

Address: Cambridge

pxResults(2) (Test-Work-MyFriends)

Name: George

Address: Boston

If the Marker Information section field is configured to show the Name property, when the pin located on the Boston address is clicked or tapped, "George" is shown in the pop-up window.

Additional information

Google Developer documentation – Obtaining an API Key