Basemaps: arcgis.com web map basemap VERSUS ArcGIS Javascript API basemap

Discussion created by davidfkimball on Apr 17, 2014
I am struggling with working with basemaps. My (in early development) webpage, which I am writing "from scratch" (not  based on a template/boilerplate) using Dojo and the ArcGIS Javascript API 3.8, shows an ArcGIS.com web map that I add  via arcgisUtils.createMap(). The arcgis.com web map contains the Topographic basemap and two layers from ArcGIS Server.  Here's the current state of my webpage:

My webpage includes a BasemapGallery widget, which seems to work fine (except that it doesn't highlight the default  basemap with a pink border when it starts up; once the user selects a different basemap in the BasemapGallery, it  highlights it). From what I can tell, the BasemapGallery widget isn't aware of what basemap the arcgis.com web map uses  by default.

I am adding homemade code* to create a "permalink" Share tool; it creates a custom URL that the user can use to share  the current state (zoom extent and appearance) of the map by adding URL query string parameters to the base URL, i.e.

I'm trying to use the well-known basemap names** (streets, satellite, oceans, topo, hybrid, gray, national-geographic,  osm) in the parameter. I can't figure out how to get and set the basemap correctly.

At this time my webpage code is all in one big HTML file; the functions that deal with the URL query string parameters  are readUrlQueryStringParameters(), writeUrlQueryStringParameters(), and createUrlQueryStringParameters().

I set up popup alerts that show the values for map.setBasemap() and map.getBasemap(). If you haven't explicitly set a  basemap via the URL, map.getBasemap() returns nothing.

map.setBasemap("osm") seems to put the new basemap UNDER the default web map basemap? If you pan quickly sometimes you  can see the first basemap draw and then be covered by the second basemap!

What is going on? Is an arcgis.com web map basemap a completely different (and parallel) thing from an ArcGIS Javascript API basemap?  Is the BasemapGallery widget (and the entire basemap-handling part of the API) not ready for prime time?

I guess on a bigger level my question is whether working with an arcgis.com web map is a bad idea? Does the API really  work well with them?

I read (and didn't fully understand) the following thread that seems to be about similar problems:


It seems an ESRI employee is suggesting a hack where you make your web map basemap 100% transparent? Yikes.



(*side question 1: is there a canned permalink/share widget that does this or am I right to code this by hand?)

(**side question 2: is there a well-known-name for the "Terrain with Labels" basemap?)