Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: Popup

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.
At version 3.4, the popup widget supports rendering text in a right-to-left (RTL) orientation to support RTL languages like Hebrew and Arabic. RTL support will automatically apply if the page direction is set to RTL using the 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

NameSummary
new Popup(options, srcNodeRef)Create a new Popup object.

CSS

esri/dijit/Popup | Download source

Properties

NameTypeSummary
anchorStringControls the placement of the popup window with respect to the geographic location.
clusterFillSymbolFillSymbolVisualizes the extent of the points summarized by the cluster graphic when the user selects the "Browse Features" action in the cluster popup.
countNumberThe number of features associated with the info window.
deferredsDeferred[]An array of pending deferreds, null if there are not any pending deferreds.
domNodeObjectThe HTML element (reference to a DOM Node) where the info window is constructed.
featuresGraphic[]The array of features currently associated with the info window.
fillSymbolFillSymbolDefine the symbol used to highlight polygon features.
hideDelayNumberNumber of milliseconds after which the popup window will be hidden when visibleWhenEmpty is false and there are no features to be displayed.
highlightBooleanIndicates whether popup should highlight features.
isShowingBooleanIndicates if the info window is visible.
keepHighlightOnHideBooleanIndicates whether a feature should remain highlighted after the user closes the popup window.
lineSymbolLineSymbolDefine the symbol used to highlight line features.
locationPointThe location the info window is pointing to.
marginLeftNumberSpecify the margin (in pixels) to leave to the left of the popup window when it is maximized.
marginTopNumberSpecify the margin (in pixels) to leave at the top of the popup window when it is maximized.
markerSymbolMarkerSymbolDefine the marker symbol used to highlight point features.
offsetXNumberSpecify the x-offset (in pixels) used when positioning the popup.
offsetYNumberSpecify the y-offset (in pixels) used when positioning the popup.
pagingControlsBooleanIndicates whether popup should display previous and next buttons in the title bar.
pagingInfoBooleanIndicates whether popup should display the title bar text that contains the page number and total number of available features.
popupWindowBooleanIndicates whether the popup window should be displayed.
selectedIndexNumberThe index of the currently selected feature in the features array.
titleInBodyBooleanIndicates whether the feature's title should display within the body of the popup window as opposed to in the titlebar.
visibleWhenEmptyBooleanIndicates whether the popup window remains visible when there are no features to be displayed.
zoomFactorNumberDefine the number of levels to zoom in when the 'Zoom to' link is clicked.

Methods

NameReturn typeSummary
addActions(actions)Object[]Creates links for the specified actions at the bottom of the popup window.
clearFeatures()NoneRemoves all features and destroys any pending deferreds.
destroy()NoneDestroy the popup.
destroyDijits()NoneHelper method.
getCurrentAnchor()StringReturns the current placement of the popup window.
getSelectedFeature()GraphicGet the currently selected feature.
hide()NoneHide the info window.
maximize()NoneMaximize the info window.
place(value, parentNode)NoneHelper method.
removeActions(actionInfos)NoneRemoves the specified actions from the popup window.
reposition()NoneRe-calculates the popup's position with respect to the map location it is pointing to.
resize(width, height)NoneResize the info window to the specified height (in pixels).
restore()NoneRestore the info window to the pre-maximized state.
select(index)NoneSelects the feature at the specified index.
selectNext()NoneGo to the next feature.
selectPrevious()NoneGo to the previous feature.
set(name, value)PopupSet the value of a property.
setContent(content)NoneSet the content for the info window.
setFeatures(features, options?)NoneAssociate an array of features or an array of deferreds that return features with the info window.
setMap(map)NoneThis method is called by the map when the object is set as its info window.
setTitle(title)NoneSets the info window title.
show(location, options?)NoneDisplay the info window at the specified location.
startup()NoneFinalizes the creation of the widget.
startupDijits()NoneHelper method.
unsetMap(map)NoneThis 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

NameEvent ObjectSummary
clear-featuresFired when clearFeatures is called.
hideFired when the info window is hidden.
maximizeFired when the popup has finished maximizing.
restoreFired when the popup has been restored from its maximized state.
selection-changeFired when the selection changes.
set-featuresFired after registering an array of features.
showFired when the info window becomes visible.
Constructor Details

new Popup(options, srcNodeRef)

