Skip to content

Commit fe24125

Browse files
rolyonrolyon
committed
Merge branch 'master' of https://github.com/MicrosoftDocs/azure-docs-pr into rolyon-rbac-roles-refactor
2 parents 5eb5816 + 3e891b4 commit fe24125

File tree

1 file changed

+140
-3
lines changed

1 file changed

+140
-3
lines changed

‎articles/azure-maps/map-add-popup.md

Lines changed: 140 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Add a popup to a point on a map |Microsoft Azure Maps
33
description: In this article, you will learn how to add a popup to a point using the Microsoft Azure Maps Web SDK.
44
author: jingjing-z
55
ms.author: jinzh
6-
ms.date: 07/29/2019
6+
ms.date: 02/27/2020
77
ms.topic: conceptual
88
ms.service: azure-maps
99
services: azure-maps
@@ -80,7 +80,7 @@ Below is the complete running code sample of the above functionality.
8080

8181
## Reusing a popup with multiple points
8282

83-
When you have a large number of points and only want to show one popup at a time, the best approach is to create one popup and reuse. By reusing the popup, the number of DOM elements created by the application is greatly reduced which can provide better performance. The following sample creates 3-point features. If you click on any of them, a popup will be displayed with the content for that point feature.
83+
There are cases in which the best approach is to create one popup and reuse it. For example, you may have a large number of points and want to show only one popup at a time. By reusing the popup, the number of DOM elements created by the application is greatly reduced, which can provide better performance. The following sample creates 3-point features. If you click on any of them, a popup will be displayed with the content for that point feature.
8484

8585
<br/>
8686

@@ -89,7 +89,7 @@ When you have a large number of points and only want to show one popup at a time
8989

9090
## Customizing a popup
9191

92-
By default the popup has a white background, a pointer arrow on the bottom, and a close button in the top-right corner. The following sample changes the background color to black using the `fillColor` option of the popup. The close button is removed by setting the `CloseButton` option to false. The HTML content of the popup uses padded of 10 pixels from the edges of the popup. The text is made white, so it shows up nicely on the black background.
92+
By default, the popup has a white background, a pointer arrow on the bottom, and a close button in the top-right corner. The following sample changes the background color to black using the `fillColor` option of the popup. The close button is removed by setting the `CloseButton` option to false. The HTML content of the popup uses padded of 10 pixels from the edges of the popup. The text is made white, so it shows up nicely on the black background.
9393

9494
<br/>
9595

@@ -98,6 +98,143 @@ By default the popup has a white background, a pointer arrow on the bottom, and
9898
(<a href='https://codepen.io/azuremaps'>@azuremaps</a>) on <a href='https://codepen.io'>CodePen</a>.
9999
</iframe>
100100

101+
## Add popup templates to the map
102+
103+
Popup templates make it easy to create data driven layouts for popups. The sections below demonstrates the use of various popup templates to generate formatted content using properties of features.
104+
105+
### String template
106+
107+
The String template replaces placeholders with values of the feature properties. The properties of the feature don't have to be assigned a value of type String. For example, `value1` holds an integer. These values are then passed to the content property of the `popupTemplate`.
108+
109+
The `numberFormat` option specifies the format of the number to display. If the `numberFormat` isn't specified, then the code will use the popup templates date format. The `numberFormat` option formats numbers using the [Number.toLocaleString](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString) function. To format large numbers, consider using the `numberFormat` option with functions from [NumberFormat.format](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat/format). For instance, the code snippet below uses `maximumFractionDigits` to limit the number of fraction digits to two.
110+
111+
> [!Note]
112+
> There's only one way in which the String template can render images. First, the String template needs to have an image tag in it. The value being passed to the image tag should be a URL to an image. Then, the String template needs to have `isImage` set to true in the `HyperLinkFormatOptions`. The `isImage` option specifies that the hyperlink is for an image, and the hyperlink will be loaded into an image tag. When the hyperlink is clicked, the image will open.
113+
114+
```javascript
115+
new atlas.data.Feature(new atlas.data.Point([-20, -20]), {
116+
title: 'Template 1 - String template',
117+
value1: 1.2345678,
118+
value2: {
119+
subValue: 'Pizza'
120+
},
121+
arrayValue: [3, 4, 5, 6],
122+
popupTemplate: {
123+
content: 'This template uses a string template with placeholders.<br/><br/> - Value 1 = {value1}<br/> - Value 2 = {value2/subValue}<br/> - Array value [2] = {arrayValue/2}',
124+
numberFormat: {
125+
maximumFractionDigits: 2
126+
}
127+
}
128+
}),
129+
```
130+
131+
### PropertyInfo template
132+
133+
The PropertyInfo template displays available properties of the feature. The `label` option specifies the text to display to the user. If `label` isn't specified, then the hyperlink will be displayed. And, if the hyperlink is an image, the value assigned to the "alt" tag will be displayed. The `dateFormat` specifies the format of the date, and if the date format isn't specified, then the date will render as a string. The `hyperlinkFormat` option renders clickable links, similarly, the `email` option can be used to render clickable email addresses.
134+
135+
Before the PropertyInfo template display the properties to the end user, it recursively checks that the properties are indeed defined for that feature. It also ignores displaying style and title properties. For example, it won't display `color`, `size`, `anchor`, `strokeOpacity`, and `visibility`. So, once property path checking is complete in the back-end, the PropertyInfo template shows the content in a table format.
136+
137+
```javascript
138+
new atlas.data.Feature(new atlas.data.Point([20, -20]), {
139+
title: 'Template 2 - PropertyInfo',
140+
createDate: new Date(),
141+
dateNumber: 1569880860542,
142+
url: 'https://aka.ms/AzureMapsSamples',
143+
email: '[email protected]',
144+
popupTemplate: {
145+
content: [{
146+
propertyPath: 'createDate',
147+
label: 'Created Date'
148+
},
149+
{
150+
propertyPath: 'dateNumber',
151+
label: 'Formatted date from number',
152+
dateFormat: {
153+
weekday: 'long',
154+
year: 'numeric',
155+
month: 'long',
156+
day: 'numeric',
157+
timeZone: 'UTC',
158+
timeZoneName: 'short'
159+
}
160+
},
161+
{
162+
propertyPath: 'url',
163+
label: 'Code samples',
164+
hideLabel: true,
165+
hyperlinkFormat: {
166+
lable: 'Go to code samples!',
167+
target: '_blank'
168+
}
169+
},
170+
{
171+
propertyPath: 'email',
172+
label: 'Email us',
173+
hideLabel: true,
174+
hyperlinkFormat: {
175+
target: '_blank',
176+
scheme: 'mailto:'
177+
}
178+
}
179+
]
180+
}
181+
}),
182+
183+
```
184+
185+
### Multiple content templates
186+
187+
A feature may also display content using a combination of the String template and the PropertyInfo template. In this case, the String template renders placeholders values on a white background. And, the PropertyInfo template renders a full width image inside a table. The properties in this sample are similar to the properties we explained in the previous samples.
188+
189+
```javascript
190+
new atlas.data.Feature(new atlas.data.Point([0, 0]), {
191+
title: 'Template 3 - Multiple content template',
192+
value1: 1.2345678,
193+
value2: {
194+
subValue: 'Pizza'
195+
},
196+
arrayValue: [3, 4, 5, 6],
197+
imageLink: 'https://azuremapscodesamples.azurewebsites.net/common/images/Pike_Market.jpg',
198+
popupTemplate: {
199+
content: [
200+
'This template has two pieces of content; a string template with placeholders and a array of property info which renders a full width image.<br/><br/> - Value 1 = {value1}<br/> - Value 2 = {value2/subValue}<br/> - Array value [2] = {arrayValue/2}',
201+
[{
202+
propertyPath: 'imageLink',
203+
label: 'Image',
204+
hideImageLabel: true,
205+
hyperlinkFormat: {
206+
isImage: true
207+
}
208+
}]
209+
],
210+
numberFormat: {
211+
maximumFractionDigits: 2
212+
}
213+
}
214+
}),
215+
]);
216+
```
217+
218+
### Points without a defined template
219+
220+
When the Popup template isn't defined to be a String template, a PropertyInfo template, or a combination of both, then it uses the default settings. When the `title` and `description` are the only assigned properties, the popup template shows a white background, a close button in the top-right corner. And, on small and medium screens, it shows an arrow at the bottom. The default settings show inside a table for all properties other than the `title` and the `description`. Even when falling back to the default settings, the popup template can still be manipulated programmatically. For example, users can turn off hyperlink detection and the default settings would still apply to other properties.
221+
222+
Click the points on the map in the CodePen. There is a point on the map for each of the following popup templates: String template, PropertyInfo template, and Multiple content template. There are also three points to show how templates render using the defaulting settings.
223+
224+
<br/>
225+
226+
<iframe height='500' scrolling='no' title='PopupTemplates' src='//codepen.io/azuremaps/embed/dyovrzL/?height=500&theme-id=0&default-tab=js,result&embed-version=2&editable=true' frameborder='no' allowtransparency='true' allowfullscreen='true' style='width: 100%;'>See the Pen <a href='https://codepen.io/azuremaps/pen/dyovrzL/'>PopupTemplates</a> by Azure Maps (<a href='https://codepen.io/azuremaps'>@azuremaps</a>) on <a href='https://codepen.io'>CodePen</a>.
227+
</iframe>
228+
229+
## Reuse popup template
230+
231+
Similar to reusing popup, you can reuse popup templates. This approach is useful when you only want to show one popup template at a time, for multiple points. By reusing the popup template, the number of DOM elements created by the application is reduced, which then improves your application performance. The following sample uses the same popup template for three points. If you click on any of them, a popup will be displayed with the content for that point feature.
232+
233+
<br/>
234+
235+
<iframe height='500' scrolling='no' title='ReusePopupTemplate' src='//codepen.io/azuremaps/embed/WNvjxGw/?height=500&theme-id=0&default-tab=js,result&embed-version=2&editable=true' frameborder='no' allowtransparency='true' allowfullscreen='true' style='width: 100%;'>See the Pen <a href='https://codepen.io/azuremaps/pen/WNvjxGw/'>ReusePopupTemplate</a> by Azure Maps (<a href='https://codepen.io/azuremaps'>@azuremaps</a>) on <a href='https://codepen.io'>CodePen</a>.
236+
</iframe>
237+
101238
## Popup events
102239

103240
Popups can be opened, closed, and dragged. The popup class provides events to help developers react to these events. The following sample highlights which events fire when the user opens, closes, or drags the popup.

0 commit comments

Comments
 (0)