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 pop-up 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. For details, see Obtaining the Google API key and Configuring a dynamic system setting for the Map control.
Adding the Address Map control
- In Dev Studio, pick a control from either the Basic or Advanced menu and drag it to the harness, section, or flow action.
- Click the View properties icon for the control to display the Cell Properties panel.
- Click the pxAddressMap from the autocomplete input field. , and select the
- 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.
|
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:
| |||||||||||||||||
Data page | |||||||||||||||||
If selected, you must also specify the
Data page
(required).
| |||||||||||||||||
Clipboard page | |||||||||||||||||
If selected, you must also specify the Clipboard page (required).
| |||||||||||||||||
Report definition | |||||||||||||||||
If selected, you must also specify the
Applies to
and
Report definition
(both required fields).
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 to better support automated testing of your application. When creating a control that supports you can use a combination of numbers, letters, and underscores, or click the Generate ID button to create a unique ID. The attribute data-test-id is then generated for the selected element. After the test ID has been generated, you can view your Test ID in HTML or display it in the Enabling run-time branching and editing panel. You also have the option to have all controls that support Test IDs in a ruleset updated in bulk. The Test ID is available to access groups that include the PegaRULES:TestID privilege. To disable Test ID, remove the PegaRULES:TestID from the access group. |
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 %.
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.
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 |
- Using an Address Map control
This article describes the behavior of the Address Map control in the app. See Adding an Address Map control to learn how configure this control. You can also make use of a static Google map as an image in the app, see Displaying location as a static map image. Make sure to obtain a unique Google API key. To learn more, see the Google developer do
- Troubleshooting Show User Location feature in browsers
The ability to show the user location is part of the Address Map control functionality - see Using an Address Map control. It uses the Geolocation feature in a browser. Depending on whether Internet Explorer, Chrome, Firefox or Safari is used, this feature may be restricted or configured incorrectly.
- Keystores
A keystore is a file that contains keys and certificates that you use for encryption, authentication, and serving content over HTTPS. In Pega Platform, you create a keystore data instance that points to a keystore file.
- harnesses
Organize the content and structure of a portal by defining harnesses. By populating harnesses with sections, you can build a modular interface that promotes reuse and maintainability.
- Sections
Use sections in conjunction with harnesses to define the appearance of user forms, rule forms, or composite portals.
- Using an Address Map control
This article describes the behavior of the Address Map control in the app. See Adding an Address Map control to learn how configure this control. You can also make use of a static Google map as an image in the app, see Displaying location as a static map image. Make sure to obtain a unique Google API key. To learn more, see the Google developer do
Previous topic Specifying presentation options for a control Next topic Using an Address Map control