Create a new Popup object.
Parameters:
<Object> options Required Optional parameters. See options list. This parameter is required but can be null or an empty object.
<Node | String> srcNodeRef Required Reference or id of the HTML element where the widget should be rendered.
options properties:
<String> anchor Optional Controls 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.
Additional valid options include: "top-left", "top-right", "bottom-left", "bottom-right"
<FillSymbol> fillSymbol Optional Define the symbol used to highlight polygon features.
<Boolean> hideDelay 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.
<Boolean> highlight Optional Indicates whether popup should highlight features. Default is true.
<Boolean> keepHighlightOnHide Optional Indicates whether a feature should remain highlighted after the user closes the popup window. Default is false.
<LineSymbol> lineSymbol Optional Define the symbol used to highlight line features.
<Number> marginLeft Optional Specify the margin (in pixels) to leave to the left of the popup window when it is maximized. The default value is 25.
<Number> marginTop Optional Specify the margin (in pixels) to leave at the top of the popup window when it is maximized. The default value is 25.
<MarkerSymbol> markerSymbol Optional Define the marker symbol used to highlight point features.
<Number> offsetX Optional Specify the x-offset (in pixels) used when positioning the popup. Default value is 3.
<Number> offsetY Optional Specify the y-offset (in pixels) used when positioning the popup. Default value is 3.
<Boolean> pagingControls 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.
<Boolean> pagingInfo Optional Indicates whether popup should display the title bar text that contains the page number and total number of available features. Default is true.
<Boolean> popupWindow 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.
<Boolean> titleInBody 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.
<Boolean> visibleWhenEmpty Optional Indicates whether the popup window remains visible when there are no features to be displayed. Default is true.
<Number> zoomFactor 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> anchor

Controls 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.
Additional valid options include: "top-left", "top-right", "bottom-left", "bottom-right".

<FillSymbol> clusterFillSymbol

Visualizes 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> count

The number of features associated with the info window.

<Deferred[]> deferreds

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> domNode

The HTML element (reference to a DOM Node) where the info window is constructed.

<Graphic[]> features

The array of features currently associated with the info window. Returns null if no features are associated with the info window.

<FillSymbol> fillSymbol

Define the symbol used to highlight polygon features.

<Number> hideDelay

Number 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> highlight

Indicates whether popup should highlight features. (Added at v3.4)
Known values: true | false
Default value: true

<Boolean> isShowing

Indicates if the info window is visible. When true, the window is visible.
Known values: true | false

<Boolean> keepHighlightOnHide

Indicates whether a feature should remain highlighted after the user closes the popup window.
Known values: true | false
Default value: false

<LineSymbol> lineSymbol

Define the symbol used to highlight line features.

<Point> location

The location the info window is pointing to. (Added at v3.10)

<Number> marginLeft

Specify the margin (in pixels) to leave to the left of the popup window when it is maximized.
Default value: 25

<Number> marginTop

Specify the margin (in pixels) to leave at the top of the popup window when it is maximized.
Default value: 25

<MarkerSymbol> markerSymbol

Define the marker symbol used to highlight point features.

<Number> offsetX

Specify the x-offset (in pixels) used when positioning the popup.
Default value: 3

<Number> offsetY

Specify the y-offset (in pixels) used when positioning the popup.
Default value: 3

<Boolean> pagingControls

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.
Known values: true | false
Default value: true

<Boolean> pagingInfo

Indicates whether popup should display the title bar text that contains the page number and total number of available features.
Known values: true | false
Default value: true

<Boolean> popupWindow

Indicates 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 | false
Default value: true

<Number> selectedIndex

The index of the currently selected feature in the features array. Value is -1 if there are no selected features.

<Boolean> titleInBody

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.
Known values: true | false
Default value: true

<Boolean> visibleWhenEmpty

Indicates whether the popup window remains visible when there are no features to be displayed. (Added at v3.8)
Known values: true | false
Default value: true

<Number> zoomFactor

Define the number of levels to zoom in when the 'Zoom to' link is clicked.
Default value: 4
Method Details

addActions(actions)

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:
<Object[]> actions 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>
<Function> callback Required Function that will be called when the user clicks the link with the given title.
<String> className Optional CSS class name to be assigned to the link. This can be an Esri Icon Font.
<String> title 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);
  }
});

clearFeatures()

