Background map picker

Quick start

The example below, running in the Mappia calculator - click it to run it live. Full-size picture

Run it
Click the picture: the map opens right here and runs the example. Nothing is saved, and nothing to install.
Try it
- Click the Topographic thumbnail at the top right: the basemap under the States layer changes.
- Click OpenStreetMap to switch back: only one basemap is visible at a time.
- Move visibility: true from OpenStreetMap to Topographic and run it again: the map starts topographic.
Make it yours
Copy the query, change it - the key parameters are below - and run it again in the playground, or paste it into the Mappia editor to save it as your map.

Key parameters

Parameter	Example	What it does
`group`	`background`	Makes the layer a basemap: it sits under every other layer, leaves the layer list and joins the picker.
`setOptions`	`ExtjsUtils.CONFIGURATION.setOptions({ backgroundSelector: true })`	Shows the floating picker, one thumbnail per basemap, when the query loads.
`source`	`osm`	Where the basemap comes from: `osm` for OpenStreetMap, `arcgisrest` for ArcGIS basemaps.
`name`	`mapnik`	Which map of that source: `mapnik` for OpenStreetMap; `Topographic` in the ArcGIS example.
`title`	`Topographic`	The label under the basemap’s thumbnail.
`visibility`	`true`	The basemap the map starts with. Set it on one basemap only.

Every parameter, with its type and default, is in the reference at the end of this page.

Complete example

The query 7 lines · runs as is

// Background map picker: layers with group "background" are basemaps; backgroundSelector
// shows them as thumbnails the user switches between. One basemap is visible at a time.
ExtjsUtils.CONFIGURATION.setOptions({ backgroundSelector: true }) && [
  { name: "CSR:estados", title: "States", visibility: true, opacity: 0.4 },
  { name: "mapnik", source: "osm", title: "OpenStreetMap", group: "background", visibility: true },
  { name: "Topographic", source: "arcgisrest", title: "Topographic", group: "background", visibility: false },
];

Customize it

How a basemap behaves

A layer with group: "background" is drawn under everything else and is not listed in the layer panel. Only one basemap is visible at a time: choosing a thumbnail hides the others. Your data layers stay on top and keep their own visibility.

The default basemap

When no layer of the query declares group: "background", the platform adds OpenStreetMap by itself. As soon as you declare a basemap of your own, that default is left out - so list OpenStreetMap among yours if you still want it, as the example does.

Turning the picker on

setOptions goes before the layer list, joined with &&, because a query is a single expression (how a query is evaluated). The setting belongs to the query: it is cleared when another query loads.

To show the picker only when there really is a choice, pass an object instead of true:

ExtjsUtils.CONFIGURATION.setOptions({ backgroundSelector: { minCount: 2 } }) && [
  { name: "CSR:estados", title: "States", visibility: true },
  { name: "mapnik", source: "osm", title: "OpenStreetMap", group: "background", visibility: true },
  { name: "Topographic", source: "arcgisrest", title: "Topographic", group: "background" },
];

Labels

Each thumbnail is labelled with the layer’s title, or its name when there is no title. Keep titles short: long ones are cut off under the thumbnail.

For tiles from any z/x/y tile service, see the XYZ layer. OpenStreetMap tiles can also be saved for use without a connection - see offline areas.

Reference: the parameters used here

Generated from the platform source. Every entry, searchable, is in the API reference; the raw data is api.json. Open an entry for its description, parameters and example; # links to it.

CONFIGURATION · query-wide settings (setOptions)

CONFIGURATION1 entry

ExtjsUtils.CONFIGURATION.setOptions({...}) && [ ... ] sets options of the whole query - keepOnLeave, defaultFromProj, backgroundSelector - until another query is applied. A layer's own settings are its properties.

`setOptions`

function(configurationOptions) : Booleanhelper# Defines query-level application configuration (iframe wheel behaviour, etc.).

Written as ExtjsUtils.CONFIGURATION.setOptions

Defines query-level application configuration (iframe wheel behaviour, etc.). Settings are stored with the query and cleared when another query loads.

configurationOptions Object: Query-level configuration options.
configurationOptions.keepOnLeave Boolean: When false, iframe mouseout blocks wheel until map click.
configurationOptions.defaultFromProj String|null|false: Default fromProj for CSV and JSON lists without crs (a file layer's GeoJSON first guesses EPSG:4326 or EPSG:3857 from its first coordinate; this default is used only when that guess fails). Precedence: this option, then the URL (?defaultFromProj=, options=defaultfromproj:CODE, options=nodefaultfromproj), then CONFIGURATION.DEFAULT_FROM_PROJ (EPSG:900913). null/false/"none" disables.
configurationOptions.backgroundSelector Boolean|Object: When true (or options object), show the floating background basemap picker after the query loads (platform OpenLayers.BackgroundSelector.sync).

Returns True for chaining with && QUERY_DESCRIPTION

ExtjsUtils.CONFIGURATION.setOptions({ keepOnLeave: false }) && QUERY_DESCRIPTION
ExtjsUtils.CONFIGURATION.setOptions({ defaultFromProj: 'EPSG:4674' }) && QUERY_DESCRIPTION
ExtjsUtils.CONFIGURATION.setOptions({ backgroundSelector: true }) && QUERY_DESCRIPTION

Layer properties

LayersProperties2 entries

Keys of a layer object: which map it shows (name, source, styles), how it looks (title, opacity, visibility) and how its row and panel behave.

`source`

String= 'local'property# Defines the source from where the maps declared at the name will be loaded from.

Defines the source from where the maps declared at the name will be loaded from. The Source can be one of the following:

'local': The maps in the name will be loaded from the CSR servers
'calculate': The maps in the name gonna be used to calculate a new map in the expression() function and the result will be displayed as the Layer
'file': The map will be loaded from a file or other custom source. For this, you need to define the file type in the 'type' property and the file where the map should be loaded. For example, for a JSON file, you also need to define the 'json' property.
'xyz': The map will be loaded from an url by the XYZ protocol. The url property is required for this type of source. You can find more informations about the XYZ protocol at: https://developers.planet.com/docs/basemaps/tile-services/xyz/

// Example of how to load a map with the local source
[
  {
     title: 'Map rendered by a local source',
     color: '#666699',
     elements: [
        {
           title: 'Map with local source',
           name: 'CSR:paises',
           source: 'local',
           visibility: true,
        },
     ],
  },
]

// Example of how to load a map with the calculated source
[
  {
     title: 'Map rendered based on calculation',
     color: '#666699',
     elements: [
        {
           title: 'Filtering a part of the map',
           name: 'CSR:geologia',
           source: 'calculate',
           visibility: true,
           updateAutomatically: true,
           expression: function(layersVals, inputs) {
              // layerVals have the value of the legend applied in every pixel of the map
              let mapValue = layersVals[0];

              // Remove every type of relief that is not 'Mantiqueira'
              if(mapValue != 'Mantiqueira') { // If the pixel is not 'Mantiqueira'
                 return undefined; // Don't show the pixel
              }

              // If the pixel is 'Mantiqueira', return the value of the pixel
              return mapValue;
           },
        },
     ],
  },
]

// Example of how to load a map with the file source
[
  {
     title: 'Map rendered based on file source',
     color: '#FFA500',
     elements: [
        {
           title: 'Map with file source',
           name: 'example:map_file_source',
           source: 'file',
           visibility: true,
           // The map is rendered based on the GeoJSON below
           // The GeoJSON needs to be in EPSG:3857
           json: JSON.stringify(
              {
                 "type": "Polygon",
                 "crs": {
                    "type": "name",
                    "properties": {
                       "name": "EPSG:3857"
                    }
                 },
                 "coordinates": [
                    [
                       [
                          -625570.6,
                          6465993.0,
                       ],
                       [
                          -305006.9,
                          6696510.8,
                       ],
                       [
                          -546330.2,
                          6768547.6,
                       ],
                       [
                          -445478.6,
                          7053093.0,
                       ],
                       [
                          -279794.0,
                          7056694.8,
                       ],
                       [
                          -359034.5,
                          7337638.4,
                       ],
                       [
                          -211359.0,
                          7485313.8,
                       ],
                       [
                          62380.8,
                          6955843.3,
                       ],
                       [
                          220861.7,
                          6909019.4,
                       ],
                       [
                          91195.5,
                          6700112.6,
                       ],
                       [
                          213658.1,
                          6682103.4,
                       ],
                       [
                          -625570.6,
                          6465993.0,
                       ],
                    ],
                 ],
              }
           ),
        },
     ],
  },
]

// Example of how to load a map with the XYZ source
// The XYZ source is used to load a map from a URL that contains the &lcub;z&rcub;, &lcub;x&rcub; and &lcub;y&rcub; placeholders
// The &lcub;z&rcub; is the zoom level, &lcub;x&rcub; is the longitude and &lcub;y&rcub; is the latitude
[
  {
     title: 'Map rendered by a XYZ source',
     color: '#666699',
     elements: [
        {
           title: 'Base map loaded by XYZ source',
           // The name of the map that will be added. This name must be unique
           name: 'planet:planet',
           source: 'xyz',
           // The url of the map that will be loaded. The $&lcub;z&rcub;, $&lcub;x&rcub; and $&lcub;y&rcub; placeholders will be replaced by the map library
           url: 'https://tiles.planet.com/basemaps/v1/planet-tiles/planet_medres_visual_2021-09_mosaic/gmap/$&lcub;z&rcub;/$&lcub;x&rcub;/$&lcub;y&rcub;.png?api_key=PLAK78456687760442eaa3d3da16aaac5f2d',
           visibility: true,
        },
     ],
  },
]

`visibility`

Boolean= falseproperty# Define if the Layer should start visible or not.

Define if the Layer should start visible or not. Set it to 'true' for the Layer start visible. Otherwise, set it to 'false' and the Layer will start hidden.

[
 {
   title: 'Example of visibility in a Layer',
   color: '#666699',
   elements: [
     {
       title: 'This layer will start visible',
       name: 'CSR:geologia',
       source: 'local',
       visibility: true,
     },
   ],
 },
]

More layer properties

ConfigLayer1 entry

More keys of the same layer object: scale limits, grouping (group, toggleGroup, openGroup), the row's layout and, on calculated layers, how each map is read (operation).

View all layer configuration API here.

`group`

Stringproperty# Only the value "background" does anything: it makes the layer a basemap, drawn under every other layer and listed in the background picker instead of the layer list.

Only the value "background" does anything: it makes the layer a basemap, drawn under every other layer and listed in the background picker instead of the layer list. Any other value is ignored (it does not group layers: groups are { title, elements: [...] } objects). To let only one of several layers be visible at a time, use toggleGroup.

[{visibility: true, group: "background", name: "CSR:planet_brasil_2024", priority: 5}]