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.
The Address Map control uses the Google Maps service when displaying locations and corresponding information. Refer to the Google Terms of Service
for details about any region-based or usage restrictions.
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:
- Access the Google Developer Console at https://console.developers.google.com and log in to your account.
- Select your project. (If no project currently exists, create a project.)
- In the Credentials section, create a browser key to use for Public API access.
- 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.
The preceding steps partially apply to a third-party resource (the Google Developer Console) and are accurate as of the publication of this article. Refer to Google Developer documentation for Obtaining an API Key
for additional assistance with this process.
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:
- Access the Pega 7 Platform.
- In the Pega 7 Search field, enter
- Enter the value for the previously generated Google API key in the Value field.
- Restart the server.
Configuring the Address Map control
- In Designer Studio, add the pxAddressMap control to a section or layout by clicking
The control can be added in a cell in a dynamic or smart layout, to a section, or directly into a harness.
The pxAddressMap control does not support direct embedding in grids in PRPC 7.1.6.
Adding this control to a section or layout displays a static image of a map to indicate the location of the control.
- Click the Gear icon to open the Cell Properties window for the Address Map control.
- When you finish configuring the control, click
, and then click 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.
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:
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 (required).
- If selected, you must also specify the
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 %.
The % height setting is not supported in dynamic layouts because they do not have any height configured. The % height setting can be used only with a free-form layout.
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:
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.
Google Developer documentation – Obtaining an API Key