Merge pull request #7207 from TerriaJS/model-dim-docs

Create model dimensions docs

CHANGES.md

@@ -4,9 +4,10 @@
 
 - TSify some `js` and `jsx` files and provide `.d.ts` ambient type files for a few others. This is so that running `tsc` on an external project that imports Terria code will typecheck successfully.
 - Upgraded a bunch of d3 dependencies for fixing security errors.
-- [The next improvement]
 - Show rectangle selector for WPS bounding box parameter
-- Fix `store` and `status` values send in WPS Execute request. 
+- Fix `store` and `status` values send in WPS Execute request.
+- Add docs for `modelDimensions`
+- [The next improvement]
 
 #### 8.7.4 - 2024-06-07
 

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"
+                            }
+                        }
+                    }
+                }
+            ]
+        }
+    ]
+}
+```
+
+<img src="../img/model-dim.jpeg">
+
+## 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.

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)

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: