Hide Table of Contents
esri
esri/arcgis
esri/dijit
esri/dijit/analysis
esri/dijit/geoenrichment
esri/dijit/geoenrichment/ReportPlayer
esri/geometry
esri/layers
esri/renderers
esri/symbols
esri/tasks
esri/tasks/datareviewer
esri/tasks/geoenrichment
esri/tasks/locationproviders
Class: Popup
[ AMD Module Require | Legacy Module Require ]
require(["esri/dijit/Popup"], function(Popup) { /* code goes here */ });
Description
(Added at v2.3)
The Popup class is an implementation of InfoWindow that inherits from InfoWindowBase to provide additional capabilities. The popup is associated with feature(s) and title and content are manually read from the feature. Popups can be used to display the results of asynchronous operations like the execution of a query task or a feature layer query. Popups provide the following additional capabilities:- Provides a user interface to navigate through multiple selections.
- Zoom and highlight selected feature.
- Maximize the info window.
dir attribute. The default value is left-to-right (LTR).
<html dir="rtl">View the Working with Popups help topic for details on creating and using poups.
Samples
Search for samples that use this class.Class hierarchy
esri/dijit/InfoWindowBase |_esri/dijit/Popup
Constructors
| Name | Summary |
|---|---|
| new Popup(options, srcNodeRef) | Create a new Popup object. |
CSS
esri/dijit/Popup | Download source
Properties
| Name | Type | Summary |
|---|---|---|
| anchor | String | Controls the placement of the popup window with respect to the geographic location. |
| clusterFillSymbol | FillSymbol | Visualizes the extent of the points summarized by the cluster graphic when the user selects the "Browse Features" action in the cluster popup. |
| count | Number | The number of features associated with the info window. |
| deferreds | Deferred[] | An array of pending deferreds, null if there are not any pending deferreds. |
| domNode | Object | The HTML element (reference to a DOM Node) where the info window is constructed. |
| features | Graphic[] | The array of features currently associated with the info window. |
| fillSymbol | FillSymbol | Define the symbol used to highlight polygon features. |
| hideDelay | Number | Number of milliseconds after which the popup window will be hidden when visibleWhenEmpty is false and there are no features to be displayed. |
| highlight | Boolean | Indicates whether popup should highlight features. |
| isShowing | Boolean | Indicates if the info window is visible. |
| keepHighlightOnHide | Boolean | Indicates whether a feature should remain highlighted after the user closes the popup window. |
| lineSymbol | LineSymbol | Define the symbol used to highlight line features. |
| location | Point | The location the info window is pointing to. |
| marginLeft | Number | Specify the margin (in pixels) to leave to the left of the popup window when it is maximized. |
| marginTop | Number | Specify the margin (in pixels) to leave at the top of the popup window when it is maximized. |
| markerSymbol | SimpleMarkerSymbol | Define the marker symbol used to highlight point features. |
| offsetX | Number | Specify the x-offset (in pixels) used when positioning the popup. |
| offsetY | Number | Specify the y-offset (in pixels) used when positioning the popup. |
| pagingControls | Boolean | Indicates whether popup should display previous and next buttons in the title bar. |
| pagingInfo | Boolean | Indicates whether popup should display the title bar text that contains the page number and total number of available features. |
| popupWindow | Boolean | Indicates whether the popup window should be displayed. |
| selectedIndex | Number | The index of the currently selected feature in the features array. |
| titleInBody | Boolean | Indicates whether the feature's title should display within the body of the popup window as opposed to in the titlebar. |
| visibleWhenEmpty | Boolean | Indicates whether the popup window remains visible when there are no features to be displayed. |
| zoomFactor | Number | Define the number of levels to zoom in when the 'Zoom to' link is clicked. |
Methods
| Name | Return type | Summary |
|---|---|---|
| addActions(actions) | Object[] | Creates links for the specified actions at the bottom of the popup window. |
| clearFeatures() | None | Removes all features and destroys any pending deferreds. |
| destroy() | None | Destroy the popup. |
| destroyDijits() | None | Helper method. |
| getCurrentAnchor() | String | Returns the current placement of the popup window. |
| getSelectedFeature() | Graphic | Get the currently selected feature. |
| hide() | None | Hide the info window. |
| maximize() | None | Maximize the info window. |
| place(value, parentNode) | None | Helper method. |
| removeActions(actionInfos) | None | Removes the specified actions from the popup window. |
| reposition() | None | Re-calculates the popup's position with respect to the map location it is pointing to. |
| resize(width, height) | None | Resize the info window to the specified height (in pixels). |
| restore() | None | Restore the info window to the pre-maximized state. |
| select(index) | None | Selects the feature at the specified index. |
| selectNext() | None | Go to the next feature. |
| selectPrevious() | None | Go to the previous feature. |
| set(name, value) | Popup | Set the value of a property. |
| setContent(content) | None | Set the content for the info window. |
| setFeatures(features, options?) | None | Associate an array of features or an array of deferreds that return features with the info window. |
| setMap(map) | None | This method is called by the map when the object is set as its info window. |
| setTitle(title) | None | Sets the info window title. |
| show(location, options?) | None | Display the info window at the specified location. |
| startup() | None | Finalizes the creation of the widget. |
| startupDijits() | None | Helper method. |
| unsetMap(map) | None | This method is called by the map when the object is no longer the map's info window. |
Events
[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.
Events
| Name | Event Object | Summary |
|---|---|---|
| clear-features | Fired when clearFeatures is called. | |
| hide | Fired when the info window is hidden. | |
| maximize | Fired when the popup has finished maximizing. | |
| restore | Fired when the popup has been restored from its maximized state. | |
| selection-change | Fired when the selection changes. | |
| set-features | Fired after registering an array of features. | |
| show | Fired when the info window becomes visible. |
Constructor Details
Create a new Popup object.
Parameters:
< |
Required | Optional parameters. See options list. This parameter is required but can be null or an empty object. |
< |
Required | Reference or id of the HTML element where the widget should be rendered. |
options properties: < |
Optional | Controls the placement of the popup window with respect to the geographic location. Supports the following options:
|
< |
Optional | Define the symbol used to highlight polygon features. |
< |
Optional | Number of milliseconds after which the popup window will be hidden when visibleWhenEmpty is false and there are no features to be displayed. Default is 1000. |
< |
Optional | Indicates whether popup should highlight features. Default is true. |
< |
Optional | Indicates whether a feature should remain highlighted after the user closes the popup window. Default is false. |
< |
Optional | Define the symbol used to highlight line features. |
< |
Optional | Specify the margin (in pixels) to leave to the left of the popup window when it is maximized. The default value is 25. |
< |
Optional | Specify the margin (in pixels) to leave at the top of the popup window when it is maximized. The default value is 25. |
< |
Optional | Define the marker symbol used to highlight point features. |
< |
Optional | Specify the x-offset (in pixels) used when positioning the popup. Default value is 3. |
< |
Optional | Specify the y-offset (in pixels) used when positioning the popup. Default value is 3. |
< |
Optional | Indicates whether popup should display previous and next buttons in the title bar. These buttons are normally displayed when the popup displays two or more features. Default is true. |
< |
Optional | Indicates whether popup should display the title bar text that contains the page number and total number of available features. Default is true. |
< |
Optional | Indicates whether the popup window should be displayed. Default is true. When set to false, the popup will still continue to fire events such as: onSetFeatures, onClearFeatures and onSelectionChange where applicable. |
< |
Optional | Indicates whether the feature's title should display within the body of the popup window as opposed to in the titlebar. This option is only valid for features that have a PopupTemplate defined. The default value is true. |
< |
Optional | Indicates whether the popup window remains visible when there are no features to be displayed. Default is true. |
< |
Optional | Define the number of levels to zoom in when the 'Zoom to' link is clicked. Default value is 4. |
Sample:
require([
"esri/dijit/Popup", "dojo/dom-construct", ...
], function(Popup, domConstruct... ) {
var popup = new Popup({
offsetX: 10,
offsetY: 10,
zoomFactor: 2
}, domConstruct.create("div"));
...
});
Property Details
<String
StringControls the placement of the popup window with respect to the geographic location. Supports the following options:
- "auto" : Placement is automatically computed depending on the available screen space. This is the default behavior
- "top" : Popup window is placed on top of the geographic location.
- "right" : Popup window is placed to the right.
- "bottom" : Popup window is placed on below the geographic location.
- "left" : Popup window is placed to the left.
<FillSymbol
FillSymbolVisualizes the extent of the points summarized by the cluster graphic when the user selects the "Browse Features" action in the cluster popup. (Added at v3.22)
<Number
NumberThe number of features associated with the info window.
<Deferred[]
Deferred[]An array of pending deferreds, null if there are not any pending deferreds. When the pending deferreds are resolved they are removed from the array and the features they return will be pushed into the features array.
<Object
ObjectThe HTML element (reference to a DOM Node) where the info window is constructed.
<Graphic[]
Graphic[]The array of features currently associated with the info window. Returns null if no features are associated with the info window.
<FillSymbol
FillSymbolDefine the symbol used to highlight polygon features.
<Number
NumberNumber of milliseconds after which the popup window will be hidden when
visibleWhenEmpty is false and there are no features to be displayed. (Added at v3.8)Default value:
1000<Boolean
BooleanIndicates whether popup should highlight features. (Added at v3.4)
Known values:
true | falseDefault value:
true<Boolean
BooleanIndicates if the info window is visible. When true, the window is visible.
Known values:
true | false<Boolean
BooleanIndicates whether a feature should remain highlighted after the user closes the popup window.
Known values:
true | falseDefault value:
false<LineSymbol
LineSymbolDefine the symbol used to highlight line features.
<Point
PointThe location the info window is pointing to. (Added at v3.10)
<Number
NumberSpecify the margin (in pixels) to leave to the left of the popup window when it is maximized.
Default value:
25<Number
NumberSpecify the margin (in pixels) to leave at the top of the popup window when it is maximized.
Default value:
25<SimpleMarkerSymbol
SimpleMarkerSymbolDefine the marker symbol used to highlight point features.
<Boolean
BooleanIndicates whether popup should display previous and next buttons in the title bar. These buttons are normally displayed when the popup displays two or more features.
Known values:
true | falseDefault value:
true<Boolean
BooleanIndicates whether popup should display the title bar text that contains the page number and total number of available features.
Known values:
true | falseDefault value:
true<Boolean
BooleanIndicates whether the popup window should be displayed. When set to false, the popup will still continue to fire events such as:
onSetFeatures, onClearFeatures and onSelectionChange where applicable.Known values:
true | falseDefault value:
true<Number
NumberThe index of the currently selected feature in the features array. Value is -1 if there are no selected features.
<Boolean
BooleanIndicates whether the feature's title should display within the body of the popup window as opposed to in the titlebar. This option is only valid for features that have a PopupTemplate defined.
Known values:
true | falseDefault value:
true<Boolean
BooleanIndicates whether the popup window remains visible when there are no features to be displayed. (Added at v3.8)
Known values:
true | falseDefault value:
true<Number
NumberDefine the number of levels to zoom in when the 'Zoom to' link is clicked.
Default value:
4Method Details
Creates links for the specified actions at the bottom of the popup window. Returns an array of actionInfo objects. These objects may be passed to the removeActions() method to remove the set actions from the popup. (Added at v3.22)
Return type:
Object[]Parameters:
< |
Required | An array of action objects that define the behavior for actions included in the popup. See the object specification table below for details about each property of an action. |
Object Specifications:
<
action>< |
Required | Function that will be called when the user clicks the link with the given title. |
< |
Optional | CSS class name to be assigned to the link. This can be an Esri Icon Font. |
< |
Required | Text representing the name of the action. This is displayed as a clickable link at the bottom of the popup. |
Sample:
var customActions;
map.infoWindow.on("selection-change", function() {
var selectedFeature = map.infoWindow.getSelectedFeature();
if (selectedFeature && selectedFeature.attributes.TYPE === "crime") {
var crimeAction = {
title: "Crime Report",
className: "crime-report-action",
callback: function() {
console.log("Get Full Crime Report");
}
};
customActions = map.infoWindow.addActions([ crimeAction ]);
}
else {
map.infoWindow.removeActions(customActions);
}
});
Removes all features and destroys any pending deferreds.
Sample:
popup.clearFeatures();
See also: on("clear-features")
Destroy the popup. Call this method when the popup is no longer needed by the application.
Helper method. Call destroy on dijits that are embedded into the specified node. Sub-classes may need to call this method before executing
setContent logic to finalize the destruction of any embedded dijits in the previous content.Returns the current placement of the popup window. (i.e. the return value can be one of these strings: "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left" and "bottom-right"). (Added at v3.22)
Return type:
StringGet the currently selected feature.
Return type:
GraphicSample:
var graphic = popup.getSelectedFeature();
Helper method. Place the HTML value as a child of the specified parent node.
Parameters:
< |
Required | A string with HTML tags or a DOM node. |
< |
Required | The parent node where the value will be placed. |
Removes the specified actions from the popup window. (Added at v3.22)
Parameters:
< |
Required | An array of objects that describe actions created with addActions(). See the object specifications table below. |
Object Specifications:
<
actionInfo>< |
Required | Describes the action that was added to the popup via addActions(). |
< |
Required | DOM node created and attached to the popup window. |
Sample:
var customActions;
map.infoWindow.on("selection-change", function() {
var selectedFeature = map.infoWindow.getSelectedFeature();
if (selectedFeature && selectedFeature.attributes.TYPE === "crime") {
var crimeAction = {
title: "Crime Report",
className: "crime-report-action",
callback: function() {
console.log("Get Full Crime Report");
}
};
customActions = map.infoWindow.addActions([ crimeAction ]);
}
else {
map.infoWindow.removeActions(customActions);
}
});
Re-calculates the popup's position with respect to the map location it is pointing to. Typically popup automatically takes care of this whenever the content inside it is modified using
setTitle, setContent or setFeatures methods. If you modify the popup's DOM in other ways, then you need to call this method to make sure it points to the correct map location. (Added at v2.5)Sample:
popup.reposition();
Resize the info window to the specified height (in pixels).
Parameters:
< |
Required | The new width of the InfoWindow in pixels. |
< |
Required | The new height of the InfoWindow in pixels. This value is set to be the maximum allowable height, if the content doesn't fit within the specified height a vertical scroll bar is displayed. |
Sample:
popup.resize(400,300);
Restore the info window to the pre-maximized state.
Sample:
popup.restore();
See also: on("restore")
Selects the feature at the specified index.
Parameters:
< |
Required | The index of the feature to select. |
Sample:
popup.select(2);
See also: on("selection-change")
Set the value of a property.
Return type:
PopupParameters:
< |
Required | Property to set value. |
<*> value |
Required | Value to set. Type depends on the type of the property (see the properties table). |
Set the content for the info window. View the Format Info Window Content help topic for more details.Note: the Popup class doesn't support the deferred object option for setting content.
Associate an array of features or an array of deferreds that return features with the info window. The first feature in the array is automatically selected.
Note:When setFeatures is used the title area displays the number of features and the index of the currently selected feature and ignores the title defined in the info template. If you want to display title text you will need to specify it as part of the info window content.
Parameters:
< |
Required | An array of features or deferreds. |
< |
Optional | Additional options for setting features in the popup. See the object specification table below for a list of valid options. |
Object Specifications:
<
options>< |
Optional | Anchor that temporarily overrides the global anchor defined in the anchor property. Its value can be one of the values supported by anchor. |
Sample:
var deferred = featureLayer.selectFeatures(query); popup.setFeatures([deferred]);
See also: on("set-features")
This method is called by the map when the object is set as its info window. The default implementation provided by InfoWindowBase stores the argument to this object in a property named map and is sufficient for most use cases.
Parameters:
< |
Required | The map object. |
Sets the info window title. View the Format Info Window Content help topic for more details.
Display the info window at the specified location.
Parameters:
< |
Required | An instance of esri.geometry.Point that represents the geographic location to display the popup. |
< |
Optional | See the object specifications table below for the structure of the options object. |
Object Specifications:
<
options>< |
Required | When using the setFeatures method to display multiple features in the popup, enable this option to display the feature closest to the specified location first. |
Sample:
popup.show(evt.mapPoint);
Helper method. Call startup on dijits that are embedded into the specified node. Sub-classes may need to call this method right after displaying the info window, passing in a reference to the content node.
This method is called by the map when the object is no longer the map's info window. The default implementation provided by InfoWindowBase clears the argument property "map" from the object and is sufficient for most use cases.
Parameters:
< |
Required | The map object. |
Event Details
[ On Style Events | Connect Style Event ]
Fired when
clearFeatures is called. (Added at v3.6)Sample:
require([
"dojo/_base/connect", ...
], function(connect, ... ) {
connect.connect(map.infoWindow,"onClearFeatures",function(){
console.log('features cleared');
});
...
});
See also: clearFeatures()
Fired when the info window is hidden. (Added at v3.6)
Sample:
require([
"dojo/_base/connect", ...
], function(connect, ... ) {
connect.connect(popup,"onHide",function(){
console.log('info window is hidden');
});
...
});
Fired when the popup has finished maximizing. Popups can be maximized by:
- User clicks the maximize icon on the title bar.
- Programmatically call the
maximizemethod.
Sample:
require([
"dojo/_base/connect", ...
], function(connect, ... ) {
connect.connect(map.infoWindow,"onMaximize",function(){
console.log("popup maximized");
});
...
});
See also: maximize()
Fired when the popup has been restored from its maximized state. Popups are restored when:
- User clicks the restore icon on the title bar.
- Programmatically call the
restoremethod.
Sample:
require([
"dojo/_base/connect", ...
], function(connect, ... ) {
connect.connect(map.infoWindow,"onRestore",function(){
console.log("popup restored");
});
...
});
See also: restore()
Fired when the selection changes. This can occur when the
select method is called or when users navigate through the selection using the next and previous buttons. (Added at v3.6)Sample:
require([
"dojo/_base/connect", ...
], function(connect, ... ) {
connect.connect(popup,"onSelectionChange",function(){
var graphic = popup.getSelectedFeature();
});
...
});
See also: select()
Fired after registering an array of features. The following actions cause this event to fire:
- The
setFeaturesmethod is called with an array of features - The
setFeaturesmethod is called with an array of deferreds and all the deferreds have completed. IfclearFeaturesis called before the pending deferreds have completed this event will not fire.
Sample:
require([
"dojo/_base/connect", ...
], function(connect, ... ) {
connect.connect(popup,"onSetFeatures",function(){
console.log("features set");
});
...
});
See also: setFeatures()