Migration guide

A guide to upgrade a 7.x.x TerriaJS map to TerriaJS 8.0.0 and beyond. Please post on our GitHub discussions forum if you encounter problems or have suggestions for improving this.

Removed features in version 8

There are a few features in v7 that we have removed. Some of these include:

Internet Explorer 11 support (navigating to a map built with TerriaJS 8.0.0+ in IE11 will result in a completely blank page)
GDAL conversion service - Shapefiles (.zip) are now supported in the frontend
ABS ITT
WMS region mapping
Australian GNAF geocoding (and CSV batch geocoding) - we will be terminating our GNAF service as it is outdated
Some specific tableStyle options
Modifying styles for HTML elements within Terria's UI using custom CSS with .tjs-xxxx class selectors

Reach out to us if you are using these, we only know about the things we have seen.

Migrating to version 8

To migrate to TerriaJS version 8 you'll need to update each of these:

Your initialization files
Custom basemaps or basemap thumbnails
The TerriaMap code
Other modifications you've done

Upgrading initialization files using the catalog converter

The best way to upgrade your initialization files to TerriaJS version 8 is to run the files through our catalog converter.

If you want the converter as a command line tool with extra options (such as more control over ids) you can run the catalog converter CLI by installing from npm:

npm install -g catalog-converter
catalog-converter input-v7-init.json output-v8-init.json
catalog-converter --help # To see all options

Or checkout the source code to build & run it and/or contribute to it. (The source for the catalog converter UI can be found at https://github.com/TerriaJS/catalog-converter-ui).

Customising the selection of basemaps or basemap thumbnails

To customise the available basemaps or the thumbnails of basemaps in the basemap switcher, add/edit the baseMaps property in your initialization files

Upgrading TerriaMap code by git merge

If you have set up your map in the standard way using a fork of TerriaMap you will be able to upgrade from TerriaJS version 7 to version 8 by merging in the next branch of TerriaMap. To do this, run the following git commands:

Add TerriaMap as a remote:

git remote add TerriaMap https://github.com/TerriaJS/TerriaMap
git fetch TerriaMap

Make a new branch to work on:
```
git checkout -b upgrade-to-tjs-8
```
Make sure you already have the tag post-prettier merged. In mid 2019 we reformatted our codebase with prettier. If the following command doesn't list your new branch, follow these instructions to merge our reformatting commit without conflicts:
```
git branch --contains post-prettier
```
Merge in the latest from TerriaMap built on terriajs version 7 (this step can be skipped, but it might make the next merge easier):
```
git merge TerriaMap/terriajs-v7
```
Finally, merge in the latest TerriaMap built on terriajs version 8. If you completed the previous step, most conflicts in this stage should be resolved in favour of TerriaMap/main (the Incoming change):
```
git merge TerriaMap/main
```

Upgrading modifications

Let us know if you're stuck trying to upgrade something in the TerriaJS discussions forum