diff --git a/.prettierrc b/.prettierrc index 36b356317b6..20b41dfabeb 100644 --- a/.prettierrc +++ b/.prettierrc @@ -1,3 +1,4 @@ { - "trailingComma": "none" + "trailingComma": "none", + "tabWidth": 2 } diff --git a/CHANGES.md b/CHANGES.md index ab3d9b6b98e..799fcd9d939 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,6 +2,7 @@ #### next release (8.7.11) +- Explicitly set prettier tab-width - [The next improvement] #### 8.7.10 - 2024-11-29 diff --git a/doc/README.md b/doc/README.md index 367a1b6b43c..bfc125ba28c 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,10 +1,10 @@ [TerriaJS](http://terria.io) is an open-source framework for web-based geospatial catalog explorers. -- [Getting Started](getting-started.md): Quick start guide to building your first TerriaJS application. -- [Customizing](customizing/README.md): Configure and tweak a TerriaJS application, including skinning and setting up the catalog. -- [Connecting to Data](connecting-to-data/README.md): Connect TerriaJS to your servers and data. -- [Deploying](deploying/README.md): Deploy a TerriaJS application in simple and advanced scenarios. -- [Contributing](contributing/README.md): Add new features to TerriaJS, be part of the TerriaJS development team, set up a development environment, write tests, and perform code reviews. +- [Getting Started](getting-started.md): Quick start guide to building your first TerriaJS application. +- [Customizing](customizing/README.md): Configure and tweak a TerriaJS application, including skinning and setting up the catalog. +- [Connecting to Data](connecting-to-data/README.md): Connect TerriaJS to your servers and data. +- [Deploying](deploying/README.md): Deploy a TerriaJS application in simple and advanced scenarios. +- [Contributing](contributing/README.md): Add new features to TerriaJS, be part of the TerriaJS development team, set up a development environment, write tests, and perform code reviews. !!! note diff --git a/doc/connecting-to-data/README.md b/doc/connecting-to-data/README.md index c6008151b11..ab565aad956 100644 --- a/doc/connecting-to-data/README.md +++ b/doc/connecting-to-data/README.md @@ -4,8 +4,8 @@ Before beginning, it is very important to understand [Cross-Origin Resource Shar TerriaJS can interface with three broad types if data: -- [Catalog Group](../connecting-to-data/catalog-groups.md): A group (folder) of items. Different group types allow the contents to be manually specified or to be automatically determined by querying various types of server. TerriaJS can use many different types of servers to populate a group, including CKAN, CSW, WMS, and more. For example, if you define a catalog group that points at a Web Map Service (WMS) server, TerriaJS will query the WMS `GetCapabilities` when the group is opened and fill the group with all of the layers advertised by the WMS server. -- [Catalog Item](../connecting-to-data/catalog-items.md): Actual geospatial or chart data from a file or service, in various formats. TerriaJS supports WMS, KML, GeoJSON, ArcGIS MapServer, and many more files and services as catalog items. -- [Catalog Function](../connecting-to-data/catalog-functions.md): A parameterized service, such as a Web Processing Service (WPS). The user supplies the parameters and gets back some result. -- [Catalog Reference](../connecting-to-data/catalog-references.md): Resolves to a Catalog Group, Item or Function. -- [Catalog item search](item-search.md): A mechanism for searching inside catalog items. +- [Catalog Group](../connecting-to-data/catalog-groups.md): A group (folder) of items. Different group types allow the contents to be manually specified or to be automatically determined by querying various types of server. TerriaJS can use many different types of servers to populate a group, including CKAN, CSW, WMS, and more. For example, if you define a catalog group that points at a Web Map Service (WMS) server, TerriaJS will query the WMS `GetCapabilities` when the group is opened and fill the group with all of the layers advertised by the WMS server. +- [Catalog Item](../connecting-to-data/catalog-items.md): Actual geospatial or chart data from a file or service, in various formats. TerriaJS supports WMS, KML, GeoJSON, ArcGIS MapServer, and many more files and services as catalog items. +- [Catalog Function](../connecting-to-data/catalog-functions.md): A parameterized service, such as a Web Processing Service (WPS). The user supplies the parameters and gets back some result. +- [Catalog Reference](../connecting-to-data/catalog-references.md): Resolves to a Catalog Group, Item or Function. +- [Catalog item search](item-search.md): A mechanism for searching inside catalog items. diff --git a/doc/connecting-to-data/cross-origin-resource-sharing.md b/doc/connecting-to-data/cross-origin-resource-sharing.md index ef436f644fa..c4fdd8ab8ce 100644 --- a/doc/connecting-to-data/cross-origin-resource-sharing.md +++ b/doc/connecting-to-data/cross-origin-resource-sharing.md @@ -6,7 +6,7 @@ Failing to do this may result in an error like this: Next, you should add servers that _do_ support Cross-Origin Resource Sharing (CORS) to the `corsDomains` list in your [initialization file](../customizing/initialization-files.md). Servers in this list are contacted directly instead of going through the proxy... except: -- if an HTTPS web page is accessing an HTTP server (this way we avoid a mixed content warning from the browser). +- if an HTTPS web page is accessing an HTTP server (this way we avoid a mixed content warning from the browser). If your server does _not_ support CORS, then you still need to add it to the `allowProxyFor` whitelist, but do not add it to the `corsDomains` list. It will then be proxied. diff --git a/doc/connecting-to-data/customizing-data-appearance/feature-info-template.md b/doc/connecting-to-data/customizing-data-appearance/feature-info-template.md index 70b6b24ae16..547380c9e31 100644 --- a/doc/connecting-to-data/customizing-data-appearance/feature-info-template.md +++ b/doc/connecting-to-data/customizing-data-appearance/feature-info-template.md @@ -88,10 +88,10 @@ The preferred way to format numbers is using the `formats` option, eg: The supported format options are: -- `"maximumFractionDigits": X`: To reduce the number of decimal places to a maximum of X digits. -- `"minimumFractionDigits": X`: To increase the number of decimal places to a minimum of X digits. -- `"useGrouping": true`: To show thousands separators. -- `"style": "percent"`: To show 0.15 as 15%. +- `"maximumFractionDigits": X`: To reduce the number of decimal places to a maximum of X digits. +- `"minimumFractionDigits": X`: To increase the number of decimal places to a minimum of X digits. +- `"useGrouping": true`: To show thousands separators. +- `"style": "percent"`: To show 0.15 as 15%. A second method is to use `terria.formatNumber` directly in the template. This accepts an initial JSON string describing the same options as above. To simplify the notation, the quotes around the keys are optional here. @@ -128,9 +128,9 @@ As with number you can also use `terria.dateTimeformat` directly in the template You can replace text by directly using `terria.partialByName` in the template and providing partials for matching and replacement. For example, with the following template and partials, -- If the value of `feature.data.layerId` matches a property name in the `partials`, it will be replaced by corresponding value. -- If there is no matching in the `partials`, the original value will be used. -- Any unsafe values in the `partials` will be stripped off when being rendered. +- If the value of `feature.data.layerId` matches a property name in the `partials`, it will be replaced by corresponding value. +- If there is no matching in the `partials`, the original value will be used. +- Any unsafe values in the `partials` will be stripped off when being rendered. ```json "featureInfoTemplate": { @@ -154,17 +154,17 @@ For features with time-varying table-based data structures (eg. CSV, SOS2, SDMX- You can place this chart in your template using `{{terria.timeSeries.chart}}`. Alternatively, you can access the following component information: -- `{{terria.timeSeries.xName}}` - the x-column name -- `{{terria.timeSeries.yName}}` - the y-column name -- `{{terria.timeSeries.title}}` -- `{{terria.timeSeries.id}}` -- `{{terria.timeSeries.units}}` - the column units as a comma-separated string. -- `{{terria.timeSeries.data}}` - the data as a comma-separated string. +- `{{terria.timeSeries.xName}}` - the x-column name +- `{{terria.timeSeries.yName}}` - the y-column name +- `{{terria.timeSeries.title}}` +- `{{terria.timeSeries.id}}` +- `{{terria.timeSeries.units}}` - the column units as a comma-separated string. +- `{{terria.timeSeries.data}}` - the data as a comma-separated string. Please note: -- If any of the component information above contains double-quotes, double quotes will be removed before TerriaJS processes the template further. -- If any of the component information above is used as part of tag attributes, it must be surrounded by double-quotes. e.g. `` +- If any of the component information above contains double-quotes, double quotes will be removed before TerriaJS processes the template further. +- If any of the component information above is used as part of tag attributes, it must be surrounded by double-quotes. e.g. `` So you could reconstruct the chart manually as: diff --git a/doc/connecting-to-data/customizing-data-appearance/imagery-data.md b/doc/connecting-to-data/customizing-data-appearance/imagery-data.md index 224e2137a40..18ff1444c57 100644 --- a/doc/connecting-to-data/customizing-data-appearance/imagery-data.md +++ b/doc/connecting-to-data/customizing-data-appearance/imagery-data.md @@ -8,39 +8,39 @@ Here's an example json file which places some sample WMS items in an open group ```json { - "catalog": [ + "catalog": [ + { + "name": "WMS example", + "type": "group", + "isPromoted": true, + "isOpen": true, + "items": [ { - "name": "WMS example", - "type": "group", - "isPromoted": true, - "isOpen": true, - "items": [ - { - "name": "Solar Satellite DNI & GHI with datetime picker", - "layers": "Solar_Satellite_DNI_2014", - "url": "http://gis.aremi.nationalmap.gov.au/bom/wms", - "type": "wms", - "maxRefreshIntervals": 9000, - "showDatetimePicker": true, - "useOwnClock": true, - "featureInfoTemplate": { - "name": "{{GRAY_INDEX}} W/m2" - } - }, - { - "name": "Solar Satellite DNI & GHI with initialTimeSource", - "layers": "Solar_Satellite_DNI_2014", - "url": "http://gis.aremi.nationalmap.gov.au/bom/wms", - "type": "wms", - "maxRefreshIntervals": 9000, - "initialTimeSource": "2014-06-30T22:00:00Z", - "featureInfoTemplate": { - "name": "{{GRAY_INDEX}} W/m2" - } - } - ] + "name": "Solar Satellite DNI & GHI with datetime picker", + "layers": "Solar_Satellite_DNI_2014", + "url": "http://gis.aremi.nationalmap.gov.au/bom/wms", + "type": "wms", + "maxRefreshIntervals": 9000, + "showDatetimePicker": true, + "useOwnClock": true, + "featureInfoTemplate": { + "name": "{{GRAY_INDEX}} W/m2" + } + }, + { + "name": "Solar Satellite DNI & GHI with initialTimeSource", + "layers": "Solar_Satellite_DNI_2014", + "url": "http://gis.aremi.nationalmap.gov.au/bom/wms", + "type": "wms", + "maxRefreshIntervals": 9000, + "initialTimeSource": "2014-06-30T22:00:00Z", + "featureInfoTemplate": { + "name": "{{GRAY_INDEX}} W/m2" + } } - ] + ] + } + ] } ``` diff --git a/doc/connecting-to-data/customizing-data-appearance/model-dimensions.md b/doc/connecting-to-data/customizing-data-appearance/model-dimensions.md index 04cd37778a8..fad7bb5247f 100644 --- a/doc/connecting-to-data/customizing-data-appearance/model-dimensions.md +++ b/doc/connecting-to-data/customizing-data-appearance/model-dimensions.md @@ -8,38 +8,38 @@ For example - this renders a new drop down called "Color" that changes the `colo ```json { - "type": "csv", - "url": "test/NSW_LGA_NEXIS_201212.csv", - "name": "NSW LGA NEXIS 2012", - "modelDimensions": [ + "type": "csv", + "url": "test/NSW_LGA_NEXIS_201212.csv", + "name": "NSW LGA NEXIS 2012", + "modelDimensions": [ + { + "id": "cols", + "name": "Color", + "selectedId": "Red", + "options": [ { - "id": "cols", - "name": "Color", - "selectedId": "Red", - "options": [ - { - "id": "Red", - "value": { - "defaultStyle": { - "color": { - "colorPalette": "Reds" - } - } - } - }, - { - "id": "Blue", - "value": { - "defaultStyle": { - "color": { - "colorPalette": "Blues" - } - } - } - } - ] + "id": "Red", + "value": { + "defaultStyle": { + "color": { + "colorPalette": "Reds" + } + } + } + }, + { + "id": "Blue", + "value": { + "defaultStyle": { + "color": { + "colorPalette": "Blues" + } + } + } } - ] + ] + } + ] } ``` @@ -51,37 +51,37 @@ Model dimensions also supports the use of [Mustache templates](https://mustache. ```json { - "type": "csv", - "url": "test/NSW_LGA_NEXIS_201212.csv", - "name": "NSW LGA NEXIS 2012", - "modelDimensions": [ + "type": "csv", + "url": "test/NSW_LGA_NEXIS_201212.csv", + "name": "NSW LGA NEXIS 2012", + "modelDimensions": [ + { + "id": "Cols", + "selectedId": "Red", + "options": [ { - "id": "Cols", - "selectedId": "Red", - "options": [ - { - "id": "Red", - "value": { - "defaultStyle": { - "color": { - "colorPalette": "{{modelDimensions.0.selectedId}}" - } - } - } - }, - { - "id": "Blue", - "value": { - "defaultStyle": { - "color": { - "colorPalette": "{{modelDimensions.0.selectedId}}" - } - } - } - } - ] + "id": "Red", + "value": { + "defaultStyle": { + "color": { + "colorPalette": "{{modelDimensions.0.selectedId}}" + } + } + } + }, + { + "id": "Blue", + "value": { + "defaultStyle": { + "color": { + "colorPalette": "{{modelDimensions.0.selectedId}}" + } + } + } } - ] + ] + } + ] } ``` diff --git a/doc/connecting-to-data/customizing-data-appearance/overview.md b/doc/connecting-to-data/customizing-data-appearance/overview.md index 827ad2c03a3..a9765a23199 100644 --- a/doc/connecting-to-data/customizing-data-appearance/overview.md +++ b/doc/connecting-to-data/customizing-data-appearance/overview.md @@ -12,7 +12,7 @@ and can be included there too. This section explains how you can use such a file to improve the look of your data: -- [Customizing the Appearance of Tabular Data](./tabular-data.md) -- [Customizing the Appearance of Imagery Data](./imagery-data.md) -- [Customizing the Feature Info Template](./feature-info-template.md) -- [Using Model Dimensions to customise the Workbench](./model-dimensions.md) +- [Customizing the Appearance of Tabular Data](./tabular-data.md) +- [Customizing the Appearance of Imagery Data](./imagery-data.md) +- [Customizing the Feature Info Template](./feature-info-template.md) +- [Using Model Dimensions to customise the Workbench](./model-dimensions.md) diff --git a/doc/connecting-to-data/customizing-data-appearance/tabular-data.md b/doc/connecting-to-data/customizing-data-appearance/tabular-data.md index b1e12421b46..5896eee8c4b 100644 --- a/doc/connecting-to-data/customizing-data-appearance/tabular-data.md +++ b/doc/connecting-to-data/customizing-data-appearance/tabular-data.md @@ -49,8 +49,8 @@ Please note this documentation is still being developed, and does not cover ever that is possible. The definitive source of what you can do with `tableStyle` is this pair: -- [TableStyle](https://github.com/TerriaJS/terriajs/blob/master/lib/Models/TableStyle.js) -- [TableColumnStyle](https://github.com/TerriaJS/terriajs/blob/master/lib/Models/TableColumnStyle.js) +- [TableStyle](https://github.com/TerriaJS/terriajs/blob/master/lib/Models/TableStyle.js) +- [TableColumnStyle](https://github.com/TerriaJS/terriajs/blob/master/lib/Models/TableColumnStyle.js) ## Referencing your data @@ -132,9 +132,9 @@ If you want to change the appearance of individual columns, use `tableStyle`'s ` This example shows a few possibilities: -- A column called "original name" is displayed with the name "better name". -- The legend for that column is shown without any decimal places (`maximumFractionDigits` 0). -- A column in the original data called "bad" is hidden from the workbench. +- A column called "original name" is displayed with the name "better name". +- The legend for that column is shown without any decimal places (`maximumFractionDigits` 0). +- A column in the original data called "bad" is hidden from the workbench. The full list of options is in [TableColumnStyle](https://github.com/TerriaJS/terriajs/blob/master/lib/Models/TableColumnStyle.js). diff --git a/doc/connecting-to-data/item-search.md b/doc/connecting-to-data/item-search.md index 754b870fefb..f6cb53fc1de 100644 --- a/doc/connecting-to-data/item-search.md +++ b/doc/connecting-to-data/item-search.md @@ -6,7 +6,7 @@ TerriaJS provides an `ItemSearchProvider` API for defining custom search provide ## Available search providers -- [Indexed item search provider](item-search/indexed-item-search.md) +- [Indexed item search provider](item-search/indexed-item-search.md) ## Configuring the catalog item for searching @@ -50,8 +50,8 @@ The search tool can be opened from the expand menu for the catalog item in the w ## Future implementations -- GeoJSON search provider, for searching inside a geojson catalog item using its properties. -- WPS search provider, for searching any item using a remote server. +- GeoJSON search provider, for searching inside a geojson catalog item using its properties. +- WPS search provider, for searching any item using a remote server. ## Implementing your own search provider diff --git a/doc/connecting-to-data/item-search/indexed-item-search-provider-design-notes.md b/doc/connecting-to-data/item-search/indexed-item-search-provider-design-notes.md index 2d60ca5a89c..980f1fd2015 100644 --- a/doc/connecting-to-data/item-search/indexed-item-search-provider-design-notes.md +++ b/doc/connecting-to-data/item-search/indexed-item-search-provider-design-notes.md @@ -2,9 +2,9 @@ ## Requirements -- Should be file based, not requiring any additional backends -- Should be performant enough to search datasets with as many as 500000 features -- Must be able to search numeric, text or enum properties +- Should be file based, not requiring any additional backends +- Should be performant enough to search datasets with as many as 500000 features +- Must be able to search numeric, text or enum properties In the remaining section we describe the structure of the index. @@ -12,19 +12,19 @@ In the remaining section we describe the structure of the index. `indexRoot` captures the overall structure of the index. It has the following fields: -- `idProperty` - - Required - - Name of the feature property that is used as ID for indexing. This is also - sometimes used by the catalog item to uniquely identify & highlight the - selected feature. -- `resultsDataUrl: string` - - Required - - URL of the CSV [results data file](#results-data-file) mapping a feature by - its ID to result data associated with the feature. -- `indexes: Record` - - Required - - An object whose keys are the property names and values are the - corresponding [Index](#index-types) definition. +- `idProperty` + - Required + - Name of the feature property that is used as ID for indexing. This is also + sometimes used by the catalog item to uniquely identify & highlight the + selected feature. +- `resultsDataUrl: string` + - Required + - URL of the CSV [results data file](#results-data-file) mapping a feature by + its ID to result data associated with the feature. +- `indexes: Record` + - Required + - An object whose keys are the property names and values are the + corresponding [Index](#index-types) definition. ## Results data file @@ -39,18 +39,18 @@ eg: It should contain a header for each column. It should also have a column for the `idProperty` specified in the `indexRoot.json` file. Terria also recongnizes a few special columns which it uses to construct a target to zoom to when the user selects the result. -- `latitude` - - Required - - The latitude of the feature -- `longitude` - - Required - - The longitude of the feature -- `height` - - Optional - - The height of the feature -- `radius` - - Optional - - The radius of the bounding sphere containing the feature +- `latitude` + - Required + - The latitude of the feature +- `longitude` + - Required + - The longitude of the feature +- `height` + - Optional + - The height of the feature +- `radius` + - Optional + - The radius of the bounding sphere containing the feature A zoom target is constructed using the `latitude`, `longitude` and `height` or the `radius` whichever is known. `height` is the height of the feature and `radius` is a radius of the bounding sphere to zoom to. @@ -64,14 +64,14 @@ Numeric index is used for searching numeric properties. It can be used for searc #### Definition -- `type: "numeric"` - - Required -- `range: {min: number, max: number}` - - Required - - The range of values in the index. -- `url: string` - - Required - - URL of the [numeric index file](#numeric-index-file) +- `type: "numeric"` + - Required +- `range: {min: number, max: number}` + - Required + - The range of values in the index. +- `url: string` + - Required + - URL of the [numeric index file](#numeric-index-file) eg: @@ -100,11 +100,11 @@ Enum index is useful for searching fixed list of strings, eg: Roof material prop #### Definition -- `type: "enum"` - - Required -- `values: Record` - - Required - - An object whose keys are the enum string and value defines the [enum value index](#enum-value-index). +- `type: "enum"` + - Required +- `values: Record` + - Required + - An object whose keys are the enum string and value defines the [enum value index](#enum-value-index). eg: @@ -128,12 +128,12 @@ Defines the index for a single enum member. ##### Definition -- `count: number` - - Required - - Number of features that have this enum value. -- `url: string` - - Required - - URL of the [enum value index file](#enum-value-index-file). +- `count: number` + - Required + - Number of features that have this enum value. +- `url: string` + - Required + - URL of the [enum value index file](#enum-value-index-file). ##### Enum value index file @@ -155,11 +155,11 @@ Text index is used for searching arbitrary text properties, for eg: street addre ##### Definition -- `type: "text"` -- Required -- `url: string` -- Required -- URL of the [text index file](#text-index-file). +- `type: "text"` +- Required +- `url: string` +- Required +- URL of the [text index file](#text-index-file). eg: @@ -171,12 +171,12 @@ eg: Text index file is a JSON file with the following structure: -- `index: MiniSearch` - - Required - - The searialized [Minisearch](https://github.com/lucaong/minisearch) index instance -- `options: MiniSearchOptions` - - Required - - The options used to create the MiniSearch instance. +- `index: MiniSearch` + - Required + - The searialized [Minisearch](https://github.com/lucaong/minisearch) index instance +- `options: MiniSearchOptions` + - Required + - The options used to create the MiniSearch instance. ### Why CSV and not JSON? diff --git a/doc/connecting-to-data/item-search/indexed-item-search.md b/doc/connecting-to-data/item-search/indexed-item-search.md index 2176915fcba..3d11384207d 100644 --- a/doc/connecting-to-data/item-search/indexed-item-search.md +++ b/doc/connecting-to-data/item-search/indexed-item-search.md @@ -48,28 +48,28 @@ Search provider configuration: `search: SearchableItemTraits` -- `providerType: "indexed"` - - Required - - A string identifying the search provider in the [ItemSearchProviders](../../../lib/Models/ItemSearchProviders/ItemSearchProviders.ts) registry. This should be `"indexed"` for `IndexedItemSearchProvider`. -- `providerOptions: any` - - Required - - Options for the indexed item search provider - - `indexRootUrl: string` - - Required - - The URL of `indexRoot.json` file that was generted using `terriajs-indexer`. -- `resultTemplate: string` +- `providerType: "indexed"` + - Required + - A string identifying the search provider in the [ItemSearchProviders](../../../lib/Models/ItemSearchProviders/ItemSearchProviders.ts) registry. This should be `"indexed"` for `IndexedItemSearchProvider`. +- `providerOptions: any` + - Required + - Options for the indexed item search provider + - `indexRootUrl: string` + - Required + - The URL of `indexRoot.json` file that was generted using `terriajs-indexer`. +- `resultTemplate: string` - - Optional - - A [Mustache](https://mustache.github.io/) formatted template string used to generate a title text for each result in the search results listing. The columns in `resultsData.csv` can be used as variables in the template string. If not provided, the text defaults to the ID of the feature. + - Optional + - A [Mustache](https://mustache.github.io/) formatted template string used to generate a title text for each result in the search results listing. The columns in `resultsData.csv` can be used as variables in the template string. If not provided, the text defaults to the ID of the feature. -- `parameters: SearchParameterTraits[]` - - Optional - - Additional configuration for each search parameter. This is given as an array of `SearchParameterTraits` indexed by the parameter ID. - - `id: string` - - Required - - ID of the parameter - - `name?: string` - - Optional - - A human readable name to assign to the parameter which will be shown to the user in the search form instead of the ID. - - `queryOptions?: any` - - Query options to be passed to the index when searching. Currently only `text` parameters accept `queryOptions`. For `text` parameter `queryOptions` is expected to be a valid [Minisearch Search Options](https://lucaong.github.io/minisearch/modules/_minisearch_.html#searchoptions-1) object. +- `parameters: SearchParameterTraits[]` + - Optional + - Additional configuration for each search parameter. This is given as an array of `SearchParameterTraits` indexed by the parameter ID. + - `id: string` + - Required + - ID of the parameter + - `name?: string` + - Optional + - A human readable name to assign to the parameter which will be shown to the user in the search form instead of the ID. + - `queryOptions?: any` + - Query options to be passed to the index when searching. Currently only `text` parameters accept `queryOptions`. For `text` parameter `queryOptions` is expected to be a valid [Minisearch Search Options](https://lucaong.github.io/minisearch/modules/_minisearch_.html#searchoptions-1) object. diff --git a/doc/contributing/README.md b/doc/contributing/README.md index c1071a137b2..3444db5780b 100644 --- a/doc/contributing/README.md +++ b/doc/contributing/README.md @@ -2,23 +2,23 @@ We're thrilled to have you as a contributor! This section explains how to set up ## For all contributors -- [Setting up a development environment](./development-environment.md) -- [Architecture](./architecture.md): The big picture of TerriaJS's architecture **(version 7)** - this page requires major changes to be updated for TerriaJS version 8 - - [New model layer documentation](./model-layer.md) **(version 8)** - - [Traits in depth](./traits-in-depth.md) **(version 8)** - - [Strata examples](./strata-examples.md) **(version 8)** - - [Result object and Error Handling](./result-object-and-error-handling) **(version 8)** - - [Init source](./init-sources.md) **(version 8)** -- [Frontend style guide](./frontend-style-guide.md) -- [Development translation guide](./translation-guide-dev.md) -- [Problems and Solutions](./problems-and-solutions.md) -- [Contributing to TerriaJS](https://github.com/TerriaJS/terriajs/blob/main/CONTRIBUTING.md): How to submit a pull request. Please read! :) +- [Setting up a development environment](./development-environment.md) +- [Architecture](./architecture.md): The big picture of TerriaJS's architecture **(version 7)** - this page requires major changes to be updated for TerriaJS version 8 + - [New model layer documentation](./model-layer.md) **(version 8)** + - [Traits in depth](./traits-in-depth.md) **(version 8)** + - [Strata examples](./strata-examples.md) **(version 8)** + - [Result object and Error Handling](./result-object-and-error-handling) **(version 8)** + - [Init source](./init-sources.md) **(version 8)** +- [Frontend style guide](./frontend-style-guide.md) +- [Development translation guide](./translation-guide-dev.md) +- [Problems and Solutions](./problems-and-solutions.md) +- [Contributing to TerriaJS](https://github.com/TerriaJS/terriajs/blob/main/CONTRIBUTING.md): How to submit a pull request. Please read! :) ## Coming from version 7? -- [Version 8 migration guide](./migration-guide.md) +- [Version 8 migration guide](./migration-guide.md) ## Special cases -- [Setting up Saucelabs](setting-up-saucelabs.md): Creating a local Saucelabs instance for cross-browser testing. -- [Using a Custom Version of Cesium](using-a-custom-version-of-cesium.md) +- [Setting up Saucelabs](setting-up-saucelabs.md): Creating a local Saucelabs instance for cross-browser testing. +- [Using a Custom Version of Cesium](using-a-custom-version-of-cesium.md) diff --git a/doc/contributing/development-environment.md b/doc/contributing/development-environment.md index 6dbbac4979c..5347539c5b5 100644 --- a/doc/contributing/development-environment.md +++ b/doc/contributing/development-environment.md @@ -59,10 +59,10 @@ yarn install Yarn will: -- Install all dependencies for both TerriaMap and any packages in your `packages` directory. -- Install the `devDependencies` for packages in the `packages` directory so you can actually develop on them. -- Create sym-links so that everything works. -- De-duplicate semver-compatible packages and bubble them up to the root `node_modules` directory. +- Install all dependencies for both TerriaMap and any packages in your `packages` directory. +- Install the `devDependencies` for packages in the `packages` directory so you can actually develop on them. +- Create sym-links so that everything works. +- De-duplicate semver-compatible packages and bubble them up to the root `node_modules` directory. Now, we can edit TerriaJS in `packages/terriajs` with the benefit of a full-featured git repo. @@ -138,17 +138,17 @@ The test suite is run by opening a web browser on [http://localhost:3002/SpecRun Run any of these tasks with `yarn gulp ` from within the TerriaJS directory: -- default - Invoked by running gulp without any arguments, this task invokes the `build` and `lint` tasks. -- `build` - Builds a non-minified version of the TerriaJS tests. This task may take 10 seconds or more, which is the main reason for the next task. -- `watch` - Starts the same as `build` but then it stays running and watches for changes to any TerriaJS or Cesium source file that was pulled in to the build. When a change to any of these files is detected, a fast incremental build is automatically kicked off. The incremental build is much faster than the full rebuild because dependencies between source files are cached. -- `release` - The same as `build` except that it also minifies the build tests. -- `lint` - Runs ESLint on the files in the `lib` folder and reports any problems. The ESLint rules are defined in the `.eslintrc` file in the root directory of TerriaJS. A stricter set of rules is also find in the `.eslintrc` file in `lib/ReactViews`. -- `docs` - Generates the user guide and reference documentation. The user guide is served at `http://localhost:3002/doc/guide/` and the reference documentation is at `http://localhost:3002/doc/reference/`. -- `make-schema` - Generates [JSON Schema](http://json-schema.org/) for the TerriaJS [Initialization Files](../customizing/initialization-files.md) from the source code. The schema is written to `wwwroot/schema`. -- `test` - Detects browsers available on the local system and launches the test suite in each. The results are reported on the command line. -- `test-electron` - Runs the tests in Electron, a headless (no UI) Chrome-like browser. -- `test-saucelabs` - Runs the tests on a bunch of browsers on [Sauce Labs](https://saucelabs.com/). You will need to [Set up Sauce Labs](setting-up-saucelabs.md). -- `test-browserstack` - Runs the tests on a bunch of browsers on [BrowserStack](https://www.browserstack.com/). You will need to set up a BrowserStack account. +- default - Invoked by running gulp without any arguments, this task invokes the `build` and `lint` tasks. +- `build` - Builds a non-minified version of the TerriaJS tests. This task may take 10 seconds or more, which is the main reason for the next task. +- `watch` - Starts the same as `build` but then it stays running and watches for changes to any TerriaJS or Cesium source file that was pulled in to the build. When a change to any of these files is detected, a fast incremental build is automatically kicked off. The incremental build is much faster than the full rebuild because dependencies between source files are cached. +- `release` - The same as `build` except that it also minifies the build tests. +- `lint` - Runs ESLint on the files in the `lib` folder and reports any problems. The ESLint rules are defined in the `.eslintrc` file in the root directory of TerriaJS. A stricter set of rules is also find in the `.eslintrc` file in `lib/ReactViews`. +- `docs` - Generates the user guide and reference documentation. The user guide is served at `http://localhost:3002/doc/guide/` and the reference documentation is at `http://localhost:3002/doc/reference/`. +- `make-schema` - Generates [JSON Schema](http://json-schema.org/) for the TerriaJS [Initialization Files](../customizing/initialization-files.md) from the source code. The schema is written to `wwwroot/schema`. +- `test` - Detects browsers available on the local system and launches the test suite in each. The results are reported on the command line. +- `test-electron` - Runs the tests in Electron, a headless (no UI) Chrome-like browser. +- `test-saucelabs` - Runs the tests on a bunch of browsers on [Sauce Labs](https://saucelabs.com/). You will need to [Set up Sauce Labs](setting-up-saucelabs.md). +- `test-browserstack` - Runs the tests on a bunch of browsers on [BrowserStack](https://www.browserstack.com/). You will need to set up a BrowserStack account. See `gulpfile.js` for more gulp tasks. @@ -156,12 +156,12 @@ See `gulpfile.js` for more gulp tasks. Run any of these tasks with `yarn gulp ` from within the TerriaMap directory: -- default - Invoked by running gulp without any arguments, this task invokes the `build` and `lint` tasks. -- `build` - Builds a non-minified version of TerriaMap, TerriaJS, Cesium, and all other dependencies, together in one JS file (called `wwwroot/build/TerriaMap.js`). Only the parts of TerriaJS and Cesium that we use (directly or indirectly) are pulled in. Web Workers, CSS, and other resources are also built by this task. This task may take 10 seconds or more, which is the main reason for the next task. -- `watch` - Starts the same as `build` but then it stays running and watches for changes to any TerriaMap, TerriaJS, or Cesium resource. When a change to any of these files is detected, a fast incremental build is automatically kicked off. The incremental build is much faster than the full rebuild because dependencies between source files are cached. -- `release` - The same as `build` except that it also minifies the built JavaScript files. This task should be used when building for production. -- `lint` - Runs ESLint on `index.js` and the files in the `lib` folder and reports any problems. The ESLint rules are defined in the `.eslintrc` file in the root directory of TerriaMap. -- `make-package` - Creates a `.tar.gz` package in `deploy/packages` from the current build. This package can be copied to another machine to run the application there. The arguments are: +- default - Invoked by running gulp without any arguments, this task invokes the `build` and `lint` tasks. +- `build` - Builds a non-minified version of TerriaMap, TerriaJS, Cesium, and all other dependencies, together in one JS file (called `wwwroot/build/TerriaMap.js`). Only the parts of TerriaJS and Cesium that we use (directly or indirectly) are pulled in. Web Workers, CSS, and other resources are also built by this task. This task may take 10 seconds or more, which is the main reason for the next task. +- `watch` - Starts the same as `build` but then it stays running and watches for changes to any TerriaMap, TerriaJS, or Cesium resource. When a change to any of these files is detected, a fast incremental build is automatically kicked off. The incremental build is much faster than the full rebuild because dependencies between source files are cached. +- `release` - The same as `build` except that it also minifies the built JavaScript files. This task should be used when building for production. +- `lint` - Runs ESLint on `index.js` and the files in the `lib` folder and reports any problems. The ESLint rules are defined in the `.eslintrc` file in the root directory of TerriaMap. +- `make-package` - Creates a `.tar.gz` package in `deploy/packages` from the current build. This package can be copied to another machine to run the application there. The arguments are: | Argument | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -169,5 +169,5 @@ Run any of these tasks with `yarn gulp ` from within the TerriaMap di | `--serverConfigOverride ` | The path to a file with overrides of the `devserverconfig.json` file. If not specified, `devserverconfig.json` is used unmodified. | | `--clientConfigOverride ` | The path to a file with overrides of the `wwwroot/config.json` file. If not specified, `wwwroot/config.json` is used unmodified. | -- `clean` - Removes the `wwwroot/build` directory. -- `sync-terriajs-dependencies` - For all npm packages used by both TerriaMap and TerriaJS, updates TerriaMap's `package.json` to use the same version as TerriaJS. This avoids build problems (errors, hangs) caused by package version conflicts. +- `clean` - Removes the `wwwroot/build` directory. +- `sync-terriajs-dependencies` - For all npm packages used by both TerriaMap and TerriaJS, updates TerriaMap's `package.json` to use the same version as TerriaJS. This avoids build problems (errors, hangs) caused by package version conflicts. diff --git a/doc/contributing/feature-picking.md b/doc/contributing/feature-picking.md index 8f457b6214a..9d06dbd67a2 100644 --- a/doc/contributing/feature-picking.md +++ b/doc/contributing/feature-picking.md @@ -8,36 +8,36 @@ It is a work in progress. **Not included in doc**: -- How picked features are shared +- How picked features are shared ## Related docs -- [Feature Info Template](../connecting-to-data/customizing-data-appearance/feature-info-template.md) +- [Feature Info Template](../connecting-to-data/customizing-data-appearance/feature-info-template.md) ## Outline 1. Catalog item creates "mappable" items: - - [Cesium Imagery Provider](https://cesium.com/learn/cesiumjs/ref-doc/ImageryProvider.html) - - [Cesium Data Source](https://cesium.com/learn/cesiumjs/ref-doc/DataSource.html) - - [Cesium Terrain Provider](https://cesium.com/learn/cesiumjs/ref-doc/TerrainProvider.html) - - [Cesium Abstract Primitive](https://cesium.com/learn/cesiumjs/ref-doc/Primitive.html) + - [Cesium Imagery Provider](https://cesium.com/learn/cesiumjs/ref-doc/ImageryProvider.html) + - [Cesium Data Source](https://cesium.com/learn/cesiumjs/ref-doc/DataSource.html) + - [Cesium Terrain Provider](https://cesium.com/learn/cesiumjs/ref-doc/TerrainProvider.html) + - [Cesium Abstract Primitive](https://cesium.com/learn/cesiumjs/ref-doc/Primitive.html) 1. Catalog item returns `mapItems` which are rendered by Leaflet or Cesium 1. User clicks on map - - Cesium/Leaflet resolves features - - `FeatureInfoUrlMixin.getFeaturesFromPickResult` is called if applicable - - Feature highlight is created if applicable + - Cesium/Leaflet resolves features + - `FeatureInfoUrlMixin.getFeaturesFromPickResult` is called if applicable + - Feature highlight is created if applicable 1. Terria `PickedFeatures` is populated 1. Picked features appear in [`FeatureInfoPanel`](#featureinfopanel) - - Catalog item for each feature is resolved - - Each catalog item renders [`FeatureInfoCatalogItem`](#featureinfocatalogitem) - - Each feature in catalog item renders [`FeatureInfoSection`](#featureinfosection) + - Catalog item for each feature is resolved + - Each catalog item renders [`FeatureInfoCatalogItem`](#featureinfocatalogitem) + - Each feature in catalog item renders [`FeatureInfoSection`](#featureinfosection) 1. Feature info is rendered by [`FeatureInfoSection`](#featureinfosection) - - Pre-processing/cleaning of feature properties - - Setup Mustache template context data (eg custom expressions) - - `FeatureInfoContext.featureInfoContext()` is called if applicable - and merged into Mustache template context - - Feature info template is rendered - - Mustache - - parseCustomHtmlToReact + - Pre-processing/cleaning of feature properties + - Setup Mustache template context data (eg custom expressions) + - `FeatureInfoContext.featureInfoContext()` is called if applicable - and merged into Mustache template context + - Feature info template is rendered + - Mustache + - parseCustomHtmlToReact **Why is this so complicated?** @@ -47,24 +47,24 @@ Because there is no explicit link between Terria model layer and map renderers ( When creating mappable items there are things you must do to ensure feature picking functions correctly: -- What is a feature? - - Vector/cesium primitive - - Pixel value - - 3D tile - - ... -- How is it picked/selected? - - Does it require a network request? (eg WMS `GetFeatureInfo`) - - Will Cesium handle it automatically - or needs manual implementation -- When a feature is picked, can it's owner (catalog item) be resolved? - - Can it's underlying data be resolved (eg a row in a CSV)? -- What feature information is to be shown to the user? - - Is a feature info template needed? -- Does the feature information require data that isn't stored in the feature itself? - - Do additional network requests need to be made? -- Does the feature change over time? - - How should this be handled when the timeline changes? -- How is the feature shared (in share link/story)? - - Does geometry need to be saved - or is feature a product of a network request +- What is a feature? + - Vector/cesium primitive + - Pixel value + - 3D tile + - ... +- How is it picked/selected? + - Does it require a network request? (eg WMS `GetFeatureInfo`) + - Will Cesium handle it automatically - or needs manual implementation +- When a feature is picked, can it's owner (catalog item) be resolved? + - Can it's underlying data be resolved (eg a row in a CSV)? +- What feature information is to be shown to the user? + - Is a feature info template needed? +- Does the feature information require data that isn't stored in the feature itself? + - Do additional network requests need to be made? +- Does the feature change over time? + - How should this be handled when the timeline changes? +- How is the feature shared (in share link/story)? + - Does geometry need to be saved - or is feature a product of a network request This varies for each type of mappable item. Cesium will give you some of them for free - depending on feature type. @@ -106,12 +106,12 @@ See [lib/Models/Feature/Feature.ts](/lib/Models/Feature/Feature.ts) `Feature` is a wrapper around a Cesium [`Entity`](https://cesium.com/learn/cesiumjs/ref-doc/Entity.html) -- `data` property contains [`TerriaFeatureData`](#terriafeaturedata) -- `_catalogItem` - owner of feature -- `imageryProvider` - if feature picked is from imagery provider -- `loadingFeatureInfoUrl` -- `cesiumEntity` - original cesium entity (when picked) -- `cesiumPrimitive` - original cesium primitive (when picked) +- `data` property contains [`TerriaFeatureData`](#terriafeaturedata) +- `_catalogItem` - owner of feature +- `imageryProvider` - if feature picked is from imagery provider +- `loadingFeatureInfoUrl` +- `cesiumEntity` - original cesium entity (when picked) +- `cesiumPrimitive` - original cesium primitive (when picked) #### `TerriaFeatureData` @@ -121,17 +121,17 @@ This property of [`Feature`](#terria-feature-object) should be used for Terria s Current properties: -- `rowIds` - array of table row IDS that correspond to the feature. This is required for TableMixin to find original data after a [`Feature`](#terria-feature-object) has been picked, -- `timeIntervalCollection` - if feature is time varying, this property can be used instead of `properties` for convenience. +- `rowIds` - array of table row IDS that correspond to the feature. This is required for TableMixin to find original data after a [`Feature`](#terria-feature-object) has been picked, +- `timeIntervalCollection` - if feature is time varying, this property can be used instead of `properties` for convenience. #### Example usage `TableMixin` example usage - enabling time-series charts in feature info: -- `TableMixin` adds `rowIds` to `data` property here [`lib/Table/createLongitudeLatitudeFeaturePerRow.ts`](/lib/Table/createLongitudeLatitudeFeaturePerRow.ts#L83) -- A feature is picked, which triggers `TableMixin.featureInfoContext()`. -- It calls [`lib/Table/tableFeatureInfoContext.ts`](/lib/Table/tableFeatureInfoContext.ts) which uses `data.rowIds` to add "Mustache context data" to the picked feature. -- The Mustache context data contain time series chart functionality +- `TableMixin` adds `rowIds` to `data` property here [`lib/Table/createLongitudeLatitudeFeaturePerRow.ts`](/lib/Table/createLongitudeLatitudeFeaturePerRow.ts#L83) +- A feature is picked, which triggers `TableMixin.featureInfoContext()`. +- It calls [`lib/Table/tableFeatureInfoContext.ts`](/lib/Table/tableFeatureInfoContext.ts) which uses `data.rowIds` to add "Mustache context data" to the picked feature. +- The Mustache context data contain time series chart functionality ### `ImageryLayerFeatureInfo` @@ -147,24 +147,24 @@ Note use of `data` property and how we use `featureDataToGeoJson` to convert `Im There are three nested React components -- [`FeatureInfoPanel`](/lib/ReactViews/FeatureInfo/FeatureInfoPanel.tsx) - - [`FeatureInfoCatalogItem`](/lib/ReactViews/FeatureInfo/FeatureInfoCatalogItem.tsx) for each catalog item - - [`FeatureInfoSection`](/lib/ReactViews/FeatureInfo/FeatureInfoSection.tsx) for each feature in each catalog item +- [`FeatureInfoPanel`](/lib/ReactViews/FeatureInfo/FeatureInfoPanel.tsx) + - [`FeatureInfoCatalogItem`](/lib/ReactViews/FeatureInfo/FeatureInfoCatalogItem.tsx) for each catalog item + - [`FeatureInfoSection`](/lib/ReactViews/FeatureInfo/FeatureInfoSection.tsx) for each feature in each catalog item ### `FeatureInfoPanel` Top level component -- Pulls features from `Terria.pickedFeatures` -- Matches features with catalog items -- Renders `FeatureInfoCatalogItem` for each. +- Pulls features from `Terria.pickedFeatures` +- Matches features with catalog items +- Renders `FeatureInfoCatalogItem` for each. ### `FeatureInfoCatalogItem` Simple component -- Applied limit to how many features are shown -- Renders `FeatureInfoSection` for each feature in specified catalog item +- Applied limit to how many features are shown +- Renders `FeatureInfoSection` for each feature in specified catalog item ### `FeatureInfoSection` @@ -172,16 +172,16 @@ Renders feature information. There are two methods of rendering feature info: -- **"Raw data"** - presents all feature properties as a table -- **"Curated data"** - applies Mustache template using feature properties (and context data) to render complex view of feature properties - - Curated data requires a Mustache [Feature Info Template](/doc/connecting-to-data/customizing-data-appearance/feature-info-template.md) +- **"Raw data"** - presents all feature properties as a table +- **"Curated data"** - applies Mustache template using feature properties (and context data) to render complex view of feature properties + - Curated data requires a Mustache [Feature Info Template](/doc/connecting-to-data/customizing-data-appearance/feature-info-template.md) #### Cleans/pre-processes feature properties -- For time-varying features, gets values for `currentTime` -- Processes nested JSON values -- Replaces values which may interfere with Mustache templates -- Applies `FeatureInfoTraits.format` options (eg `number.toLocaleString` options) +- For time-varying features, gets values for `currentTime` +- Processes nested JSON values +- Replaces values which may interfere with Mustache templates +- Applies `FeatureInfoTraits.format` options (eg `number.toLocaleString` options) #### Raw data: generate table @@ -193,18 +193,18 @@ See [`generateCesiumInfoHTMLFromProperties`](/lib/ReactViews/FeatureInfo/generat This is an object with properties which can be used by Mustache templates: -- All (cleaned) feature properties - this forms the base of the object -- `properties` = array of key:value pairs of feature properties -- `terria` magical object - - a bunch of custom mustache expressions - - `partialByName` - - `formatNumber` - - `formatDateTime` - - `urlEncodeComponent` - - `urlEncode` - - `coords` with `latitude` and `longitude` - - `currentTime` -- properties provided by catalog item through `featureInfoContext` function +- All (cleaned) feature properties - this forms the base of the object +- `properties` = array of key:value pairs of feature properties +- `terria` magical object + - a bunch of custom mustache expressions + - `partialByName` + - `formatNumber` + - `formatDateTime` + - `urlEncodeComponent` + - `urlEncode` + - `coords` with `latitude` and `longitude` + - `currentTime` +- properties provided by catalog item through `featureInfoContext` function ##### Example mustache template with context data @@ -220,9 +220,9 @@ A custom expression - which formats `terria.currentTime` as `"dd-mm-yyyy HH:MM:s Using three components: -- The template - see `FeatureInfoTraits.template` -- "Mustache context data" - see above -- Partials - see `FeatureInfoTraits.partials` +- The template - see `FeatureInfoTraits.template` +- "Mustache context data" - see above +- Partials - see `FeatureInfoTraits.partials` The output HTML/markdown may contain Custom Components. These are handled by the next step diff --git a/doc/contributing/frontend-style-guide.md b/doc/contributing/frontend-style-guide.md index afcd37c2eff..465e6db476b 100644 --- a/doc/contributing/frontend-style-guide.md +++ b/doc/contributing/frontend-style-guide.md @@ -43,8 +43,8 @@ are encapsulated in an action, e.g. rather than: ```ts runInAction(() => { - this.props.viewState.selectedHelpMenuItem = this.props.content.itemName; - this.props.viewState.helpPanelExpanded = true; + this.props.viewState.selectedHelpMenuItem = this.props.content.itemName; + this.props.viewState.helpPanelExpanded = true; }); ``` @@ -147,8 +147,8 @@ For the most part, simple strings should go through fine by calling TypeScript should be the default choice when writing components. Lean towards `tsx` when writing React components, with the following caveats: -- The majority of the `lib/Styled` components are not yet `tsx`, these will need - to be (tsx-ified!) or imported via CommonJS to consume them, e.g. +- The majority of the `lib/Styled` components are not yet `tsx`, these will need + to be (tsx-ified!) or imported via CommonJS to consume them, e.g. ```ts const Box: any = require("../../../Styled/Box").default; @@ -160,10 +160,10 @@ or const BoxSpan: any = require("../../../Styled/Box").BoxSpan; ``` -- When rapididly prototyping a UI, you may find it quicker to do this in jsx - then tsxifying when you know what the final look is. You may want to consider - still having some typed benefits by using logic in TypeScript (either through - a wrapper `tsx`, or some `ts` helpers) to aid in the process. +- When rapididly prototyping a UI, you may find it quicker to do this in jsx + then tsxifying when you know what the final look is. You may want to consider + still having some typed benefits by using logic in TypeScript (either through + a wrapper `tsx`, or some `ts` helpers) to aid in the process. Components written in TypeScript will not need `PropTypes` defined on them, as type errors on props will be caught at compilation rather than a runtime check. diff --git a/doc/contributing/init-sources.md b/doc/contributing/init-sources.md index 0a88fadb0e0..12d35073605 100644 --- a/doc/contributing/init-sources.md +++ b/doc/contributing/init-sources.md @@ -8,13 +8,13 @@ See [Initialization file](../customizing/initialization-files.md) for JSON struc In order they are applied: -- URL to [Initialization file](../customizing/initialization-files.md) specified in [`initializationUrls` in Client-side config](../customizing/client-side-config.md#intializationurls) -- Init fragment paths, for example - - `#simple` - will be resolved using [`initFragmentPaths` in Client-side config](../customizing/client-side-config.md#parameters) - - `#https://some.url/config.json` -- Start data - `#start=ShareData` - - Note: uses [`ShareData`](../customizing/client-side-config.md#sharedata) format - which is slightly different from [Initialization file](../customizing/initialization-files.md) format - - See [`StartData` examples](#startdata-examples) +- URL to [Initialization file](../customizing/initialization-files.md) specified in [`initializationUrls` in Client-side config](../customizing/client-side-config.md#intializationurls) +- Init fragment paths, for example + - `#simple` - will be resolved using [`initFragmentPaths` in Client-side config](../customizing/client-side-config.md#parameters) + - `#https://some.url/config.json` +- Start data - `#start=ShareData` + - Note: uses [`ShareData`](../customizing/client-side-config.md#sharedata) format - which is slightly different from [Initialization file](../customizing/initialization-files.md) format + - See [`StartData` examples](#startdata-examples) Any number of `InitSources` can be specified @@ -24,24 +24,24 @@ When they are applied, some properties may overwrite each other - for example `w We have the following map URL -- `http://ci.terria.io/main/#https://some.url/config.json` +- `http://ci.terria.io/main/#https://some.url/config.json` Which loads `http://ci.terria.io/main` with the following [Client-side config](../customizing/client-side-config.md): -- `http://ci.terria.io/main/config.json` +- `http://ci.terria.io/main/config.json` The config has : -- `initializationUrls = ["simple"] ` -- `initFragmentPaths = undefined` (default is `["init/"]`) +- `initializationUrls = ["simple"] ` +- `initFragmentPaths = undefined` (default is `["init/"]`) So the init URL then resolves to: -- `http://ci.terria.io/main/init/simple.json` +- `http://ci.terria.io/main/init/simple.json` Then, as the URL has fragment path (`#https://some.url/config.json`), another `InitSource` is created: -- `https://some.url/config.json` +- `https://some.url/config.json` Terria will then load both `InitSources` in order: @@ -52,9 +52,9 @@ Terria will then load both `InitSources` in order: These are also treated as `InitSources` - but don't provide ability to set init JSON or URL to init JSON -- `#share=shareId` -- `/catalog/:id` route -- `/story/:shareId` route (same as `#share=shareId`, but will automatically start story) +- `#share=shareId` +- `/catalog/:id` route +- `/story/:shareId` route (same as `#share=shareId`, but will automatically start story) ### `StartData` examples @@ -64,8 +64,8 @@ Uses JSON: ```json { - "version": "8.0.0", - "initSources": ["https://some.url/config.json"] + "version": "8.0.0", + "initSources": ["https://some.url/config.json"] } ``` @@ -75,11 +75,11 @@ http://ci.terria.io/main/#start={%22version%22:%228.0.0%22,%22initSources%22:[{% ```json { - "version": "8.0.0", - "initSources": [ - { - "catalog": [] - } - ] + "version": "8.0.0", + "initSources": [ + { + "catalog": [] + } + ] } ``` diff --git a/doc/contributing/merge-master-into-mobx.md b/doc/contributing/merge-master-into-mobx.md index 8f07444d810..c0d3d08bbdd 100644 --- a/doc/contributing/merge-master-into-mobx.md +++ b/doc/contributing/merge-master-into-mobx.md @@ -1,8 +1,8 @@ # Merging master (v7) into mobx (v8) -- Pull and checkout the latest mobx branch. -- Find the common ancestor between that and master: `git merge-base origin/master mobx` -- Open a comparison of all the changes in master since the common ancestor. You can do this on github by visiting e.g. https://github.com/TerriaJS/terriajs/compare/7f54929aa766e83b4608a527c5ec307bdff829b0...master (replace the commit hash with the one reported by git merge-base above). Don't merge any of the changes yet. -- `git checkout -b mobx-merge` -- `git merge origin/master` -- Resolve conflicts. The comparison you opened above may help, especially when a file was deleted into the mobx branch. You'll need to apply any relevant changes to the new (TypeScript) files in the mobx branch. +- Pull and checkout the latest mobx branch. +- Find the common ancestor between that and master: `git merge-base origin/master mobx` +- Open a comparison of all the changes in master since the common ancestor. You can do this on github by visiting e.g. https://github.com/TerriaJS/terriajs/compare/7f54929aa766e83b4608a527c5ec307bdff829b0...master (replace the commit hash with the one reported by git merge-base above). Don't merge any of the changes yet. +- `git checkout -b mobx-merge` +- `git merge origin/master` +- Resolve conflicts. The comparison you opened above may help, especially when a file was deleted into the mobx branch. You'll need to apply any relevant changes to the new (TypeScript) files in the mobx branch. diff --git a/doc/contributing/migration-guide.md b/doc/contributing/migration-guide.md index a0ff1531cf1..55d89f09e23 100644 --- a/doc/contributing/migration-guide.md +++ b/doc/contributing/migration-guide.md @@ -6,13 +6,13 @@ A guide to upgrade a 7.x.x TerriaJS map to TerriaJS 8.0.0 and beyond. Please pos 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 +- 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. @@ -20,10 +20,10 @@ Reach out to us if you are using these, we only know about the things we have se 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 +- Your initialization files +- Custom basemaps or basemap thumbnails +- The TerriaMap code +- Other modifications you've done ### Upgrading initialization files using the catalog converter diff --git a/doc/contributing/model-layer.md b/doc/contributing/model-layer.md index a0d82dcff79..b0c489b8a36 100644 --- a/doc/contributing/model-layer.md +++ b/doc/contributing/model-layer.md @@ -8,10 +8,10 @@ It is also helpful to understand [what MobX reacts to](https://mobx.js.org/best/ ## Types of classes in the Model layer -- _Traits_: Define the configurable properties of a each stratum of a model object. Traits classes have no logic or behavior, only properties. Note that traits classes are often built by mixing in several sets of traits. Example: `WebMapServiceCatalogItemTraits`. -- _Models_: Concrete, usable model objects representing things like map items and groups in the catalog. They are composed of mix-ins plus some model-specific computed properties and logic. Example: `WebMapServiceCatalogItem`. -- _Mixins_: Provide computed properties and behavior intended to be mixed into model objects to add capabilities to them. Example: `GetCapabilitiesMixin`. -- _Load Strata_: (singular: Load Stratum) Strata that provide values for a subset of the properties defined on model's traits class, usually by loading them from an external source such as WMS GetCapabilities service. Example: `GetCapabilitiesStratum`. +- _Traits_: Define the configurable properties of a each stratum of a model object. Traits classes have no logic or behavior, only properties. Note that traits classes are often built by mixing in several sets of traits. Example: `WebMapServiceCatalogItemTraits`. +- _Models_: Concrete, usable model objects representing things like map items and groups in the catalog. They are composed of mix-ins plus some model-specific computed properties and logic. Example: `WebMapServiceCatalogItem`. +- _Mixins_: Provide computed properties and behavior intended to be mixed into model objects to add capabilities to them. Example: `GetCapabilitiesMixin`. +- _Load Strata_: (singular: Load Stratum) Strata that provide values for a subset of the properties defined on model's traits class, usually by loading them from an external source such as WMS GetCapabilities service. Example: `GetCapabilitiesStratum`. ## Reactivity @@ -33,8 +33,8 @@ A good rule of thumb is this: all properties should either be simple data proper Computed properties with setters should be avoided. In our _old_ architecture, we frequently used computed properties with a setter to model properties that are configurable by the user, but that have a default value computed from other properties when there is no user-specified value. In the current architecture, this is better modeled by: -- Defining the configurable property on the `Traits` class. -- Defining a computed property on the derived Model class that accesses `super.propertyName` (if mixins should be allowed to define the property) or `this.flattened.propertyName` (if only a directly-configured property value should be used) and, if that is undefined, computes and returns the default value from other properties. +- Defining the configurable property on the `Traits` class. +- Defining a computed property on the derived Model class that accesses `super.propertyName` (if mixins should be allowed to define the property) or `this.flattened.propertyName` (if only a directly-configured property value should be used) and, if that is undefined, computes and returns the default value from other properties. If a property does have a setter, it should obey these laws: @@ -80,8 +80,8 @@ In this scenario, consider whether you could instead let the reactive world take We want to keep the UI as small and simple as possible, because: -- The UI is the hardest part of TerriaJS to test with automated tests. If it has lots of complicated logic, we will need to spend a lot of time writing tests for it to ensure that it behaves correctly. A very simple UI is easier to test, and is perhaps so simple that automated tests for it are not needed at all. -- We would like everything that can be done by a user interacting with the UI to be doable programmatically as well. If the UI encodes complex rules or has its own states, this may not be possible, or doing so may require duplicating complicated "business logic" that already exists in the UI. +- The UI is the hardest part of TerriaJS to test with automated tests. If it has lots of complicated logic, we will need to spend a lot of time writing tests for it to ensure that it behaves correctly. A very simple UI is easier to test, and is perhaps so simple that automated tests for it are not needed at all. +- We would like everything that can be done by a user interacting with the UI to be doable programmatically as well. If the UI encodes complex rules or has its own states, this may not be possible, or doing so may require duplicating complicated "business logic" that already exists in the UI. Therefore, whenever possible, TerriaJS logic should be in the Model layer instead of in the UI. The UI should be a pure function from Model state to React components, and actions that simply execute functions or change a small number of properties in the Model layer. @@ -91,9 +91,9 @@ Evaluate observable properties as late as possible. In particular, avoid getting A few notes on defining properties in Model classes: -- _Set only traits_: All settable properties of a Model should be in its Traits. Because Traits are the only properties that are serialized/deserialized for catalog configuration and for sharing, settable properties that are not part of Traits prevent us from being able to completely recover application state. The only exception to this rule is for highly transient properties, such as whether a load from a remote source is currently in progress. -- _Covariance_: If you override a gettable property in a derived class, its type must be covariant with the base class type. That is, it is fine of the derived class property returns `string` while the base class property returns `string | undefined`. And it is fine if the derived class returns `Dog` while the base class returns `Animal`. But it is not ok if this relationship is reversed. You shouldn't really have any settable properties, but if you do, the types of such properties must be identical in base and derived classes. -- _Equals_: Pay attention to the comparer/equals to use with observables to determine if a new value is equal to an old one. The default `equals` is usually fine for primitive types (e.g. string, number, boolean), observable arrays, and objects whose properties are themselves observable (e.g. Traits). But for other types, especially Cesium types like JulianDate, Cartographic, and Cartesian3, it is essential to specify an `equals`. Typically this looks like this: `@computed({ equals: JulianDate.equals })`. +- _Set only traits_: All settable properties of a Model should be in its Traits. Because Traits are the only properties that are serialized/deserialized for catalog configuration and for sharing, settable properties that are not part of Traits prevent us from being able to completely recover application state. The only exception to this rule is for highly transient properties, such as whether a load from a remote source is currently in progress. +- _Covariance_: If you override a gettable property in a derived class, its type must be covariant with the base class type. That is, it is fine of the derived class property returns `string` while the base class property returns `string | undefined`. And it is fine if the derived class returns `Dog` while the base class returns `Animal`. But it is not ok if this relationship is reversed. You shouldn't really have any settable properties, but if you do, the types of such properties must be identical in base and derived classes. +- _Equals_: Pay attention to the comparer/equals to use with observables to determine if a new value is equal to an old one. The default `equals` is usually fine for primitive types (e.g. string, number, boolean), observable arrays, and objects whose properties are themselves observable (e.g. Traits). But for other types, especially Cesium types like JulianDate, Cartographic, and Cartesian3, it is essential to specify an `equals`. Typically this looks like this: `@computed({ equals: JulianDate.equals })`. ## `Traits` @@ -153,8 +153,8 @@ So, instead of trying to make a model change type upon load, `ReferenceMixin` cr There are two types of references -- Strong references -- Weak references +- Strong references +- Weak references ### Strong references @@ -162,12 +162,12 @@ These are a one-to-one mapping from a reference to it's target. The target can o #### Some rules -- The target model of a `ReferenceMixin` may be obtained from the `target` property, but it may be undefined until the promise returned by `loadReference` resolves. It may also be stale if a relevant trait of the reference has changed but `loadReference` hasn't yet been called or hasn't yet finished. -- For simplicity, a particular model may _only_ be the target of a single reference. Multiple references cannot point to the same target. The reference that points to a particular model may be obtained from the model's `sourceReference` property. -- The `uniqueId` of the `target` model must be the same as the `uniqueId` of the model with `ReferenceMixin`. -- The model with `ReferenceMixin` _may_ be in `terria.models`. -- The `target` model must _not_ be in `terria.models`. -- The instance referred to by the `target` property should remain stable (the same instance) whenever possible. But if something drastic changes (e.g. we need an instance of a different model class), it's possible for the `target` property to switch to pointing at an entirely new instance. So it's important to only hold on to references to the `ReferenceMixin` model and access the `target` as needed, rather than holding a reference to the `target` directly. +- The target model of a `ReferenceMixin` may be obtained from the `target` property, but it may be undefined until the promise returned by `loadReference` resolves. It may also be stale if a relevant trait of the reference has changed but `loadReference` hasn't yet been called or hasn't yet finished. +- For simplicity, a particular model may _only_ be the target of a single reference. Multiple references cannot point to the same target. The reference that points to a particular model may be obtained from the model's `sourceReference` property. +- The `uniqueId` of the `target` model must be the same as the `uniqueId` of the model with `ReferenceMixin`. +- The model with `ReferenceMixin` _may_ be in `terria.models`. +- The `target` model must _not_ be in `terria.models`. +- The instance referred to by the `target` property should remain stable (the same instance) whenever possible. But if something drastic changes (e.g. we need an instance of a different model class), it's possible for the `target` property to switch to pointing at an entirely new instance. So it's important to only hold on to references to the `ReferenceMixin` model and access the `target` as needed, rather than holding a reference to the `target` directly. ### Weak References @@ -194,18 +194,18 @@ This means that we can call `asyncLoader.load()` many times without worrying abo `forceLoadX()` shouldn't be called directly - instead you should use `asyncLoader.load()` method - for example in `CatalogMemberMixin` we have -- the abstract method `forceLoadMetadata` -- `loadMetadata()` which wraps `asyncLoader.load()` -- `loadMetadata()` can be called as many times as needed -- See [CatalogMemberMixin example](#CatalogMemberMixin-example) +- the abstract method `forceLoadMetadata` +- `loadMetadata()` which wraps `asyncLoader.load()` +- `loadMetadata()` can be called as many times as needed +- See [CatalogMemberMixin example](#CatalogMemberMixin-example) A **correct** example: ```ts async function forceLoadX() { - const url = this.someObservableUrl; - const someData = await loadText(url); - runInAction(() => (this.someOtherObservable = someData)); + const url = this.someObservableUrl; + const someData = await loadText(url); + runInAction(() => (this.someOtherObservable = someData)); } ``` @@ -219,9 +219,9 @@ An **incorrect** example: ```ts async function forceLoadX() { - const arg = this.someObservable; - const someData = someSynchronousFn(arg); - runInAction(() => (this.someOtherObservable = someData)); + const arg = this.someObservable; + const someData = someSynchronousFn(arg); + runInAction(() => (this.someOtherObservable = someData)); } ``` @@ -238,13 +238,13 @@ get newComputed { **Other tips**: -- You should not nest together `AsyncLoaders`. - Eg. - ```ts - async function forceLoadX() { - await this.forceLoadY(); - } - ``` +- You should not nest together `AsyncLoaders`. + Eg. + ```ts + async function forceLoadX() { + await this.forceLoadY(); + } + ``` For more info, see `lib\Core\AsyncLoader.ts` diff --git a/doc/contributing/result-object-and-error-handling.md b/doc/contributing/result-object-and-error-handling.md index d6ea68a0f2c..694f33fe45a 100644 --- a/doc/contributing/result-object-and-error-handling.md +++ b/doc/contributing/result-object-and-error-handling.md @@ -13,10 +13,10 @@ See `lib\Core\Result.ts` for more documentation. ```ts function someFn(someArg: boolean): Result { - if (someArg) { - return new Result("success"); - } - return new Result(undefined, TerriaError.from("SOME ERROR")); + if (someArg) { + return new Result("success"); + } + return new Result(undefined, TerriaError.from("SOME ERROR")); } ``` @@ -36,7 +36,7 @@ const value = someFn(false).ignoreError(); ```ts const value = someFn(someArg).catchError((error) => - doSomethingWithError(error) + doSomethingWithError(error) ); ``` @@ -66,18 +66,18 @@ This allows you to add more context to TerriaErrors. Valid `TerriaErrorOverrides` include: -- String values - eg `"Some error message"` -- JSON representation of `TerriaError` - eg `{"title": "Error title", "message": "Some error message"}` +- String values - eg `"Some error message"` +- JSON representation of `TerriaError` - eg `{"title": "Error title", "message": "Some error message"}` #### Simple usage ```ts function someFn(someArg): Result { - if (someArg) { - return new Result("success"); - } - // Here we create a TerriaError with message "Some Error inside result" - return new Result(undefined, TerriaError.from("Some error inside result")); + if (someArg) { + return new Result("success"); + } + // Here we create a TerriaError with message "Some Error inside result" + return new Result(undefined, TerriaError.from("Some error inside result")); } // Here we add `TerriaErrorOverrides` in throwIfError. @@ -125,10 +125,10 @@ See `lib\Core\TerriaError.ts` for more documentation. `TerriaErrorSeverity` enum values can be `Error` or `Warning`. -- Errors with severity `Error` are presented to the user. `Warning` will just be printed to console. -- By default, errors will use `Error` -- `TerriaErrorSeverity` will be copied through nested `TerriaErrors` on creation (eg if you call `TerriaError.from()` on a `Warning` then the parent error will also be `Warning`) -- Loading models from share links or stories will use `Warning` if the model is **not in the workbench**, otherwise it will use `Error`. +- Errors with severity `Error` are presented to the user. `Warning` will just be printed to console. +- By default, errors will use `Error` +- `TerriaErrorSeverity` will be copied through nested `TerriaErrors` on creation (eg if you call `TerriaError.from()` on a `Warning` then the parent error will also be `Warning`) +- Loading models from share links or stories will use `Warning` if the model is **not in the workbench**, otherwise it will use `Error`. #### Example of severity propagation @@ -136,8 +136,8 @@ Say we have this error with severity `Warning`: ```ts const error = { - message: "some message", - severity: TerriaErrorSeverity.Warning + message: "some message", + severity: TerriaErrorSeverity.Warning }; ``` diff --git a/doc/contributing/setting-up-saucelabs.md b/doc/contributing/setting-up-saucelabs.md index f93cf5f687e..9857a81881a 100644 --- a/doc/contributing/setting-up-saucelabs.md +++ b/doc/contributing/setting-up-saucelabs.md @@ -1,9 +1,9 @@ -- Get an account from [https://saucelabs.com/open-source](https://saucelabs.com/open-source). -- DON'T bother installing any tunnels or any of that nonsense that it tells you to do. This is actually automatically handled by sauce's npm module which is pretty sweet. -- Go to "My Account" in saucelabs (bottom left menu) and copy your access key (middle of the page roughly). -- Set env variables for SAUCE_USERNAME and SAUCE_ACCESS_KEY using your OS's method for doing that (`export` in bash) with your sauce username and the access key you just copied. -- Run `npm install -g karma-cli` Without this karma will sort-of work but give you confusing errors. -- Run `yarn start` in your `terriajs` dir in another terminal. -- Run `yarn gulp test-saucelabs` if you have a `karma-saucelabs.conf.js` file, or run `karma start` from the TerriaJS directory if you have a `karma.config.js` file. +- Get an account from [https://saucelabs.com/open-source](https://saucelabs.com/open-source). +- DON'T bother installing any tunnels or any of that nonsense that it tells you to do. This is actually automatically handled by sauce's npm module which is pretty sweet. +- Go to "My Account" in saucelabs (bottom left menu) and copy your access key (middle of the page roughly). +- Set env variables for SAUCE_USERNAME and SAUCE_ACCESS_KEY using your OS's method for doing that (`export` in bash) with your sauce username and the access key you just copied. +- Run `npm install -g karma-cli` Without this karma will sort-of work but give you confusing errors. +- Run `yarn start` in your `terriajs` dir in another terminal. +- Run `yarn gulp test-saucelabs` if you have a `karma-saucelabs.conf.js` file, or run `karma start` from the TerriaJS directory if you have a `karma.config.js` file. If you want to narrow down the browsers being run (i.e. only run IE9), you can remove them from `karma[-saucelabs].config.js` under `browsers`. diff --git a/doc/contributing/strata-examples.md b/doc/contributing/strata-examples.md index c5052c10247..27865e08fe6 100644 --- a/doc/contributing/strata-examples.md +++ b/doc/contributing/strata-examples.md @@ -4,36 +4,36 @@ **Bold** items are not `CommonStrata` -- Defaults - - `default` - - **`magda-record`** -- Loadable - - **`getCapabilities`** -- Definition - - `underride` - - `definition` - - `override` -- User - - `user` +- Defaults + - `default` + - **`magda-record`** +- Loadable + - **`getCapabilities`** +- Definition + - `underride` + - `definition` + - `override` +- User + - `user` ### Example Magda record ```json { - "aspects": { - "terria": { - "definition": { - "url": "some-wms-server.com/layer" - }, - "underride": { - "name": "A WMS layer name that has been updated by Magda Minion" - }, - "id": "wms-layer-id", - "type": "wms" - } - }, - "id": "wms-layer-id", - "name": "WMS layer name in Magda" + "aspects": { + "terria": { + "definition": { + "url": "some-wms-server.com/layer" + }, + "underride": { + "name": "A WMS layer name that has been updated by Magda Minion" + }, + "id": "wms-layer-id", + "type": "wms" + } + }, + "id": "wms-layer-id", + "name": "WMS layer name in Magda" } ``` @@ -51,7 +51,7 @@ Will contain properties loaded from WMS `GetCapabilities` request. For example: ```json { - "name": "A WMS layer name provided by WMS GetCapabilities" + "name": "A WMS layer name provided by WMS GetCapabilities" } ``` @@ -63,7 +63,7 @@ In provided example, this would be: ```json { - "name": "A WMS layer name that has been updated by Magda Minion" + "name": "A WMS layer name that has been updated by Magda Minion" } ``` @@ -75,7 +75,7 @@ In provided example, this would be: ```json { - "url": "some-wms-server.com/layer" + "url": "some-wms-server.com/layer" } ``` @@ -83,7 +83,7 @@ In provided example, this would be: ```json { - "name": "A WMS layer name that has been updated by Magda Minion", - "url": "some-wms-server.com/layer" + "name": "A WMS layer name that has been updated by Magda Minion", + "url": "some-wms-server.com/layer" } ``` diff --git a/doc/contributing/traits-in-depth.md b/doc/contributing/traits-in-depth.md index 61351839b2c..a5ddeb595e7 100644 --- a/doc/contributing/traits-in-depth.md +++ b/doc/contributing/traits-in-depth.md @@ -19,10 +19,10 @@ Stratums are how Terria determines which value a Trait should resolve to. There are 4 strata types -- Defaults -- Loadable -- Definition -- User +- Defaults +- Loadable +- Definition +- User Each type can have multiple strata - see [`StratumOrder.ts`](/lib/Models/Definition/StratumOrder.ts) @@ -30,14 +30,14 @@ Each type can have multiple strata - see [`StratumOrder.ts`](/lib/Models/Definit There are 5 common strata - these exist for every model -- Defaults - - `default` -- Definition - - `underride` - - `definition` - - `override` -- User - - `user` +- Defaults + - `default` +- Definition + - `underride` + - `definition` + - `override` +- User + - `user` ### Defaults `defaults` @@ -60,8 +60,8 @@ These should only be used in Trait definitions. Some example usages of `underride` -- Copying `itemPropertiesByIds`, `itemPropertiesByType`, `itemProperties`, to nested groups or nested references - that is, when a group or reference is loaded, if there are nested groups or nested reference - they will get the parent `itemProperties*` set in their `underride` stratum -- Setting `isExperiencingIssues = true` for models which have configuration issues +- Copying `itemPropertiesByIds`, `itemPropertiesByType`, `itemProperties`, to nested groups or nested references - that is, when a group or reference is loaded, if there are nested groups or nested reference - they will get the parent `itemProperties*` set in their `underride` stratum +- Setting `isExperiencingIssues = true` for models which have configuration issues ### Definition `definition` @@ -96,8 +96,8 @@ Values for models created programmatically by dynamic groups - for example `WebM Some use cases: -- To override invalid `definition` values -- Apply `itemProperties` to a model +- To override invalid `definition` values +- Apply `itemProperties` to a model ### User `user` diff --git a/doc/contributing/translation-guide-dev.md b/doc/contributing/translation-guide-dev.md index 017b5eb8158..630f1e9f0a8 100644 --- a/doc/contributing/translation-guide-dev.md +++ b/doc/contributing/translation-guide-dev.md @@ -17,10 +17,10 @@ import React from "react"; import { useTranslation } from "react-i18next"; export function MyComponent() { - const { t, i18n } = useTranslation(); - // or const [t, i18n] = useTranslation(); + const { t, i18n } = useTranslation(); + // or const [t, i18n] = useTranslation(); - return

