diff --git a/CHANGES.md b/CHANGES.md index 706a302a46e..4e0215dd4e7 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -14,6 +14,7 @@ - Increase `maxRefreshIntervals` from 1000 to 10000 for `WebMapServiceCatalogItem` and `ArcGisMapServerCatalogItem`. - Add `nextDiscreteJulianDate` helper computed value to `DiscretelyTimeVaryingMixin` - Add `EPSG:7899` to `Proj4Definitions` +- Add docs for `modelDimensions` - [The next improvement] #### 8.7.4 - 2024-06-07 diff --git a/doc/connecting-to-data/customizing-data-appearance/img/model-dim.jpeg b/doc/connecting-to-data/customizing-data-appearance/img/model-dim.jpeg new file mode 100644 index 00000000000..d21ef6f4ae5 Binary files /dev/null and b/doc/connecting-to-data/customizing-data-appearance/img/model-dim.jpeg differ diff --git a/doc/connecting-to-data/customizing-data-appearance/model-dimensions.md b/doc/connecting-to-data/customizing-data-appearance/model-dimensions.md new file mode 100644 index 00000000000..b3df638c9d3 --- /dev/null +++ b/doc/connecting-to-data/customizing-data-appearance/model-dimensions.md @@ -0,0 +1,114 @@ +# Model Dimensions + +Model dimensions can be used to define dropdown menus in the workbench that update model JSON - think of it as a dropdown that patches the model JSON with a new value. This is useful for changing the appearance of a dataset, such as changing the colourMap for a CSV. + +## Basic example + +For example - this renders a new drop down called "Color" that changes the `colorPalette` trait - [test link](http://ci.terria.io/main/#clean&start={%22initSources%22%3A[{%22homeCamera%22%3A{%22north%22%3A-8%2C%22east%22%3A158%2C%22south%22%3A-45%2C%22west%22%3A109}%2C%22workbench%22%3A[%22test%22]%2C%22catalog%22%3A[{%22type%22%3A%22csv%22%2C%22url%22%3A%22test%2FNSW_LGA_NEXIS_201212.csv%22%2C%22name%22%3A%22NSWLGANEXIS2012%22%2C%22id%22%3A%22test%22%2C%22modelDimensions%22%3A[{%22id%22%3A%22cols%22%2C%22name%22%3A%22Color%22%2C%22selectedId%22%3A%22Red%22%2C%22options%22%3A[{%22id%22%3A%22Red%22%2C%22value%22%3A{%22defaultStyle%22%3A{%22color%22%3A{%22colorPalette%22%3A%22Reds%22}}}}%2C{%22id%22%3A%22Blue%22%2C%22value%22%3A{%22defaultStyle%22%3A{%22color%22%3A{%22colorPalette%22%3A%22Blues%22}}}}]}]}]}]}) + +```json +{ + "type": "csv", + "url": "test/NSW_LGA_NEXIS_201212.csv", + "name": "NSW LGA NEXIS 2012", + "modelDimensions": [ + { + "id": "cols", + "name": "Color", + "selectedId": "Red", + "options": [ + { + "id": "Red", + "value": { + "defaultStyle": { + "color": { + "colorPalette": "Reds" + } + } + } + }, + { + "id": "Blue", + "value": { + "defaultStyle": { + "color": { + "colorPalette": "Blues" + } + } + } + } + ] + } + ] +} +``` + + + +## Example with Mustache template + +Model dimensions also supports the use of [Mustache templates](https://mustache.github.io/) - this means you can refer to other parts of the model JSON in the value of the model dimension. For example, this changes the `colorPalette` trait based on the value of another trait `colorPalette2`: + +```json +{ + "type": "csv", + "url": "test/NSW_LGA_NEXIS_201212.csv", + "name": "NSW LGA NEXIS 2012", + "modelDimensions": [ + { + "id": "Cols", + "selectedId": "Red", + "options": [ + { + "id": "Red", + "value": { + "defaultStyle": { + "color": { + "colorPalette": "{{modelDimensions.0.selectedId}}" + } + } + } + }, + { + "id": "Blue", + "value": { + "defaultStyle": { + "color": { + "colorPalette": "{{modelDimensions.0.selectedId}}" + } + } + } + } + ] + } + ] +} +``` + +This is a silly example - but the template approach means you can have "interaction" between `modelDimensions` + +```json +{ + ..., + "modelDimensions": [ + { + "id": "some-dim", + "selectedId": "some-option", + "options": [ + { + "id": "some-option", + "value": { + "url": "https://example.com/{{modelDimensions.0.selectedId}}-and-{{modelDimensions.1.selectedId}}.geojson" + } + }, + ... + ] + } + ], + ... +} +``` + +## Default `selectedId` + +It is important to note that the `selectedId` does not apply/update the model JSON when the model is first loaded. So it is best to make sure that the `selectedId` matches your default model JSON. diff --git a/doc/connecting-to-data/customizing-data-appearance/overview.md b/doc/connecting-to-data/customizing-data-appearance/overview.md index ac7897c91fd..827ad2c03a3 100644 --- a/doc/connecting-to-data/customizing-data-appearance/overview.md +++ b/doc/connecting-to-data/customizing-data-appearance/overview.md @@ -15,3 +15,4 @@ This section explains how you can use such a file to improve the look of your da - [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/mkdocs.yml b/doc/mkdocs.yml index dfd28b71452..8319b66925f 100644 --- a/doc/mkdocs.yml +++ b/doc/mkdocs.yml @@ -31,6 +31,7 @@ nav: - Imagery Data: connecting-to-data/customizing-data-appearance/imagery-data.md - Tabular Data: connecting-to-data/customizing-data-appearance/tabular-data.md - Feature Information Template: connecting-to-data/customizing-data-appearance/feature-info-template.md + - Model Dimensions: connecting-to-data/customizing-data-appearance/model-dimensions.md - Catalog Functions: connecting-to-data/catalog-functions.md - Catalog References: connecting-to-data/catalog-references.md - Catalog Type Details: