Custom Map Layers

1. What are Custom Map Layers?

Since V1.3.1 of GPXTrackMap, it is possible to use custom, self-defined map layers within GPXTrackMap.

The plugin comes with four different types of OpenStreetmap layers, and four types of Google Maps© layers.

If you want to use different maps, like Microsoft® Bing™ Maps for example, this is possible by using Custom Map Layers.

You can have up to three different Custom Map Layers at the same time.


2. How to use Custom Map Layers

The plugin distribution includes some example layer definition files for Custom Map Layers: Microsoft® Bing™ Maps (in three flavours), and two map layers made available by the Norwegian Mapping Authority.

The map layers are defined in short pieces of Javascript code that will be included in the OpenLayers code that displays the map on your site.

To use a custom map layer, you need to do two things:

  1. copy the layer definition file to the right place and filename on your server
  2. enable the Custom Map Layer(s) in the plugin options.

NOTE: if you want to use Microsoft® Bing™ Maps, you need to request an API key from the Microsoft Bing Maps Portal first. Also make sure you have read and understood their Terms Of Use.


3. Installing Custom Map Layer files

To use a custom map layer, the plugin needs a file with the layer definition in the Plugin directory, which is /plugins/content/gpxtrackmap

The file names must be:




respectively. You don't need all three files. If you want just one custom layer, you only need the CustomMapLayer1.js file. The plugin will show a warning in the page when it tries to access a file that it can not find, or if the file is empty.


4. Examples 

Here are two examples on how to prepare the required files for Custom Map Layers.

NOTE: if you can not copy / rename files directly on your server, you can also do it via FTP: download the CustomMapLayer_xxx.js file you want, rename it locally to CustomMapLayer1.js, and upload that into the gpxtrackmap directory on your server.


4.1. Example 1: including Bing™ Maps 

Go to the /plugins/content/gpxtrackmap directory on your server.

Copy the CustomMapLayer_BingRoad.js file and rename the copied file to CustomMapLayer1.js.

Copy the CustomMapLayer_BingHybrid.js file and rename the copied file to CustomMapLayer2.js.

Copy the CustomMapLayer_BingAerial.js file and rename the copied file to CustomMapLayer3.js.

IMPORTANT: Edit all three files - you will find the line 

var apiKey = "YourAPIKeyHere";

in each of them. You need to replace YourAPIKeyHere with the API key you got from Microsoft®.

If you don't do this, or don't have a valid API key, the maps will not work! (i.e. you will see your track on an empty map)


4.2. Example 2: including Norwegian topographic maps 

Go to the /plugins/content/gpxtrackmap directory on your server.

Copy the CustomMapLayer_Norgeskart.js file and rename the copied file to CustomMapLayer1.js.

 Since this map doesn't need any API keys, all you need to do now is to enable the map layer.


5.  Enabling Custom Map Layers

When you have the layer definition files in place on your server, you need to enable the Custom Map Layers in the plugin options.

Go to the Administration (back-end) of your site, go to Extensions / Plugin Manager and click "Content - GPXTrackMap". On the page "Map controls and layers", set "Custom map layer 1" as Default map layer.

If you have more layers, you can add "Custom map layer 2" and "Custom map layer 3" to the Selectable map layers.


6.  Setting individual Custom Map Layers in the invocation code

If you want to use a custom map layer for a specific Track Map, you can override the default map layer from the Plugin Options in the Invocation Code or in a Parameter Preset.

The custom map layers 1, 2 and 3 have the layer numbers 8, 9 and 10.

(layer numbers 0..7 are the predefined OpenStreetmap and Google Map layers).

So, if you want to have Custom Map Layer 1 for a specific track, write this into the invocation code:



7. Advanced: creating your own Custom Map Layer files

In order to use your own map layer, you need to find out how the map layer can be included in OpenLayers. I found the code for the Bing™ Maps in the OpenLayers examples. Let's take a look at one of the example files for the Bing™ Maps Hybrid layer, this is the content of the CustomMapLayer_BingHybrid.js file that comes with the plugin distribution:

var apiKey = "YourAPIKeyHere"; // enter YOUR Bing Maps API key here!

var layerBingHybrid = new OpenLayers.Layer.Bing({
name: "Bing Hybrid",
key: apiKey,
type: "AerialWithLabels"



Basically, you need to define a variable for an OpenLayers.Layer, and add that to the map. The map variable here is %MAPVAR% and will be replaced by the plugin with the actual map layer variable, which will be "map0" or "map1" if you have multiple maps on your page.

If you have the file ready, place it as CustomMapLayer1.js into the plugin directory (see above).