{t("key")}

; //returns corresponding translated text from translation files + return

{t("key")}

; //returns corresponding translated text from translation files } ``` @@ -37,7 +37,7 @@ import React from "react"; import { withTranslation } from "react-i18next"; function MyComponent({ t, i18n }) { - return

{t("my translated text")}

; + return

{t("my translated text")}

; } export default withTranslation()(MyComponent); @@ -56,13 +56,13 @@ import React from "react"; import { Trans, useTranslation } from "react-i18next"; function MyComponent() { - const { t } = useTranslation("myNamespace"); + const { t } = useTranslation("myNamespace"); - return ( - - Hello World - - ); + return ( + + Hello World + + ); } ``` @@ -76,7 +76,7 @@ Use dynamic values in translations. ```json { - "key": "{{what}} is {{how}}" + "key": "{{what}} is {{how}}" } ``` @@ -99,10 +99,10 @@ i18next features automatic recognition of singular and plural forms. ```json { - "key": "item", - "key_plural": "items", - "keyWithCount": "{{count}} item", - "keyWithCount_plural": "{{count}} items" + "key": "item", + "key_plural": "items", + "keyWithCount": "{{count}} item", + "keyWithCount_plural": "{{count}} items" } ``` @@ -129,9 +129,9 @@ Nesting allows you to reference other keys in a translation. ```json { - "nesting1": "1 $t(nesting2)", - "nesting2": "2 $t(nesting3)", - "nesting3": "3" + "nesting1": "1 $t(nesting2)", + "nesting2": "2 $t(nesting3)", + "nesting3": "3" } ``` @@ -151,9 +151,9 @@ By providing a context you can differ translations. ```json { - "friend": "A friend", - "friend_male": "A boyfriend", - "friend_female": "A girlfriend" + "friend": "A friend", + "friend_male": "A boyfriend", + "friend_female": "A girlfriend" } ``` @@ -169,4 +169,4 @@ See the [react-i18next context documentation](https://www.i18next.com/translatio ## Future work -- Support internationalization of catalog content. +- Support internationalization of catalog content. diff --git a/doc/customizing/README.md b/doc/customizing/README.md index 28ec724c772..71312f664b2 100644 --- a/doc/customizing/README.md +++ b/doc/customizing/README.md @@ -2,8 +2,8 @@ TerriaJS can be extensively customized, often without writing any code. The cata This section explains the various ways to customize a TerriaJS application. It assumes you have already completed the [Getting Started](../getting-started.md) section and have a working Terria Map. -- [Client-side Config](client-side-config.md): Configure which catalog (init) files to load, the application name and support email address, the branding at the top of the application, disclaimers, keys for Bing Maps and Google Analytics, and more. -- [Initialization Files](initialization-files.md): TerriaJS init files describe the catalog that will be presented to the user, the initial map view, and more. Init files let you connect TerriaJS to your servers and data. -- [Server-side Config](server-side-config.md): Configure which domains the server will proxy for (to avoid [Cross-Origin Resource Sharing (CORS) problems](../connecting-to-data/cross-origin-resource-sharing.md)), persistence of sharing data, and more. -- [Skinning](skinning.md): Customize the look and feel of a TerriaJS application. -- [Cloning and Building](cloning-and-building.md): Build TerriaMap locally to customize your application further +- [Client-side Config](client-side-config.md): Configure which catalog (init) files to load, the application name and support email address, the branding at the top of the application, disclaimers, keys for Bing Maps and Google Analytics, and more. +- [Initialization Files](initialization-files.md): TerriaJS init files describe the catalog that will be presented to the user, the initial map view, and more. Init files let you connect TerriaJS to your servers and data. +- [Server-side Config](server-side-config.md): Configure which domains the server will proxy for (to avoid [Cross-Origin Resource Sharing (CORS) problems](../connecting-to-data/cross-origin-resource-sharing.md)), persistence of sharing data, and more. +- [Skinning](skinning.md): Customize the look and feel of a TerriaJS application. +- [Cloning and Building](cloning-and-building.md): Build TerriaMap locally to customize your application further diff --git a/doc/customizing/client-side-config.md b/doc/customizing/client-side-config.md index d4d137d7cdc..d104a076c4d 100644 --- a/doc/customizing/client-side-config.md +++ b/doc/customizing/client-side-config.md @@ -45,10 +45,10 @@ Note: relative paths will be resolved to the base URL of client-side config URL 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` +- 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` @@ -189,22 +189,22 @@ Configuration of items to appear in the search bar ```json { - "enabled": true, - "debug": false, - "react": { - "useSuspense": false - }, - "languages": { - "en": "english", - "de": "deutsch" - }, - "fallbackLanguage": "en", - "changeLanguageOnStartWhen": [ - "querystring", - "localStorage", - "navigator", - "htmlTag" - ] + "enabled": true, + "debug": false, + "react": { + "useSuspense": false + }, + "languages": { + "en": "english", + "de": "deutsch" + }, + "fallbackLanguage": "en", + "changeLanguageOnStartWhen": [ + "querystring", + "localStorage", + "navigator", + "htmlTag" + ] } ``` @@ -223,10 +223,10 @@ Configuration of maps to appear in "Related Maps" menu panel ```json { - "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." + "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." } ``` @@ -238,14 +238,14 @@ Credits/Attribution shown at the bottom of the map. Supports internationalizatio ```json [ - { - "text": "map.extraCreditLinks.dataAttribution", - "url": "about.html#data-attribution" - }, - { - "text": "map.extraCreditLinks.disclaimer", - "url": "about.html#disclaimer" - } + { + "text": "map.extraCreditLinks.dataAttribution", + "url": "about.html#data-attribution" + }, + { + "text": "map.extraCreditLinks.disclaimer", + "url": "about.html#disclaimer" + } ] ``` diff --git a/doc/customizing/cloning-and-building.md b/doc/customizing/cloning-and-building.md index a80078559dd..88d964e29da 100644 --- a/doc/customizing/cloning-and-building.md +++ b/doc/customizing/cloning-and-building.md @@ -20,10 +20,10 @@ If you run into trouble or want more explanation, read on. TerriaJS can be built and run on almost any macOS, Linux, or Windows system. The following are required to build TerriaJS: -- The Bash command shell. On macOS or Linux you almost certainly already have this. On Windows, you can easily get it by installing [Git for Windows](https://gitforwindows.org/). In the instructions below, we assume you're using a Bash command prompt. -- [Node.js](https://nodejs.org) v16.0. You can check your node version by running `node --version` on the command-line. -- [npm](https://www.npmjs.com/) v8.0. npm is usually installed automatically alongside the above. You can check your npm version by running `npm --version`. -- [yarn](https://yarnpkg.com/) v1.19.0 or later. This can be installed using `npm install -g yarn@^1.19.0` +- The Bash command shell. On macOS or Linux you almost certainly already have this. On Windows, you can easily get it by installing [Git for Windows](https://gitforwindows.org/). In the instructions below, we assume you're using a Bash command prompt. +- [Node.js](https://nodejs.org) v16.0. You can check your node version by running `node --version` on the command-line. +- [npm](https://www.npmjs.com/) v8.0. npm is usually installed automatically alongside the above. You can check your npm version by running `npm --version`. +- [yarn](https://yarnpkg.com/) v1.19.0 or later. This can be installed using `npm install -g yarn@^1.19.0` ### Cloning TerriaMap diff --git a/doc/customizing/initialization-files.md b/doc/customizing/initialization-files.md index abc8a3b014c..c4599423ec3 100644 --- a/doc/customizing/initialization-files.md +++ b/doc/customizing/initialization-files.md @@ -42,12 +42,12 @@ An init file is a [JSON file](https://en.wikipedia.org/wiki/JSON) with this basi Key points: -- `catalog` is an array. -- Every element of that array must have a `type` (corresponding to a value recognised by TerriaJS) and a `name`. -- The three major categories of catalog member types are: - - [Catalog Group](../connecting-to-data/catalog-groups.md): A group (folder) of items. Different group types allow the contents to be manually specified or to be automatically determined by querying various types of server. - - [Catalog Item](../connecting-to-data/catalog-items.md): Actual geospatial or chart data from a file or service, in various formats. - - [(Docs not yet available) Catalog Function](../connecting-to-data/catalog-functions.md): A parameterized service, such as a Web Processing Service (WPS). The user supplies the parameters and gets back some result. +- `catalog` is an array. +- Every element of that array must have a `type` (corresponding to a value recognised by TerriaJS) and a `name`. +- The three major categories of catalog member types are: + - [Catalog Group](../connecting-to-data/catalog-groups.md): A group (folder) of items. Different group types allow the contents to be manually specified or to be automatically determined by querying various types of server. + - [Catalog Item](../connecting-to-data/catalog-items.md): Actual geospatial or chart data from a file or service, in various formats. + - [(Docs not yet available) Catalog Function](../connecting-to-data/catalog-functions.md): A parameterized service, such as a Web Processing Service (WPS). The user supplies the parameters and gets back some result. Most of the other properties of each layer depend on the specific type. See the links above for details of each type. diff --git a/doc/customizing/search-providers.md b/doc/customizing/search-providers.md index 3549953db5f..69a8b33b4a4 100644 --- a/doc/customizing/search-providers.md +++ b/doc/customizing/search-providers.md @@ -28,35 +28,35 @@ The [flexsearch](https://github.com/nextapps-de/flexsearch) library is used to i To generate the catalog index: -- `yarn build-tools` -- `node ./build/generateCatalogIndex.js -c config-url -b base-url` where +- `yarn build-tools` +- `node ./build/generateCatalogIndex.js -c config-url -b base-url` where - - `config-url` is URL to client-side-config file - - `base-url` is URL to terriajs-server (this is used to load `server-config` and to proxy requests) - - For example `node ./build/generateCatalogIndex.js -c http://localhost:3001/config.json -b http://localhost:3001/` + - `config-url` is URL to client-side-config file + - `base-url` is URL to terriajs-server (this is used to load `server-config` and to proxy requests) + - For example `node ./build/generateCatalogIndex.js -c http://localhost:3001/config.json -b http://localhost:3001/` -- This will output three files - - `catalog-index.json` - - `catalog-index-errors.json` with any error messages which occurred while loading catalog members - - `catalog-index-errors-stack.json` with errors stack -- Set `catalogIndexUrl` config parameter to URL to `catalog-index.json` +- This will output three files + - `catalog-index.json` + - `catalog-index-errors.json` with any error messages which occurred while loading catalog members + - `catalog-index-errors-stack.json` with errors stack +- Set `catalogIndexUrl` config parameter to URL to `catalog-index.json` This file will have to be re-generated manually every time the catalog structure changes - for example: -- if items are renamed, or moved -- dynamic groups are updated (for example, WMS server publishes new layers) +- if items are renamed, or moved +- dynamic groups are updated (for example, WMS server publishes new layers) For more details see [/buildprocess/generateCatalogIndex.ts](/buildprocess/generateCatalogIndex.ts) -- Run `node ./build/generateCatalogIndex.js --help` for argument documentation +- Run `node ./build/generateCatalogIndex.js --help` for argument documentation ## Location search providers Location search providers are used to search for locations on the map. TerriaJS currently supports two implementations of search providers: -- [`BingMapsSearchProvider`](#bingmapssearchprovider) - implementation which in background uses Bing Map search API -- [`CesiumIonSearchProvider`](#cesiumionsearchprovider) - implementation which in background use CesiumIon geocoding API -- [`AustralianGazetteerSearchProvider`](#australiangazetteersearchprovider) - uses `WebFeatureServiceSearchProvider` +- [`BingMapsSearchProvider`](#bingmapssearchprovider) - implementation which in background uses Bing Map search API +- [`CesiumIonSearchProvider`](#cesiumionsearchprovider) - implementation which in background use CesiumIon geocoding API +- [`AustralianGazetteerSearchProvider`](#australiangazetteersearchprovider) - uses `WebFeatureServiceSearchProvider` Each `LocationSearchProvider support following confing options @@ -138,16 +138,16 @@ It can be configured using following options ```json { - "id": "search-provider/australian-gazetteer", - "type": "australian-gazetteer-search-provider", - "name": "translate#viewModels.searchPlaceNames", - "url": "http://services.ga.gov.au/gis/services/Australian_Gazetteer/MapServer/WFSServer", - "searchPropertyName": "Australian_Gazetteer:NameU", - "searchPropertyTypeName": "Australian_Gazetteer:Gazetteer_of_Australia", - "flightDurationSeconds": 1.5, - "minCharacters": 3, - "recommendedListLength": 3, - "isOpen": false + "id": "search-provider/australian-gazetteer", + "type": "australian-gazetteer-search-provider", + "name": "translate#viewModels.searchPlaceNames", + "url": "http://services.ga.gov.au/gis/services/Australian_Gazetteer/MapServer/WFSServer", + "searchPropertyName": "Australian_Gazetteer:NameU", + "searchPropertyTypeName": "Australian_Gazetteer:Gazetteer_of_Australia", + "flightDurationSeconds": 1.5, + "minCharacters": 3, + "recommendedListLength": 3, + "isOpen": false } ``` @@ -167,11 +167,11 @@ It can be configured using following options ```json { - "id": "search-provider/nominatim", - "type": "nominatim-search-provider", - "name": "Nominatim", - "flightDurationSeconds": 2, - "minCharacters": 3 + "id": "search-provider/nominatim", + "type": "nominatim-search-provider", + "name": "Nominatim", + "flightDurationSeconds": 2, + "minCharacters": 3 } ``` @@ -179,7 +179,7 @@ It can be configured using following options Implementing new location search provider is similar to implementing new `CatalogItems` and `CatalogGroups`. Each of them should be based on the usage of one of the mixins -- `LocationSearchProviderMixin` - should be used for API based location search providers. Example of such search provider is `BingMapSearchProvider`. -- `WebFeatureServiceSearchProviderMixin` - should be used for location search providers that will rely on data provided by `WebFeatureService`. Example of such search provider is `AustralianGazetteerSearchProvider`. +- `LocationSearchProviderMixin` - should be used for API based location search providers. Example of such search provider is `BingMapSearchProvider`. +- `WebFeatureServiceSearchProviderMixin` - should be used for location search providers that will rely on data provided by `WebFeatureService`. Example of such search provider is `AustralianGazetteerSearchProvider`. Each new `SearchProvider` should be registered inside `registerSearchProvider` so they can be properly upserted from json definition provider in config file. diff --git a/doc/customizing/skinning.md b/doc/customizing/skinning.md index 6a80198e1f1..8696db0e334 100644 --- a/doc/customizing/skinning.md +++ b/doc/customizing/skinning.md @@ -33,33 +33,30 @@ import StandardUserInterface from "terriajs/lib/ReactViews/StandardUserInterface import MenuItem from "terriajs/lib/ReactViews/StandardUserInterface/customizable/MenuItem"; import RelatedMaps from "./RelatedMaps"; import { - Menu, - Nav + Menu, + Nav } from "terriajs/lib/ReactViews/StandardUserInterface/customizable/Groups"; import MeasureTool from "terriajs/lib/ReactViews/Map/Navigation/MeasureTool"; import "./global.scss"; export default function UserInterface(props) { - return ( - - - - - - - - - ); + return ( + + + + + + + + + ); } ``` diff --git a/doc/customizing/translation-guide.md b/doc/customizing/translation-guide.md index 5e8ba15aa38..df0f5640887 100644 --- a/doc/customizing/translation-guide.md +++ b/doc/customizing/translation-guide.md @@ -11,8 +11,8 @@ If you are an advanced user or expert, we recommend reading the short and concis The following i18next plugins are used: -- [i18next-browser-languagedetector](https://github.com/i18next/i18next-browser-languageDetector) to detect the browser language, use the localStorage and react to URL query -- [i18next-http-backend](https://github.com/i18next/i18next-http-backend) to enable loading translations from editable language files +- [i18next-browser-languagedetector](https://github.com/i18next/i18next-browser-languageDetector) to detect the browser language, use the localStorage and react to URL query +- [i18next-http-backend](https://github.com/i18next/i18next-http-backend) to enable loading translations from editable language files ### Languages @@ -58,14 +58,14 @@ The translation key must be prefixed with `"translate#"`, so the structure of th ```json { - "help": { - "gettingstarted": { - "title": "Getting started with the map", - "content": "", - "video": "https://...", - "image": "https://..." - } + "help": { + "gettingstarted": { + "title": "Getting started with the map", + "content": "", + "video": "https://...", + "image": "https://..." } + } } ``` diff --git a/doc/deploying/README.md b/doc/deploying/README.md index 409776e2d1b..8319a7df2c6 100644 --- a/doc/deploying/README.md +++ b/doc/deploying/README.md @@ -4,19 +4,19 @@ The simplest way to deploy a production ready TerriaMap is to use a cloud provid Deploying TerriaMap itself: -- [Deploying with Kubernetes](deploying-with-kubernetes.md): Deploy TerriaMap using [Docker](https://www.docker.com/) and [Kubernetes](https://kubernetes.io/). -- [Deploying TerriaMap](deploying-terriamap.md): General instructions for deploying TerriaMap in almost any environment. +- [Deploying with Kubernetes](deploying-with-kubernetes.md): Deploy TerriaMap using [Docker](https://www.docker.com/) and [Kubernetes](https://kubernetes.io/). +- [Deploying TerriaMap](deploying-terriamap.md): General instructions for deploying TerriaMap in almost any environment. Deploying other services for use with TerriaJS: -- [Setting Up a Region Mapping Server](setting-up-a-region-mapping-server.md): Set up a server for use with TerriaJS's region mapping feature. -- [Setting Up Geoserver](setting-up-geoserver.md): Configure [GeoServer](http://geoserver.org/) for effective use with TerriaJS. +- [Setting Up a Region Mapping Server](setting-up-a-region-mapping-server.md): Set up a server for use with TerriaJS's region mapping feature. +- [Setting Up Geoserver](setting-up-geoserver.md): Configure [GeoServer](http://geoserver.org/) for effective use with TerriaJS. Using a TerriaMap in other applications: -- [Controlling with URL Parameters](controlling-with-url-parameters.md): Control a TerriaJS application by passing it URL parameters. This is powerful because it enables another site to launch or embed a customized map with little or no code to write. -- [Controlling in an <iframe> or Popup](controlling-in-an-iframe-or-popup.md): Embed a TerriaJS application in iframe or pop it up in a separate window, and control it by posting it cross-window messages. +- [Controlling with URL Parameters](controlling-with-url-parameters.md): Control a TerriaJS application by passing it URL parameters. This is powerful because it enables another site to launch or embed a customized map with little or no code to write. +- [Controlling in an <iframe> or Popup](controlling-in-an-iframe-or-popup.md): Embed a TerriaJS application in iframe or pop it up in a separate window, and control it by posting it cross-window messages. Special deployment configurations: -- [Running TerriaMap through a reverse proxy](running-through-reverse-proxy.md): How to configure Terria to work correctly when running through a reverse proxy that performs path rewriting to prefix a path to URLs. E.g. hosting a map to be accessed at http://example.com/my/terriamap/ +- [Running TerriaMap through a reverse proxy](running-through-reverse-proxy.md): How to configure Terria to work correctly when running through a reverse proxy that performs path rewriting to prefix a path to URLs. E.g. hosting a map to be accessed at http://example.com/my/terriamap/ diff --git a/doc/deploying/controlling-in-an-iframe-or-popup.md b/doc/deploying/controlling-in-an-iframe-or-popup.md index 5f908996648..337fb3fa1ae 100644 --- a/doc/deploying/controlling-in-an-iframe-or-popup.md +++ b/doc/deploying/controlling-in-an-iframe-or-popup.md @@ -11,61 +11,60 @@ Then, the parent window can send messages like this: ```html - - - NationalMap Embed Test - + + + NationalMap Embed Test + - - + + - - + ] + }, + "https://nationalmap.gov.au" + ); + } + }); + + ``` diff --git a/doc/deploying/controlling-with-url-parameters.md b/doc/deploying/controlling-with-url-parameters.md index ec3585a9569..8afc4d8765a 100644 --- a/doc/deploying/controlling-with-url-parameters.md +++ b/doc/deploying/controlling-with-url-parameters.md @@ -2,9 +2,9 @@ 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 +- 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) diff --git a/doc/deploying/deploying-terriamap.md b/doc/deploying/deploying-terriamap.md index e6089b7fa66..cf7e769ae75 100644 --- a/doc/deploying/deploying-terriamap.md +++ b/doc/deploying/deploying-terriamap.md @@ -16,9 +16,9 @@ The easiest way to deploy your TerriaMap is to use the included Node.js-based we Then, copy the following files and directories from your local system where you built TerriaMap onto the server: -- `wwwroot` -- `node_modules` (note: this can take a long time, be patient) -- `devserverconfig.json` but rename this to `productionserverconfig.json` (and add any private access keys/passwords/secrets) +- `wwwroot` +- `node_modules` (note: this can take a long time, be patient) +- `devserverconfig.json` but rename this to `productionserverconfig.json` (and add any private access keys/passwords/secrets) And on the server, change to the directory where you copied those files and directories and run: diff --git a/doc/deploying/deploying-with-kubernetes.md b/doc/deploying/deploying-with-kubernetes.md index 6fb5ebb56a3..ca17da7df28 100644 --- a/doc/deploying/deploying-with-kubernetes.md +++ b/doc/deploying/deploying-with-kubernetes.md @@ -16,23 +16,23 @@ E.g. ```yaml global: - rollingUpdate: - maxUnavailable: 1 - image: - tag: "0.0.6" + rollingUpdate: + maxUnavailable: 1 + image: + tag: "0.0.6" terriamap: - clientConfig: - parameters: - disclaimer: - text: "This is a disclaimer" - serverConfig: - port: 8080 - initConfig: - camera: - north: "1" - east: "2" - south: "3" - west: "4" + clientConfig: + parameters: + disclaimer: + text: "This is a disclaimer" + serverConfig: + port: 8080 + initConfig: + camera: + north: "1" + east: "2" + south: "3" + west: "4" ``` # Building Your Own Image @@ -47,8 +47,8 @@ docker build -t app-name:tag . If you want to run a local version of TerriaMap using Kubernetes then you can try one of these applications: -- [Docker Desktop](https://www.docker.com/products/docker-desktop/): Application with embedded Kubernetes setup for fast and easy app development, [requiring a subscription licence](https://docs.docker.com/subscription/desktop-license/) in most cases for commercial use -- [Rancher Desktop](https://rancherdesktop.io/): Apache-2.0 alternative to Docker Desktop +- [Docker Desktop](https://www.docker.com/products/docker-desktop/): Application with embedded Kubernetes setup for fast and easy app development, [requiring a subscription licence](https://docs.docker.com/subscription/desktop-license/) in most cases for commercial use +- [Rancher Desktop](https://rancherdesktop.io/): Apache-2.0 alternative to Docker Desktop Or try a tool recommended in the [official Kuberntes setup documentation](https://kubernetes.io/docs/setup/). diff --git a/doc/deploying/deprecated-wms-region-mapping.md b/doc/deploying/deprecated-wms-region-mapping.md index 1c0d49acd51..2fba69b96fd 100644 --- a/doc/deploying/deprecated-wms-region-mapping.md +++ b/doc/deploying/deprecated-wms-region-mapping.md @@ -8,17 +8,17 @@ _Region mapping_ is the process of matching a value in a CSV file to a pre-defin ## Prepare the shapefiles -- One shapefile should contain all the polygons. -- There should be a `FID` (case-sensitive) attribute, numbering each polygon starting from 0. If no FID attribute is present, use ogr2ogr to add it: +- One shapefile should contain all the polygons. +- There should be a `FID` (case-sensitive) attribute, numbering each polygon starting from 0. If no FID attribute is present, use ogr2ogr to add it: - `ogr2ogr -f "ESRI Shapefile" precincts-fid.shp precincts.shp -sql 'select FID,* from precincts'` + `ogr2ogr -f "ESRI Shapefile" precincts-fid.shp precincts.shp -sql 'select FID,* from precincts'` - If you have several files to process, use a line like this: + If you have several files to process, use a line like this: - `for i in GCCSA IARE ILOC IREG SOS SOSR SUA UCL; do ogr2ogr -f "ESRI Shapefile" ${i}_2011_AUST_fid.shp ${i}_2011_AUST.shp -sql 'select FID,* from '"${i}_2011_AUST"; done` + `for i in GCCSA IARE ILOC IREG SOS SOSR SUA UCL; do ogr2ogr -f "ESRI Shapefile" ${i}_2011_AUST_fid.shp ${i}_2011_AUST.shp -sql 'select FID,* from '"${i}_2011_AUST"; done` -- There should be an attribute containing the identifiers you wish to match against (eg, for postcode boundaries, a `postcode` attribute containing the 4 digit codes themselves). -- The projection should be EPSG:4326 (unprojected lat/long on WGS84). +- There should be an attribute containing the identifiers you wish to match against (eg, for postcode boundaries, a `postcode` attribute containing the 4 digit codes themselves). +- The projection should be EPSG:4326 (unprojected lat/long on WGS84). ## Set up GeoServer @@ -34,9 +34,9 @@ _Region mapping_ is the process of matching a value in a CSV file to a pre-defin 7. Set these properties: -- Declared SRS: EPSG:4326 -- Click "Compute from data" and "Compute from native bounds" to set the bounding box. -- On the _Publishing_ page, set `region_fid` as the _Default Style_ +- Declared SRS: EPSG:4326 +- Click "Compute from data" and "Compute from native bounds" to set the bounding box. +- On the _Publishing_ page, set `region_fid` as the _Default Style_ ## Configure the regions in your TerriaJS-based map @@ -50,9 +50,9 @@ Modify `wwwroot/data/regionMapping.json`. Add a section like this: "description": "Statistical Area Level 4" }, -- `"SA4"`: this identifier does not serve any machine-readable purpose outside this file. -- `layerName`: the WMS layer of your new regions, including the workspace. -- `server`: the URL of your GeoServer, up to and including `/ows`. -- `regionProp`: the name of the attribute containing region identifiers that will be matched against (case-sensitive) -- `aliases`: alias of CSV column header names that will be recognised as matching this kind of feature. Must be lowercase. -- `description`: May be used in GUI elements and error messages. +- `"SA4"`: this identifier does not serve any machine-readable purpose outside this file. +- `layerName`: the WMS layer of your new regions, including the workspace. +- `server`: the URL of your GeoServer, up to and including `/ows`. +- `regionProp`: the name of the attribute containing region identifiers that will be matched against (case-sensitive) +- `aliases`: alias of CSV column header names that will be recognised as matching this kind of feature. Must be lowercase. +- `description`: May be used in GUI elements and error messages. diff --git a/doc/deploying/running-through-reverse-proxy.md b/doc/deploying/running-through-reverse-proxy.md index 229a0612ff8..04e45c9d37f 100644 --- a/doc/deploying/running-through-reverse-proxy.md +++ b/doc/deploying/running-through-reverse-proxy.md @@ -8,9 +8,9 @@ yarn gulp release --baseHref="/my/terriamap/" This paramter can be passed to any `gulp` "build" task: -- `default` (this runs when you call `gulp` without a task) -- `build` -- `release` -- `watch` +- `default` (this runs when you call `gulp` without a task) +- `build` +- `release` +- `watch` _Note that Terria's server doesn't do any path rewriting. This must be used in conjunction with a reverse proxy which does the path rewriting (so that terriajs-server gets a request for `/index.html` when the browser requests `http://example.com/my/terriamap/index.html`)._ diff --git a/doc/deploying/using-as-a-ckan-previewer.md b/doc/deploying/using-as-a-ckan-previewer.md index f3ec3a4f86f..afd9b69912b 100644 --- a/doc/deploying/using-as-a-ckan-previewer.md +++ b/doc/deploying/using-as-a-ckan-previewer.md @@ -13,12 +13,12 @@ Follow the instructions in the CKAN documentation [here](http://docs.ckan.org/en Install a local instance of CKAN per http://docs.ckan.org/en/ckan-2.0/install-from-source.html Follow all the steps : -- In step 1 install openjdk-7-jdk instead of openjdk-6-jdk -- in step 2c use requirements.txt instead of pip-requirements.txt -- In step 3 making 'pass' your password will makes things simpler -- Set up the optional Solr install as per step 5 (Single Solr instance) -- Step 6 can take a long time. If it does fail drop the ckan_default database and redo step 3 and try again -- You do no need to set up the optional DataStore install as per step 7 +- In step 1 install openjdk-7-jdk instead of openjdk-6-jdk +- in step 2c use requirements.txt instead of pip-requirements.txt +- In step 3 making 'pass' your password will makes things simpler +- Set up the optional Solr install as per step 5 (Single Solr instance) +- Step 6 can take a long time. If it does fail drop the ckan_default database and redo step 3 and try again +- You do no need to set up the optional DataStore install as per step 7 To add local storage of files