Skip to content

controlling-with-url-parameters.md

Latest commit

 

History

History
80 lines (62 loc) · 7.26 KB

controlling-with-url-parameters.md

File metadata and controls

80 lines (62 loc) · 7.26 KB

Controlling Terria with URL parameters

Many aspects of TerriaJS (and hence TerriaMap, NationalMap, and others) can be configured by the end user by passing URL parameters. Combine them like this:

  • The base URL, then a #
  • Then the first parameter
  • Then repeatedly: a &, and the next parameter

For example: http://nationalmap.gov.au#test&map=2d

Display parameters

Parameter Meaning
clean Don't load the default init/catalog file for this site.
map=2d Use the 2D (Leaflet) map, instead of the default.
map=3d Use the 3D (Cesium) map, instead of the default.
map=3dSmooth Use the 3D (Cesium) map without terrain, instead of the default.
playStory=1 Automatically start playing the map's Story, if there is one.
hideWorkbench=1 Collapse the workbench (left side) panel, useful for embedding. Also automatically plays a story, if there is one.
mode=preview Operate in "preview mode", which mostly means not showing a warning if the screen is small
share=... Load a map view previously saved using the "Share" function with URL shortening.
start=... Load a map view previously saved without URL shortening. The argument is a URL-encoded JSON structure defined using an internal format described below.
<initfile> Load init/catalog file as described below. This can be a URL to an init file - or an "init fragment" (eg simple - which resolves to init/simple.json). See initFragmentPaths in client side config parameters
hideWelcomeMessage Forces the welcome message not to be displayed.
ignoreErrors=1 Ignore all error messages.
configUrl=... Overwrite Terria config URL in dev environment only.

Catalog files (init files)

Any unrecognised parameter (eg foo or http://foo.com/bar.json) is treated as an "Init Source". These can be Init Fragments (eg foo) or Init URLs (eg http://foo.com/bar.json)

Init fragments are resolved using Client-side config parameters.initFragmentPaths (which defaults to "init/"). For example, foo would become init/foo.json

Multiple catalog files can be loaded this way, and will be combined. Files are loaded in order provided.

Note: relative URLs (and relative init fragments) in hash are resolved using base URL of the map - where as relative URLs in Client-side config initializationUrls and resolved using base URL of config URL

For example, http://nationalmap.gov.au#test will load init file http://nationalmap.gov.au/init/test.json

Full Init file docs are available here

Start data (ShareData)

Full ShareData docs are available here

The start= parameter essentially embeds an entire init/catalog file in the URL. The format is:

{
    "version": "8.0.0",
    "initSources": [
        "init/nm.json",
        "init/test.json",
        ...
        {
            "catalog": [
            ...
            ]
        },
        {
            "homeCamera": {
                "west": ...,
                "south": ...,
                "east": ...,
                "north": -...
            },
            "viewerMode": "3d"
        }
    ]
    }
}

The exact structure changes as features are added. The best way to understand it is:

  1. Adjust the view as desired
  2. Generate a share link
  3. URL-decode the share link (using a tool such as this).