Skip to content

Latest commit

 

History

History
265 lines (210 loc) · 42.7 KB

client-side-config.md

File metadata and controls

265 lines (210 loc) · 42.7 KB

Client-side config

The file wwwroot/config.json in TerriaMap contains client-side configuration parameters. See this file for an example.

It has following structure:

Name Required Type Default Description
initializationUrls yes string[] [] The list of initialization files which define the catalog content, for more details check below.
v7initializationUrls yes string[] [] The list of v7 initialization files — these will be converted to v8 on the fly using catalog-converter. For more details check below.
parameters yes Parameters TerriaJS configuration options

Example

{
    "initializationUrls" : [
        "https://someurl.com/file.json",
        "init-fragment"
    ],
    "parameters": {
        "bingMapsKey": "...",
        ...
    }
}

intializationUrls

Each string in the array specifies a single initialization file (catalog) to be loaded by TerriaJS. The init files are loaded in the order they're specified.

Init URL

If a string ends with .json, it is assumed to be a complete relative or absolute URL to an init file. The file may be on an entirely separate web server, but in that case it must be accessible for Cross-Origin Resource Sharing (CORS). It may also be generated by a service rather than being a simple static file. If the URL is relative, it is relative to the config file.

Init fragment

If the string does not end with .json, such as "foo", it refers to an init file on the same web server at init/foo.json. In a TerriaMap directory on your computer, it can be found at wwwroot/init/foo.json.

Init fragment paths

See parameters.initFragmentPaths for defining path to Init fragments (defaults to init/).

Note: relative paths will be resolved to the base URL of client-side config URL (which defaults to config.json - which means the base application URL is used)

For example a map hosted at http://something.com/map

  • will have default configUrl = http://something.com/map/config.json
  • therefore will resolve initFragmentPaths to http://something.com/map
  • if using default initFragmentPaths = ["init"]
    • init fragments will be resolved to http://something.com/map/init

v7initializationUrls

It is also possible to add version 7 init files using the v7initializationUrls property — these will be converted on-the-fly in terriajs when a map is loaded. See catalog-converter repo for more information. Only v7 Init URLs are supported (v7 Init fragments are not supported).

Parameters

The best reference for now is interface ConfigParameters (you may have to search for interface ConfigParameters on that page to find it if future code changes change line numbers).

Specifies various options for configuring TerriaJS:

