Hide Table of Contents
esri
esri/arcgis
esri/dijit
esri/dijit/analysis
esri/dijit/geoenrichment
esri/dijit/geoenrichment/ReportPlayer
esri/geometry
esri/layers
esri/opsdashboard
esri/renderers
esri/symbols
esri/tasks
esri/tasks/datareviewer
esri/tasks/geoenrichment
esri/tasks/locationproviders
Class: BasemapGallery
[ AMD Module Require | Legacy Module Require ]
require(["esri/dijit/BasemapGallery"], function(BasemapGallery) { /* code goes here */ });
Description
(Added at v2.1)
The BasemapGallery dijit displays a collection of basemaps from ArcGIS.com or a user-defined set of map or image services. When a new basemap is selected from the BasemapGallery the basemap layers are removed from the map and the new layers are added.
All basemaps added to the gallery need to have the same spatial reference. If the default ArcGIS.com basemaps are used then all additional items added to the gallery need to be in Web Mercator (wkids: 102100, 102113 and 3857). If the default basemaps are not used you can add basemaps in any spatial reference as long as all the items added to the gallery share that spatial reference. For best performance, it is recommended that all basemaps added to the gallery are cached (tiled) layers.
Samples
Search for samples that use this class.Constructors
| Name | Summary |
|---|---|
| new BasemapGallery(params, srcNodeRef?) | Creates a new BasemapGallery dijit. |
CSS
esri/dijit/BasemapGallery | Download source
| Name | Description |
|---|---|
| esriBasemapGallery | Basemap gallery node. |
| esriBasemapGalleryNode | Style the gallery items. The gallery items contain a label and thumbnail. |
| esriBasemapGallerySelectedNode | The currently selected item node. This snippet modifies the selected color for items in the gallery.
.esriBasemapGallerySelectedNode .esriBasemapGalleryThumbnail{
border-color: #66FFFF !important;
}
|
| esriBasemapGalleryThumbnail | Style the the node that contains the thumbnail image. |
Properties
| Name | Type | Summary |
|---|---|---|
| basemaps | Basemap[] | List of basemaps displayed in the BasemapGallery. |
| loaded | Boolean | This value is true after the BasemapGallery retrieves the ArcGIS.com basemaps. |
| portalUrl | String | Optional parameter to pass in a portal URL, including the instance name, used to access the group containing the basemap gallery items, for example www.myportal.com/myInstance or http://www.myportal.com/myInstance. |
Methods
| Name | Return type | Summary |
|---|---|---|
| add(basemap) | Boolean | Add a new basemap to the BasemapGallery's list of basemaps. |
| destroy() | None | Destroys the basemap gallery. |
| get(id) | Basemap | Return the basemap with the specified id. |
| getSelected() | Basemap | Gets the currently selected basemap. |
| remove(id) | Basemap | Remove a basemap from the BasemapGallery's list of basemaps. |
| select(id) | Basemap | Select a new basemap for the map. |
| startup() | None | Finalizes the creation of the basemap gallery. |
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 |
|---|---|---|
| add | {
basemap: < | Fires when a basemap is added to the BasemapGallery's list of basemaps. |
| error | Fires when an error occurs while switching basemaps. | |
| load | Fires when the BasemapGallery retrieves the ArcGIS.com basemaps. | |
| remove | {
basemap: < | Fires when a basemap is removed from the BasemapGallery's list of basemaps. |
| selection-change | Fires after the map is updated with a new basemap. |
Constructor Details
Creates a new BasemapGallery dijit.
Parameters:
< |
Required | Parameters used to configure the widget. See the list below for details. |
< |
Optional | Reference or id of the HTML element where the widget should be rendered. If a srcNodeRef is not provided the BasemapGallery has no user interface representation. |
params properties: < |
Optional | List of basemap layer ids in the current map. These layers will be removed when switching to a new basemap. |
< |
Optional | An array of user-defined basemaps to display in the BasemapGallery.
require([
"esri/dijit/Basemap", ...
], function(Basemap, ... ) {
var basemaps = [];
var waterBasemap = new Basemap({
layers: [waterTemplateLayer],
title: "Water Template",
thumbnailUrl: "images/waterThumb.png"
});
basemaps.push(waterBasemap);
...
});
|
< |
Optional | Specify an ArcGIS.com group that contains web maps that will be used as basemaps in the gallery. The basemapsGroup is an object with the following parameters:
{
owner:"",
title:"",
id:""
}
The group can be defined by specifying either the id or the owner and title of the group. If all three parameters are defined only the id is used. If a valid basemapsGroup is defined then the value of showArcGISBasemaps is ignored and the default ArcGIS.com basemaps are not displayed. The following snippet defines a custom basemaps group for the BasemapGallery.
require([
"esri/map", "esri/dijit/BasemapGallery", "dojo/dom-construct", ...
], function(Map, BasemapGallery, domConstruct, ... ) {
var map = new Map( ... );
var basemapGallery = new BasemapGallery({
showArcGISBasemaps: true,
basemapsGroup: { owner: "esri", title: "Community Basemaps" },
map: map
}, domConstruct.create('div'));
...
});
|
< |
Optional | Specify your Bing Maps key if the basemap group you want to display in the gallery contains bing basemaps. |
< |
Required | Reference to the map. The map parameter is required. |
< |
Optional | Specify the portal url, including the instance name, used to access the group that contains the basemap gallery items. Default value is "http://www.arcgis.com".
var basemapGallery = new BasemapGallery({
showArcGISBasemaps: true,
map: map,
portalUrl: "http://myportal.arcgis.com"
}, "basemapGallery");
|
< |
Optional | List of reference layer ids in the current map. Reference layers are displayed on top of the map and usually contain information like place boundaries or labels. All layers specified by the referenceIds will be removed when switching to a new basemap. |
< |
Optional | When true, queries ArcGIS.com to retrieve available basemaps. When false, only user-defined basemaps specified using the basemaps property are displayed. Note: The collection of ArcGIS.com base maps may occasionally change, this means that the order or a particular set of maps being returned may not always be the same. |
Sample:
require([
"esri/map", "esri/dijit/BasemapGallery", ...
], function(Map, BasemapGallery, ... ) {
var map = new Map( ... );
var basemapGallery = new BasemapGallery({
showArcGISBasemaps: true,
map: map
}, "basemapGalleryDiv");
...
});
Property Details
<Basemap[]
Basemap[]List of basemaps displayed in the BasemapGallery. The list contains basemaps added using the basemaps constructor option and if
showArcGISBasemaps is true ArcGIS.com basemaps are also included.Sample:
require([
"esri/dijit/BasemapGallery", "dojo/_base/array", ...
], function(BasemapGallery, array, ... ) {
var basemapGallery = new BasemapGallery( ... );
var items = array.map(basemapGallery.basemaps, function(basemap){
return {thumbnailUrl: basemap.thumbnailUrl, id: basemap.id, title: basemap.title};
});
...
});
<Boolean
BooleanThis value is true after the BasemapGallery retrieves the ArcGIS.com basemaps. If
showArcGISBasemaps is false the loaded property is set to true immediately.Known values:
true | falseSample:
if (basemapGallery.loaded){
basemapGallery.add(basemap);
}
<String
StringOptional parameter to pass in a portal URL, including the instance name, used to access the group containing the basemap gallery items, for example www.myportal.com/myInstance or http://www.myportal.com/myInstance. If the page runs under https the portal URL is automatically converted to https://www.myportal.com/myInstance. See the portal documentation for more info on the portal instance name. (Added at v3.7)
Method Details
Add a new basemap to the BasemapGallery's list of basemaps. Returns true if the basemap is successfully added and false if the item was not added, for example if the id is already in the list of basemaps.
Return type:
BooleanParameters:
< |
Required | The basemap to add to the map. |
Sample:
require([
"esri/dijit/BasemapLayer", "esri/dijit/Basemap", ...
], function(BasemapLayer, Basemap, ... ) {
var layer = new BasemapLayer({
url:"http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/PublicSafety/PublicSafetyBasemap/MapServer"
});
var basemap = new Basemap({
layers:[layer],
title:"Public Safety",
thumbnailUrl:"images/safetyThumb.png"
});
basemapGallery.add(basemap);
...
});
Destroys the basemap gallery. Call destroy() when the widget is no longer needed by the application.
Return the basemap with the specified id. Returns null if a basemap with the specified id is not found.
Return type:
BasemapParameters:
< |
Required | The basemap id. |
Sample:
function getBasemap(id){
var basemap = basemapGallery.get(id);
console.log(basemap.title);
}
Gets the currently selected basemap. Returns null if the map is displaying a basemap that is not from the BasemapGallery.
Return type:
BasemapSample:
require([
"esri/dijit/BasemapGallery", "dojo/_base/connect", ...
], function(BasemapGallery, connect, ... ) {
var basemapGallery = new BasemapGallery( ... );
connect.connect(basemapGallery,"onSelectionChange",function(){
var basemap = basemapGallery.getSelected();
});
...
});
Remove a basemap from the BasemapGallery's list of basemaps. Returns null if a basemap with the specified id is not found.
Return type:
BasemapParameters:
< |
Required | The basemap id. |
Sample:
function removeBasemap(id){
basemapGallery.remove(id);
}
Select a new basemap for the map. The map refreshes to display the new basemap. Returns null if a basemap with the specified id is not found.
Return type:
BasemapParameters:
< |
Required | The basemap id. |
Sample:
function selectBasemap(id) {
basemapGallery.select(id);
}
Finalizes the creation of the basemap gallery. Call startup() after creating the widget when you are ready for user interaction. Startup is only required when a srcNodeRef is provided in the BasemapGallery constructor.
Sample:
basemapGallery.startup();
Event Details
[ On Style Events | Connect Style Event ]
Fires when a basemap is added to the BasemapGallery's list of basemaps. (Added at v3.6)
Event Object Properties:
< |
A basemap to add to the BasemapGallery's list of basemaps. |
Sample:
require([
...
], function( ... ) {
basemapGallery.on("add", function(evt) {
console.log(evt.basemap.title+" added to the gallery");
});
...
});
Fires when an error occurs while switching basemaps. (Added at v3.6)
Sample:
require([
...
], function( ... ) {
basemapGallery.on("error", function(evt) {console.log(evt.error)});
...
});
Fires when the BasemapGallery retrieves the ArcGIS.com basemaps. If
showArcGISBasemaps is set to false this event is not fired. (Added at v3.6)Fires when a basemap is removed from the BasemapGallery's list of basemaps. (Added at v3.6)
Event Object Properties:
< |
A basemap to remove from the BasemapGallery's list of basemaps. |
Sample:
require([
...
], function( ... ) {
basemapGallery.on("remove",function(evt){
console.log(evt.basemap.title + " removed from the gallery");
});
...
});