Removes all features and destroys any pending deferreds.
Sample:

popup.clearFeatures();

destroy()

Destroy the popup. Call this method when the popup is no longer needed by the application.

destroyDijits()

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.

getCurrentAnchor()

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: String

getSelectedFeature()

Get the currently selected feature.
Return type: Graphic
Sample:
var graphic = popup.getSelectedFeature();

hide()

Hide the info window.

maximize()

Maximize the info window.
Sample:
popup.maximize();
See also: on("maximize")

place(value, parentNode)

Helper method. Place the HTML value as a child of the specified parent node.
Parameters:
<String | HTMLElement> value Required A string with HTML tags or a DOM node.
<Node> parentNode Required The parent node where the value will be placed.

removeActions(actionInfos)

Removes the specified actions from the popup window. (Added at v3.22)
Parameters:
<Object[]> actionInfos Required An array of objects that describe actions created with addActions(). See the object specifications table below.
Object Specifications:
<actionInfo>
<Object> action Required Describes the action that was added to the popup via addActions().
<Node> node 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);
  }
});

reposition()

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(width, height)

Resize the info window to the specified height (in pixels).
Parameters:
<Number> width Required The new width of the InfoWindow in pixels.
<Number> height 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()

Restore the info window to the pre-maximized state.
Sample:
popup.restore();
See also: on("restore")

select(index)

Selects the feature at the specified index.
Parameters:
<Number> index Required The index of the feature to select.
Sample:

popup.select(2);

selectNext()

Go to the next feature.

selectPrevious()

Go to the previous feature.

set(name, value)

Set the value of a property.
Return type: Popup
Parameters:
<String> name Required Property to set value.
<*> value Required Value to set. Type depends on the type of the property (see the properties table).

setContent(content)

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.
Parameters:
<String | Function> content Required The content for the info window.

setFeatures(features, options?)

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:
<Graphic[] | Deferred[]> features Required An array of features or deferreds.
<Object> options Optional Additional options for setting features in the popup. See the object specification table below for a list of valid options.
Object Specifications:
<options>
<String> anchor 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]);

setMap(map)

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:
<Map> map Required The map object.

setTitle(title)

Sets the info window title. View the Format Info Window Content help topic for more details.
Parameters:
<String | Function> title Required The text for the title.

show(location, options?)

Display the info window at the specified location.
Parameters:
<Point> location Required An instance of esri.geometry.Point that represents the geographic location to display the popup.
<Object> options Optional See the object specifications table below for the structure of the options object.
Object Specifications:
<options>
<Boolean> closestFirst 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);

startup()

Finalizes the creation of the widget. (Added at v3.12)

startupDijits()

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.

unsetMap(map)

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:
<Map> map Required The map object.
Event Details
[ On Style Events | Connect Style Event ]

clear-features

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()

hide

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');
  });
  ...
});

maximize

Fired when the popup has finished maximizing. Popups can be maximized by:
  • User clicks the maximize icon on the title bar.
  • Programmatically call the maximize method.
(Added at v3.6)
Sample:
require([
  "dojo/_base/connect", ... 
], function(connect, ... ) {
  connect.connect(map.infoWindow,"onMaximize",function(){
    console.log("popup maximized");
  });
  ...
});
See also: maximize()

restore

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 restore method.
(Added at v3.6)
Sample:
require([
  "dojo/_base/connect", ... 
], function(connect, ... ) {
  connect.connect(map.infoWindow,"onRestore",function(){

    console.log("popup restored");

  });
  ...
});
See also: restore()

selection-change

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()

set-features

Fired after registering an array of features. The following actions cause this event to fire:
  • The setFeatures method is called with an array of features
  • The setFeatures method is called with an array of deferreds and all the deferreds have completed. If clearFeatures is called before the pending deferreds have completed this event will not fire.
(Added at v3.6)
Sample:
require([
  "dojo/_base/connect", ... 
], function(connect, ... ) {
  connect.connect(popup,"onSetFeatures",function(){

    console.log("features set");

  });
  ...
});
See also: setFeatures()

show

Fired when the info window becomes visible. (Added at v3.6)
Sample:
require([
  "dojo/_base/connect", ... 
], function(connect, ... ) {
  connect.connect(popup,"onShow",function(){
    console.log('info window is showing');
  });
  ...
});