Name Required Type Default Description
appName no string "TerriaJS App" TerriaJS uses this name whenever it needs to display the name of the application.
supportEmail no string "info@terria.io" The email address shown when things go wrong.
defaultMaximumShownFeatureInfos no number 100 The maximum number of "feature info" boxes that can be displayed when clicking a point.
regionMappingDefinitionsUrl no string Deprecated please use regionMappingDefinitionsUrls array instead. If this is defined, it will override regionMappingDefinitionsUrls
regionMappingDefinitionsUrls no string[] ["build/TerriaJS/data/regionMapping.json"] URLs of JSON files that define region mapping for Tabular data (eg CSV). This option only needs to be changed in unusual deployments. It has to be changed if deploying as static site, for instance. It multiple URLs are provided then the first matching region will be used (in order of URLs)
catalogIndexUrl no string URL of the JSON file that contains index of catalog. See CatalogIndex
proj4ServiceBaseUrl no string "proj4def/" URL of Proj4 projection lookup service (part of TerriaJS-Server). This option only needs to be changed in unusual deployments. It has to be changed if deploying as static site, for instance.
corsProxyBaseUrl no string "proxy/" URL of CORS proxy service (part of TerriaJS-Server). This option only needs to be changed in unusual deployments. It has to be changed if deploying as static site, for instance.
proxyableDomainsUrl no string "proxyabledomains/" Deprecated, will be determined from serverconfig.
serverConfigUrl no string "serverconfig/"
shareUrl no string "share"
feedbackUrl no string URL of the service used to send feedback. If not specified, the "Give Feedback" button will not appear.
initFragmentPaths yes string[] ["init/"] An array of base paths to use to try to use to resolve init fragments in the URL. For example, if this property is [ "init/", "http://example.com/init/"], then a URL with #test will first try to load init/test.json and, if that fails, next try to load http://example.com/init/test.json.
storyEnabled yes boolean true Whether the story is enabled. If false story function button won't be available.
interceptBrowserPrint no boolean true True (the default) to intercept the browser's print feature and use a custom one accessible through the Share panel.
tabbedCatalog no boolean false True to create a separate explorer panel tab for each top-level catalog group to list its items in.
useCesiumIonTerrain no boolean true True to use Cesium World Terrain from Cesium ion. False to use terrain from the URL specified with the "cesiumTerrainUrl" property. If this property is false and "cesiumTerrainUrl" is not specified, the 3D view will use a smooth ellipsoid instead of a terrain surface. Defaults to true.
cesiumTerrainUrl no string undefined The URL to use for Cesium terrain in the 3D Terrain viewer, in quantized mesh format. This property is ignored if "useCesiumIonTerrain" is set to true, or if cesiumTerrainAssetId is present.
cesiumTerrainAssetId no number undefined The Cesium Ion Asset ID to use for Cesium terrain in the 3D Terrain viewer. cesiumIonAccessToken will be used to authenticate. This property is ignored if "useCesiumIonTerrain" is set to true.
cesiumIonAccessToken no string undefined The access token to use with Cesium ion. If "useCesiumIonTerrain" is true and this property is not specified, the Cesium default Ion key will be used. It is a violation of the Ion terms of use to use the default key in a deployed application.
useCesiumIonBingImagery no boolean true True to use Bing Maps from Cesium ion (Cesium World Imagery). By default, Ion will be used, unless the bingMapsKey property is specified, in which case that will be used instead. To disable the Bing Maps layers entirely, set this property to false and set bingMapsKey to null.
bingMapsKey no string undefined A Bing Maps API key used for requesting Bing Maps base maps and using the Bing Maps geocoder for searching. It is your responsibility to request a key and comply with all terms and conditions.
hideTerriaLogo no boolean false
brandBarElements no string[] undefined An array of strings of HTML that fill up the top left logo space (see brandBarSmallElements or displayOneBrand for small screens).
brandBarSmallElements no string[] undefined An array of strings of HTML that fill up the top left logo space - used for small screens.
displayOneBrand no number 0 Index of which brandBarElements to show for mobile header. This will only be used if brandBarSmallElements is undefined.
disableMyLocation no boolean undefined True to disable the "Centre map at your current location" button.
disableSplitter no boolean undefined True to disable the use of the splitter control.
experimentalFeatures no boolean undefined
magdaReferenceHeaders no MagdaReferenceHeaders undefined
locationSearchBoundingBox no number undefined
googleAnalyticsKey no string undefined A Google API key for Google Analytics. If specified, TerriaJS will send various events about how it's used to Google Analytics.
errorService no ErrorServiceOptions undefined Optional configuration for the remote error logging service that Terria should log errors to.
globalDisclaimer no any undefined
showWelcomeMessage no boolean false True to display welcome message on startup.
welcomeMessageVideo no any Video to show in welcome message.
showInAppGuides no boolean false True to display in-app guides.
helpContent no HelpContentItem [] The content to be displayed in the help panel.
helpContentTerms no Term
languageConfiguration no LanguageConfiguration undefined Language configuration of TerriaJS.
customRequestSchedulerLimits no RequestScheduler undefined Custom concurrent request limits for domains in Cesium's RequestScheduler.
persistViewerMode no boolean true Whether to load persisted viewer mode from local storage.
openAddData no boolean false Whether to open the add data explorer panel on load.
feedbackPreamble no string feedback.feedbackPreamble Text showing at the top of feedback form, supports the internationalization using the translation key.
feedbackPostamble no string feedback.feedbackPostamble Text showing at the bottom of feedback form, supports the internationalization using the translation key.
feedbackMinLength no number 0 Minimum length of feedback comment.
theme no any {} An object used to override theme properties - for example {"logoHeight": "70px"}.
storyRouteUrlPrefix no string undefined (Experimental) Prefix to which :story-id is added to fetch JSON for stories when using /story/:story-id routes. Should end in /
leafletAttributionPrefix no string undefined Attribution HTML string to show on Leaflet maps. Will use Leaflet's default if undefined. To hide Leaflet attribution - set leafletAttributionPrefix:""
extraCreditLinks no Credit[] See Credits default value Credits (attribution) to be shown at the bottom of the map.
storyVideo.videoUrl no string https://www.youtube-nocookie.com/embed/fbiQawV8IYY Video to show in Story Editor panel under Getting Started.
relatedMaps no RelatedMap[] See lib/Models/RelatedMaps.ts Maps to show in "Related Maps" menu panel
aboutButtonHrefUrl no string "about.html" About button URL. If set to null, then the About button will not be shown
searchBar no SearchBar new SearchBar() Search bar configuration
searchProviders no **SearchProviders [] Search providers that will be used for search

