dojo.require("esri.dijit.Popup");
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
CSS
esri/dijit/Popup | Download source
Properties
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
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
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. |
Old Events
onClearFeatures() | Fired when clearFeatures is called. |
onHide() | Fired when the info window is hidden. |
onMaximize() | Fired when the popup has finished maximizing. |
onRestore() | Fired when the popup has been restored from its maximized state. |
onSelectionChange() | 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. |
onSetFeatures() | Fired after registering an array of features. |
onShow() | Fired when the info window becomes visible. |
Constructor Details
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:
var popup = new esri.dijit.Popup({
offsetX:10,
offsetY:10,
zoomFactor:2
}, dojo.create("div"));
Property Details
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 below the geographic location.
- "left" : Popup window is placed to the left.
Additional valid options include: "top-left", "top-right", "bottom-left", "bottom-right".
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)
The number of features associated with the info window.
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.
The HTML element (reference to a DOM Node) where the info window is constructed.
The array of features currently associated with the info window. Returns null if no features are associated with the info window.
Define the symbol used to highlight polygon features.
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
Indicates whether popup should highlight features. (Added at v3.4)
Known values: true | false
Default value: true
Indicates if the info window is visible. When true, the window is visible.
Known values: true | false
Indicates whether a feature should remain highlighted after the user closes the popup window.
Known values: true | false
Default value: false
Define the symbol used to highlight line features.
The location the info window is pointing to. (Added at v3.10)
Specify the margin (in pixels) to leave to the left of the popup window when it is maximized.
Default value: 25
Specify the margin (in pixels) to leave at the top of the popup window when it is maximized.
Default value: 25
Define the marker symbol used to highlight point features.
Specify the x-offset (in pixels) used when positioning the popup.
Default value: 3
Specify the y-offset (in pixels) used when positioning the popup.
Default value: 3
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
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
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
The index of the currently selected feature in the features array. Value is -1 if there are no selected features.
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
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
Define the number of levels to zoom in when the 'Zoom to' link is clicked.
Default value: 4
Method 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) 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. |
Removes all features and destroys any pending deferreds.
Sample:
popup.clearFeatures();
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)
Get the currently selected feature.
Sample:
var graphic = popup.getSelectedFeature();
Maximize the info window.
Sample:
popup.maximize();
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. |
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. |
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:
<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 the info window to the pre-maximized state.
Selects the feature at the specified index.
Parameters:
<Number > index |
Required |
The index of the feature to select. |
Go to the previous feature.
Set the value of a property.
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). |
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:
<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]);
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. |
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);
Finalizes the creation of the widget. (Added at v3.12)
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:
<Map > map |
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');
});
...
});
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
maximize
method.
(Added at v3.6) Sample:
require([
"dojo/_base/connect", ...
], function(connect, ... ) {
connect.connect(map.infoWindow,"onMaximize",function(){
console.log("popup maximized");
});
...
});
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");
});
...
});
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();
});
...
});
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");
});
...
});
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');
});
...
});
Fired when clearFeatures
is called.
Sample:
dojo.connect(map.infoWindow,"onClearFeatures",function(){
console.log('features cleared');
});
Fired when the info window is hidden.
Sample:
dojo.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
maximize
method.
(Added at v2.5) Sample:
dojo.connect(map.infoWindow,"onMaximize",function(){
console.log("popup maximized");
});
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 v2.5) Sample:
dojo.connect(map.infoWindow,"onRestore",function(){
console.log("popup restored");
});
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.
Sample:
dojo.connect(popup,"onSelectionChange",function(){
var graphic = popup.getSelectedFeature();
});
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.
Sample:
dojo.connect(popup,"onSetFeatures",function(){
console.log("features set");
});
Fired when the info window becomes visible.
Sample:
dojo.connect(popup,"onShow",function(){
console.log('info window is showing');
});