terriajs
Version:
Geospatial data visualization platform.
81 lines (62 loc) • 7.44 kB
Markdown
# 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](http://nationalmap.gov.au#test&map=2d)
### Display parameters
| Parameter | Meaning |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clean` | Don't load the default [init/catalog file](../customizing/initialization-files.md) 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](../customizing/initialization-files.md) 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](../customizing/client-side-config.md#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](../customizing/client-side-config.md#init-fragment) (eg `foo`) or [Init URLs](../customizing/client-side-config.md#init-url) (eg `http://foo.com/bar.json`)
[Init fragments](../customizing/client-side-config.md#init-fragment) are resolved using Client-side config [`parameters.initFragmentPaths`](../customizing/client-side-config.md#parameters) (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`](../customizing/client-side-config.md#intializationurls) 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](../customizing/initialization-files.md)
### Start data (`ShareData`)
Full `ShareData` docs are [available here](../customizing/initialization-files.md#sharedata)
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](http://www.url-encode-decode.com/)).