MagdaReferenceHeaders


HelpContentItem

Configuration of items to appear in the search bar

Name Required Type Default Description
itemName yes string undefined
title no string undefined Title of the help item
videoUrl no string undefined The video to show on the top of help item.
placeholderImage no string undefined Placeholder image for the video.
paneMode no enum["videoAndContent","slider","trainer"] "videoAndContent"
trainerItems no TrainerItem[] undefined List of the trainer steps
markdownText no string undefined The content of the help item, can use Markdown syntax.
icon no string undefined Icon to show next to the itemName.

TrainerItem

Name Required Type Default Description
title yes string Title of the trainer item.
footnote yes string Text to show below steps.
steps yes StepItem List of the steps for this trainer item.

StepItem

Name Required Type Default Description
title yes string Title of the step.
markdownDescription no string The content of the step item.

Term

Name Required Type Default Description
term yes string Name of the term, content will be attached to it when found in text.
content yes string Description of the content.
aliases no string[] Aliases of the term.

LanguageConfiguration

Name Required Type Default Description
enabled yes boolean false Controls whether a button to switch the portal's language is provided.
debug yes boolean false Controls whether debug information regarding translations is logged to the console.
react yes ReactOptions
languages yes Object {en: "english"} Language abbreviations. Please mind that matching locale files must exist.
fallbackLanguage yes string "en" Fallback language used if contents are not available in the currently selected language.
changeLanguageOnStartWhen yes string[] ["querystring", "localStorage", "navigator", "htmlTag"] Order of user language detection. See i18next browser language detection documentation for details.
overridesBaseUrl yes string Base URL for override namespace translation files. If set, this makes up the base URL for translation override files. Should end in "/". For example, if overridesBaseUrl = "test/path/", then the full path for translation override files will be "test/path/{{lng}}.json"

ErrorServiceOptions

Name Required Type Default Description
provider yes string undefined A string identifying the error service provider to use. Currently only rollbar is supported.
configuration no any undefined The configuration object to pass as constructor parameters to the error service provider instance. See the provider implementation for supported configuration parameters.

Example

{
    "enabled": true,
    "debug": false,
    "react": {
        "useSuspense": false
    },
    "languages": {
        "en": "english",
        "de": "deutsch"
    },
    "fallbackLanguage": "en",
    "changeLanguageOnStartWhen": [
        "querystring",
        "localStorage",
        "navigator",
        "htmlTag"
    ]
}

RelatedMap

Configuration of maps to appear in "Related Maps" menu panel

Name Required Type Default Description
title yes string undefined Title of the map
description yes string undefined Description for the map.
url yes string undefined URL to map.
imageUrl yes nyeso undefined URL to image/thumbnail (width: "200px" and height: "150px")

Example

{
    "imageUrl": "https://terria-catalogs-public.storage.googleapis.com/misc/related-maps/nationalmap.jpg",
    "url": "http://nationalmap.gov.au/",
    "title": "NationalMap",
    "description": "The NationalMap is a website for map-based access to spatial data from Australian government agencies. It is an initiative of the Australian Government's Department of the Prime Minister and Cabinet and the software has been developed by Data61 working closely with the Department of the Prime Minister and Cabinet, Geoscience Australia and other government agencies."
}

Credits (attribution)

Credits/Attribution shown at the bottom of the map. Supports internationalization.

Credits default value

[
    {
        "text": "map.extraCreditLinks.dataAttribution",
        "url": "about.html#data-attribution"
    },
    {
        "text": "map.extraCreditLinks.disclaimer",
        "url": "about.html#disclaimer"
    }
]

SearchBar

Configuration for the search bar. Some of the values will be used as default for search provider values.

Name Required Type Default Description
placeholder no string translate#search.placeholder Input text field placeholder shown when no input has been given yet. The string is translateable.
recommendedListLength no number 5 Maximum amount of entries in the suggestion list.
flightDurationSeconds no number 1.5 The duration of the camera flight to an entered location, in seconds.
minCharacters no number 3 Minimum number of characters required for search to start
boundingBoxLimit no Rectangle Cesium.Rectangle.MAX_VALUE Bounding box limits for the search results {west, south, east, north}