dojo.require("esri.dijit.BasemapGallery");
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
CSS
esri/dijit/BasemapGallery | Download source
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
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
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
add | {
basemap: <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: <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. |
Old Events
onAdd(basemap) | Fires when a basemap is added to the BasemapGallery's list of basemaps. |
onError() | Fires when an error occurs while switching basemaps. |
onLoad() | Fires when the BasemapGallery retrieves the ArcGIS.com basemaps. |
onRemove(basemap) | Fires when a basemap is removed from the BasemapGallery's list of basemaps. |
onSelectionChange() | Fires after the map is updated with a new basemap. |
Constructor Details
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:
var basemapGallery = new esri.dijit.BasemapGallery({
showArcGISBasemaps: true,
map: map
}, "basemapGalleryDiv");
Property Details
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:
var items = dojo.map(basemapGallery.basemaps, function(basemap){
return {thumbnailUrl: basemap.thumbnailUrl, id: basemap.id, title: basemap.title};
});
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);
}
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 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.
Parameters:
<Basemap > basemap |
Required |
The basemap to add to the map. |
Sample:
var layer = new esri.dijit.BasemapLayer({
url:"https://www.example.com/arcgis/rest/services/PublicSafety/PublicSafetyBasemap/MapServer"
});
var basemap = new esri.dijit.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.
Parameters:
<String > id |
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.
Sample:
dojo.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.
Parameters:
<String > id |
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.
Parameters:
<String > id |
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:
<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");
});
...
});
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:
<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");
});
...
});
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();
});
...
});
Fires when a basemap is added to the BasemapGallery's list of basemaps. (Added at v2.2)
Event Object Properties:
<Basemap > basemap |
A basemap to add to the BasemapGallery's list of basemaps. |
Sample:
dojo.connect(basemapGallery, "onAdd", function(basemap) {
console.log(basemap.title+" added to the gallery");
});
Fires when an error occurs while switching basemaps.
Sample:
dojo.connect(basemapGallery, "onError", function(error) {console.log(error)});
Fires when the BasemapGallery retrieves the ArcGIS.com basemaps. If showArcGISBasemaps
is set to false this event is not fired. (Added at v2.2)
Fires when a basemap is removed from the BasemapGallery's list of basemaps. (Added at v2.2)
Event Object Properties:
<Basemap > basemap |
A basemap to remove from the BasemapGallery's list of basemaps. |
Sample:
dojo.connect(basemapGallery,"onRemove",function(basemap){
console.log(basemap.title + " removed from the gallery");
});
Fires after the map is updated with a new basemap. (Added at v2.2)
Sample:
dojo.connect(basemapGallery,"onSelectionChange",function(){
var basemap = basemapGallery.getSelected();
});