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

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

NameSummary
new BasemapGallery(params, srcNodeRef?)Creates a new BasemapGallery dijit.

CSS

esri/dijit/BasemapGallery | Download source

NameDescription
esriBasemapGalleryBasemap gallery node.
esriBasemapGalleryNodeStyle the gallery items. The gallery items contain a label and thumbnail.
esriBasemapGallerySelectedNodeThe currently selected item node. This snippet modifies the selected color for items in the gallery.

.esriBasemapGallerySelectedNode .esriBasemapGalleryThumbnail{ 

  border-color: #66FFFF !important; 

}

esriBasemapGalleryThumbnailStyle the the node that contains the thumbnail image.

Properties

NameTypeSummary
basemapsBasemap[]List of basemaps displayed in the BasemapGallery.
loadedBooleanThis value is true after the BasemapGallery retrieves the ArcGIS.com basemaps.
portalUrlStringOptional 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

NameReturn typeSummary
add(basemap)BooleanAdd a new basemap to the BasemapGallery's list of basemaps.
destroy()NoneDestroys the basemap gallery.
get(id)BasemapReturn the basemap with the specified id.
getSelected()BasemapGets the currently selected basemap.
remove(id)BasemapRemove a basemap from the BasemapGallery's list of basemaps.
select(id)BasemapSelect a new basemap for the map.
startup()NoneFinalizes 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

NameEvent ObjectSummary
add
{
  basemap: <Basemap>
}
Fires when a basemap is added to the BasemapGallery's list of basemaps.
errorFires when an error occurs while switching basemaps.
loadFires when the BasemapGallery retrieves the ArcGIS.com basemaps.
remove
{
  basemap: <Basemap>
}
Fires when a basemap is removed from the BasemapGallery's list of basemaps.
selection-changeFires after the map is updated with a new basemap.
Constructor Details

new BasemapGallery(params, srcNodeRef?)

Creates a new BasemapGallery dijit.
Parameters:
<Object> params Required Parameters used to configure the widget. See the list below for details.
<Node | String> srcNodeRef 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:
<String[]> basemapIds Optional List of basemap layer ids in the current map. These layers will be removed when switching to a new basemap.
<Basemap[]> basemaps 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);
  ...
});
<Object> basemapsGroup 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'));
  ...
});
<String> bingMapsKey Optional Specify your Bing Maps key if the basemap group you want to display in the gallery contains bing basemaps.
<Map> map Required Reference to the map. The map parameter is required.
<String> portalUrl 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");
<String[]> referenceIds 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.
<Boolean> showArcGISBasemaps 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[]> basemaps

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

This 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 | false
Sample:
if (basemapGallery.loaded){
  basemapGallery.add(basemap);
}

<String> portalUrl

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

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: Boolean
Parameters:
<Basemap> basemap 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);
  ...
});

destroy()

Destroys the basemap gallery. Call destroy() when the widget is no longer needed by the application.

get(id)

Return the basemap with the specified id. Returns null if a basemap with the specified id is not found.
Return type: Basemap
Parameters:
<String> id Required The basemap id.
Sample:

function getBasemap(id){

  var basemap = basemapGallery.get(id);

  console.log(basemap.title);

}

getSelected()

Gets the currently selected basemap. Returns null if the map is displaying a basemap that is not from the BasemapGallery.
Return type: Basemap
Sample:
require([
  "esri/dijit/BasemapGallery", "dojo/_base/connect", ... 
], function(BasemapGallery, connect, ... ) {
  var basemapGallery = new BasemapGallery( ... );
  connect.connect(basemapGallery,"onSelectionChange",function(){
    var basemap = basemapGallery.getSelected(); 
  });
  ...
});

remove(id)

Remove a basemap from the BasemapGallery's list of basemaps. Returns null if a basemap with the specified id is not found.
Return type: Basemap
Parameters:
<String> id Required The basemap id.
Sample:

function removeBasemap(id){

  basemapGallery.remove(id);

}

select(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: Basemap
Parameters:
<String> id Required The basemap id.
Sample:

function selectBasemap(id) {

  basemapGallery.select(id);

}

startup()

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 ]

add

Fires when a basemap is added to the BasemapGallery's list of basemaps. (Added at v3.6)
Event Object Properties:
<Basemap> basemap 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");
  });
  ...
});

error

Fires when an error occurs while switching basemaps. (Added at v3.6)
Sample:
require([
 ... 
], function( ... ) {
  basemapGallery.on("error", function(evt) {console.log(evt.error)});
  ...
});

load

Fires when the BasemapGallery retrieves the ArcGIS.com basemaps. If showArcGISBasemaps is set to false this event is not fired. (Added at v3.6)

remove

Fires when a basemap is removed from the BasemapGallery's list of basemaps. (Added at v3.6)
Event Object Properties:
<Basemap> basemap 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");
  });
  ...
});

selection-change

Fires after the map is updated with a new basemap. (Added at v3.6)
Sample:
require([
 ... 
], function( ... ) {
  basemapGallery.on("selection-change",function(){
    var basemap = basemapGallery.getSelected(); 
  });
  ...
});