Harness and Section forms - Adding an Address Map control

You can add the pxAddressMap control to a cell, enabling users to view and interact with location points in Google Maps from within a desktop or mobile app. This control is responsive when added to a dynamic layout, and you can configure events on the control, such as displaying location details. It can also be added to a smart layout or to a section. For more information, see Using an Address Map control.

Map points are generated using data sourced from a Property, Data page, Clipboard page, or Report definition. Information for a specific location is shown in a popup when the corresponding map point is clicked or tapped. If you experience issues using the Geolocation functionality, see Troubleshooting Show User Location feature in browsers.

The Address Map control uses the Google Maps service when displaying locations and corresponding information. Refer to the Google Terms of Service for details regarding any region-based or usage restrictions.

Obtaining a Google API key

The Address Map control displays at run time only if you have first obtained a Google API key.

  1. Access the Google Developer Console and log in to your account.
  2. Select your project. (If no project currently exists, create a new project).
  3. Locate the APIs section and turn on Google Maps JavaScript API v3 and Google Maps Geocoding API. This must be done to make use of the Address Map feature.
  4. Locate the Credentials section and create a new browser key to use for Public API access.
    • Make sure you create a new browser key here and not a server key.
    • See the Google Developer documentation for information about configuring allowed referers.
  5. Once generated, take note of the API key. Access the Pega Platform and enter this key in the Dynamic System Setting at: uiengine/map/googleapikey.
Note: The above steps partially apply to a third-party resource (the Google Developer Console) and are accurate as of the publication of this article. Refer to the official Google Developer documentation for Obtaining an API Key for additional assistance with this process.

Adding the Address Map control

  1. In Designer Studio, select the Advanced menu and drag the Address Map control to the harness, section, or flow action.
  2. Click the View properties icon for the control to display the Cell Properties panel.
  3. Configure the control in the fields provided on the General tab and click OK to save your changes.

Customizing map functionality

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

Field Description
Show User Location When checked, shows the user's current location on the map with a blue marker pin. This pin is prioritized and displays 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.
  • This can either be hardcoded into the field by enclosing coordinates within double quotes, such as:

    “42.366200, -71.076936”

    or use a property reference, such as:

    ​.OfficeLocation, SomePage.HomeAddress, EmployeeList.pxResults(1).Location

  • This location does not always display as the starting point, since the map initially zooms in/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 displays based on user input.
Type A menu in the Markers Source section where you select the data source used to display points on the map. See the section below for description of fields for each available option.

Using the Markers Source section

For list-based sources, 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 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/group, the applies to class must be the applies to class of pxResults

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

Option Description
Property  
  If selected, you can also specify the Source to be Value or List defined on property. Specifying the Address property is required and you can optionally also specify the Marker info section.

The following fields are available:

Source
Indicates one of the following for the source:
Value The source for the address map control is to be a value.
List defined on property The local/prompt list as defined on property ruleform, like other list-based controls. The fields below related to marker repositioning, lat long property and error reporting do not apply when this setting is selected.
Address property The value of the property at runtime. This field and the address map control are coupled. Change in one triggers an automatic update in the other.

It can either be hardcoded into the field by enclosing coordinates within double quotes, such as:

“42.366200, -71.076936”

or use a property reference, such as:

.OfficeLocation, SomePage.HomeAddress, EmployeeList.pxResults(1).Location

Allow marker repositioning to change the address value Causes the address to change 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, both properties- the Address property and Lat-long property are filled with the latitude/longitude coordinates.
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 displaying an error message when the address at the new location cannot be found. The text of the error message is configured via 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 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 either be an Activity or a Data transform.
  • After specifying the clipboard page to use, the Property for location field must be filled using a list record or by pxResults.
  • For clipboard pages, the "Markers Source" section runs in the context of each row.
Report definition  
  If 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 using a list record.
  • For report definitions, the "Markers Source" section runs in the context of each row.

When the Address Map control is sourced from a report definition it can use a value to drive which marker icon to display - so that different locations on the control have different icons. See also Customizing map icons section below.

Identifiers  
Tour ID Optional: Provide an ID for use in a guided tour. Use a combination of numbers, letters, and underscores. Pega Platform uses the Tour ID when it finds an anchor button during a tour stop anchor point.
Test ID

Optional: If authorized, you can provide a unique Test ID for use in your test suite in order to support better automated testing against any Pega application.

When creating a control that supports Test ID, the Test ID field is initially blank. Use a combination of numbers, letters, and underscores, or click the Generate ID button to create a time stamp as a unique ID. The attribute data-test-id is then generated for the selected element. When you save an existing section, any supported controls that do not have a Test ID will have one automatically generated. You can override these with a custom ID at a later time.

Once generated, you can view your Test ID in HTML or display it in the Live UI panel. You also have the option to have all controls that support Test IDs in a ruleset updated in bulk.

A standard, out-of-the-box developer role, PegaRULES:SysAdm4, includes the privilege for Test ID. To disable Test ID for this role, modify the pxTestID privilege.

For instance, if a Text Input control is bound with the Address property and the map also drives its marker from the same property, then:

  • when the Text Input value is changed by the user and
  • the Text Input control is configured to 'Post value' on change

The Address Map control automatically, via changing tracking, updates the marker pin to display this new location without needing to perform a section refresh. In addition, if the Allow marker repositioning to change address value option is selected, any change in the marker pin by dragging it, triggers an update in the Text Input field automatically without any section refresh.

Customizing map size

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

Note: The % height setting is not supported in dynamic layouts since they do not have any height configured. % height can only be used with a free form layout.

Customizing map icons

A user can customize the Address Map control icons to make them consistent with the look and feel of the application and the map. Changing them affects marker icons globally. At design-time a user can also change default marker icons on individual address map instances. For example, it may be useful to show an airport location with an airplane icon and a coffee shop location with a cup icon on the same map displayed in the application.

Note: The user can only customize the images representing the icons, the anchor position cannot be changed.
Name Description Required size
pyDefaultMarkerIcon Icon for address location marker pins. By default it is red. 32 x 32 pixels
pyGPSIcon Icon for button that resets the map to user's current location. 32 x 32 pixels
pyUserLocationIcon Icon used to show current physical location. By default it is blue. 24 x 24 pixels