|
| 1 | +# Customisation of Platform Content |
| 2 | + |
| 3 | +Given that the platform is designed to be generalisable, this directory exists to allow users to customise their web contents according to their needs. It acts as the target for a Docker volume or bind mount, and should be mounted to the `/twa/public` directory within the deployed container. Files within it can then be accessed using the `$HOST/...` URL route. |
| 4 | + |
| 5 | +The uploaded content provided by the deploying developer should match the directory structure below. Please read the respective sections for the specific instructions. |
| 6 | + |
| 7 | +- [`config/`](#1-configuration): Contains config/settings files. |
| 8 | +- [`images/`](#2-assets): Custom image files. |
| 9 | +- [`optional-pages/`](#3-optional-pages): Markdown files for optional static content (with metadata from [gray-matter](https://www.npmjs.com/package/gray-matter)). |
| 10 | +- [`style-overrides.css`](#4-styling-overrides): Optional CSS overrides. |
| 11 | + |
| 12 | +## 1. Configuration |
| 13 | + |
| 14 | +The platform requires the following [JSON](https://en.wikipedia.org/wiki/JSON) configuration files: |
| 15 | + |
| 16 | +- [`ui-settings.json`](#11-ui-settings): UI configuration settings; **[MANDATORY]**. |
| 17 | +- [`data.json`](#121-general-settings): Specifies data sources and layers to be mapped; **[OPTIONAL]** |
| 18 | +- [`map-settings.json`](#122-map-data-settings): Non-data specific configuration for maps; **[OPTIONAL]** |
| 19 | + |
| 20 | +### 1.1 UI Settings |
| 21 | + |
| 22 | +The `config/ui-settings.json` file provides general settings for the platform. This includes settings for displaying modules, branding requirements, and setting scenarios. A brief explanation is as follows: |
| 23 | + |
| 24 | +- `branding`: key value pairs for various branding icons such as navigation bar and logo |
| 25 | +- `modules`: key value pairs indicating if certain modules should be highlighted |
| 26 | + - `landing`: REQUIRED. Displays landing page if enabled |
| 27 | + - `map`: REQUIRED. Displays map visualisation if enabled |
| 28 | + - `dashboard`: REQUIRED. Displays dashboard if enabled |
| 29 | + - `help`: REQUIRED. Displays help page if enabled |
| 30 | +- `scenario`: optional key value pairs if you require scenario handling |
| 31 | + - `url`: endpoint to retrieve the scenarios and settings |
| 32 | + - `data`: target dataset that should be acccessible to the user |
| 33 | + |
| 34 | +Below is an example of the contents for a valid `ui-settings.json` file with additional comments explaining each entry. The format of the file should be consistent whether implementing mapbox or cesium maps. |
| 35 | + |
| 36 | +> [!NOTE] |
| 37 | +> The comments seen below are for explanation purposes only, they are not valid JSON. If wishing to use this content in production, remove the comments first. |
| 38 | +
|
| 39 | +```json |
| 40 | +{ |
| 41 | + "branding": { |
| 42 | + "logo": "/images/whatever.svg", // Custom branding logo |
| 43 | + "navbarLogo": "/images/defaults/navbar-logo.svg" // Custom logo for the navbar (should be 5:1 aspect ratio) |
| 44 | + }, |
| 45 | + "modules": { |
| 46 | + "landing": true, // Should the landing page be enabled |
| 47 | + "help": true, // Should the help page be enabled |
| 48 | + "map": true, // Should the map page be enabled |
| 49 | + "dashboard": true // Should the dashboard page be enabled |
| 50 | + } |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +### 1.2 Map Settings |
| 55 | + |
| 56 | +If the map module is enabled, developers will need to supply `data.json` and `map-settings.json` files. |
| 57 | + |
| 58 | +#### 1.2.1 General Settings |
| 59 | + |
| 60 | +The `config/map-settings.json` file provides general map settings that are not specific to the data sets being loaded. The specific settings are: |
| 61 | + |
| 62 | +- `type` : The map type. Either "mapbox" or "cesium" is currently accepted |
| 63 | +- `camera` : Camera starting position and available positions |
| 64 | +- `imagery` : Imagery options |
| 65 | +- `legend` : Optional custom legend settings |
| 66 | +- `icons` : A key-value map of the icon name and its corresponding url |
| 67 | + |
| 68 | +Please note that Cesium has not been incorporated at the moment. It is intended that this file (along with other configuration files) are provided by the deploying developer via Docker volumes created with the standard TWA Stack. As such, there may be no off-the-shelf example file committed to this repository. |
| 69 | + |
| 70 | +> Legend setting format |
| 71 | +
|
| 72 | +Icons on the map are shown by default in the layer tree. Additional legend items can be customised in this file. The current setup uses nested groups, where group names act as headers on the legend. At the moment, the available visualisation options for legends are only `icons` and `fills`. For other options, please send in a feature request. Sample settings are as follows: |
| 73 | + |
| 74 | +> [!NOTE] |
| 75 | +> The comments seen below are for explanation purposes only. They are not valid JSON and should be removed. |
| 76 | +```json |
| 77 | +{ |
| 78 | + "legend": { |
| 79 | + // Group one for icons - Only PNG, JPG, SVG, and Google Materials icon are available |
| 80 | + "Status Indicators": { |
| 81 | + // Group one, item one |
| 82 | + "Active": { |
| 83 | + "type": "symbol", |
| 84 | + "icon": "/images/active.svg" |
| 85 | + }, |
| 86 | + // Group one, item two |
| 87 | + "Inactive": { |
| 88 | + "type": "symbol", |
| 89 | + "icon": "/images/inactive.jpg" |
| 90 | + }, |
| 91 | + // Group one, item three |
| 92 | + "Unknown": { |
| 93 | + "type": "symbol", |
| 94 | + "icon": "question_mark" |
| 95 | + } |
| 96 | + }, |
| 97 | + // Group two for fills |
| 98 | + "Area of interest": { |
| 99 | + // Group two, item one |
| 100 | + "Primary": { |
| 101 | + "type": "fill", |
| 102 | + "fill": "#000000" |
| 103 | + }, |
| 104 | + // Group two, item two |
| 105 | + "Secondary": { |
| 106 | + "type": "fill", |
| 107 | + "fill": "#709ac7" |
| 108 | + } |
| 109 | + } |
| 110 | + } |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +Below is an example of the contents for a valid `map-settings.json` file for Mapbox with additional comments explaining each entry. The format of the file is mostly consistent for either mapbox or cesium maps. However, there are some differences, that will be explained when Cesium has been incorporated. |
| 115 | + |
| 116 | +> [!NOTE] |
| 117 | +> The comments seen below are for explanation purposes only, they are not valid JSON. If wishing to use this content in production, remove the comments first. |
| 118 | +
|
| 119 | +```json |
| 120 | +{ |
| 121 | + "type": "mapbox", // Required Type of map, "mapbox" or "cesium" |
| 122 | + "camera": { |
| 123 | + "default": "Paris", // Name of starting camera position |
| 124 | + "positions": [ |
| 125 | + // Selectable positions for the camera |
| 126 | + { |
| 127 | + "name": "London", |
| 128 | + "center": [-0.12794, 51.50774], |
| 129 | + "zoom": 18, |
| 130 | + "bearing": 0, |
| 131 | + "pitch": 45 |
| 132 | + }, |
| 133 | + { |
| 134 | + "name": "Paris", |
| 135 | + "center": [2.29448, 48.85826], |
| 136 | + "zoom": 16, |
| 137 | + "bearing": 0, |
| 138 | + "pitch": 45 |
| 139 | + }, |
| 140 | + { |
| 141 | + "name": "New York", |
| 142 | + "center": [-73.98568, 40.74845], |
| 143 | + "zoom": 16, |
| 144 | + "bearing": 0, |
| 145 | + "pitch": 45 |
| 146 | + } |
| 147 | + ] |
| 148 | + }, |
| 149 | + "imagery": { |
| 150 | + "default": "Auto", // Name of default map imagery, "auto" will inherit from browser theme |
| 151 | + "options": [ |
| 152 | + // Mapbox base layer options, using their Style URL system |
| 153 | + { |
| 154 | + "name": "Light", |
| 155 | + "url": "mapbox://styles/mapbox/light-v11?optimize=true" |
| 156 | + }, |
| 157 | + { |
| 158 | + "name": "Dark", |
| 159 | + "url": "mapbox://styles/mapbox/dark-v11?optimize=true" |
| 160 | + }, |
| 161 | + { |
| 162 | + "name": "Outdoors", |
| 163 | + "url": "mapbox://styles/mapbox/outdoors-v12?optimize=true" |
| 164 | + }, |
| 165 | + { |
| 166 | + "name": "Satellite", |
| 167 | + "url": "mapbox://styles/mapbox/satellite-streets-v12?optimize=true" |
| 168 | + }, |
| 169 | + { |
| 170 | + "name": "3D (Day)", |
| 171 | + "url": "mapbox://styles/mapbox/standard", |
| 172 | + "time": "dawn" |
| 173 | + }, |
| 174 | + { |
| 175 | + "name": "3D (Night)", |
| 176 | + "url": "mapbox://styles/mapbox/standard", |
| 177 | + "time": "dusk" |
| 178 | + } |
| 179 | + ] |
| 180 | + }, |
| 181 | + "icons": { |
| 182 | + // Mappings for the icon name that will be called in code and its corresponding url |
| 183 | + "info": "/images/defaults/icons/info.svg" |
| 184 | + } |
| 185 | +} |
| 186 | +``` |
| 187 | + |
| 188 | +#### 1.2.2 Map Data Settings |
| 189 | + |
| 190 | +The `config/data.json` file visualises data according to user requirements. Specifically, it is expected to specify the data sources (where and how the data is loaded) and data layers (how that data is visualised) within a hierarchal data group structure. |
| 191 | + |
| 192 | +##### Defining a group |
| 193 | + |
| 194 | +The `data.json` requires at least one defined data group. Each data group contains a number of parameters (detailed below), and can house multiple sub-groups to form a custom hierarchy. |
| 195 | + |
| 196 | +- `name` (required): This is the user facing name of the data group. |
| 197 | +- `stack` (optional): This is the URL for the stack containing metadata on this group's data. Note that this should be the base URL of the stack (i.e. without "/geoserver"). If missing, dynamic metadata from a remote FeatureInfoAgent cannot be utilised. This parameter can also be set with different values for different subgroups. |
| 198 | +- `sources` (optional): This is an array of objects defining data sources (see below for info on sources). |
| 199 | +- `layers` (optional): This is an array of objects defining data layers (see below for info on layers). |
| 200 | +- `groups` (optional): This is an array of its data subgroups, which follows the same structure and is used to build the data hierarchy. |
| 201 | + |
| 202 | +Definitions of data sources and layers is optional within a data group so that groups can be added just for hierarchal purposes rather than _having_ to house data in every group. |
| 203 | + |
| 204 | +```json |
| 205 | +{ |
| 206 | + "name": "My Example Group", |
| 207 | + "stack": "https://my-example-website.com/stack", |
| 208 | + "sources": [ |
| 209 | + ... |
| 210 | + ], |
| 211 | + "layers": [ |
| 212 | + ... |
| 213 | + ], |
| 214 | + "groups": [ |
| 215 | + "name": "My Example Sub Group", |
| 216 | + "stack": "https://my-example-website.com/subgroup/stack", |
| 217 | + "sources": [ |
| 218 | + ... |
| 219 | + ], |
| 220 | + "layers": [ |
| 221 | + ... |
| 222 | + ], |
| 223 | + "groups": [ |
| 224 | + ... |
| 225 | + ] |
| 226 | + ] |
| 227 | +} |
| 228 | +``` |
| 229 | + |
| 230 | +##### Defining a source |
| 231 | + |
| 232 | +Each group can contain a number of sources, representing individual data files or endpoints that will be loaded into memory by the chosen mapping library. Sources can also be defined in top-level groups, then utilised by layers further down the hierarchy. For loading local data files, it is recommended to placed them in the `uploads/config/data` directory for a more organised approach. Please create the subdirectory if required. |
| 233 | + |
| 234 | +Definitions of sources vary depending on the chosen mapping provider. Specific parameters used for each mapping library are detailed in later parts of the documentation. Nonetheless, the common parameters are detailed below: |
| 235 | + |
| 236 | +- `id` (required): This is the internal ID of the source. It needs to be unique within the current group, but is not required to be globally unique. |
| 237 | +- `type` (required): This is the type of the source. Acceptable values differ depending on the mapping library (see the library specific documentation for details). |
| 238 | + |
| 239 | +A sample definition for Mapbox is as follows: |
| 240 | + |
| 241 | +```json |
| 242 | +{ |
| 243 | + "id": "example-mapbox-source", |
| 244 | + "type": "geojson", |
| 245 | + "data": "./my-example-data.geojson" |
| 246 | +} |
| 247 | +``` |
| 248 | + |
| 249 | +##### Defining a layer |
| 250 | + |
| 251 | +Each group can also contain a number of layers, defining how the data is visualised on screen. Layers can utilise sources defined in groups higher in the hierarchy; additionally multiple layers can visualise data from the same source. |
| 252 | + |
| 253 | +As with sources, definitions of layers vary depending on the chosen mapping provider (as they all support different styling options). Specific parameters used for each mapping library are detailed in later parts of the documentation. Nonetheless, the common parameters are detailed below: |
| 254 | + |
| 255 | +- `id` (required): This is the internal ID of the layer. It needs to be unique within the current group, but is not required to be globally unique. |
| 256 | +- `name` (required): This is the user facing name of the layer (that will appear in the tree). Multiple layers can use the same name, they'll be combined in a single entry in the tree. |
| 257 | +- `source` (required): This is the ID of the source used to populate the layer. |
| 258 | + |
| 259 | +```json |
| 260 | +{ |
| 261 | + "id": "example-mapbox-layer", |
| 262 | + "name": "My Example Data", |
| 263 | + "source": "example-mapbox-source" |
| 264 | +} |
| 265 | +``` |
| 266 | + |
| 267 | +## 2. Assets |
| 268 | + |
| 269 | +This directory is expected to host any assets (images, svg, icons, gifs) for the client. The root endpoint will be `$HOST/images`. For example, the `loading.gif` is available at `$HOST/images/defaults/loading.gif`. |
| 270 | + |
| 271 | +Do note that users should **NOT** delete any contents within the `defaults` directory, as it hosts required images and icons. The remaining contents on the repository are optional and intended to be part of a tutorial. |
| 272 | + |
| 273 | +## 3. Optional Pages |
| 274 | + |
| 275 | +Developers can insert landing pages alongside other supplementary pages such as about us, glossary, acknowledgements, and attributions into the platform. These optional pages must be included as `Markdown` files in the `uploads/optional-pages` directory. |
| 276 | + |
| 277 | +Do note that the supplementary pages will be inserted as thumbnails and accessed via the landing page. It is crucial to add numbers in the file name of supplementary pages to order the thumbnail display according to your preferences. Otherwise, file names are insignificant if the display order is not of utmost significance. For instance, `01.about.md` and `02.glossary.md` will be always be displayed in this sequence as 01 is smaller than 02. |
| 278 | + |
| 279 | +When linking the images in markdown, do note that any relative path should start from the `images` path (e.g. `/images/defaults/icons/acknowledgement.svg`). The platform will automatically transform this if required for a reverse proxy or subpath implementation through the `BASE_PATH` environment variable. |
| 280 | + |
| 281 | +### 3.1 Fields |
| 282 | + |
| 283 | +The following fields are supported, and must be added to the top of the file before any markdown content: |
| 284 | + |
| 285 | +- `title`: Displays the title on the browser tab. Required |
| 286 | +- `slug`: Identifier for the page route. Required |
| 287 | +- `description`: Describes the page in the landing page. Required only for non-landing pages |
| 288 | +- `thumbnail`: Displays the associated thumbnail image in the landing page. Required only for non-landing pages |
| 289 | + |
| 290 | +### 3.2 Sample |
| 291 | + |
| 292 | +A sample markdown file for the landing page: |
| 293 | + |
| 294 | +``` |
| 295 | +--- |
| 296 | +title: CReDo // Customisable |
| 297 | +slug: landing // This must always be set to landing for the landing page |
| 298 | +--- |
| 299 | +
|
| 300 | +Insert your content here |
| 301 | +``` |
| 302 | + |
| 303 | +## 4. Styling Overrides |
| 304 | + |
| 305 | +Users can override existing styling to suit their requirements by adding a `style-overrides.css` to the `uploads` directory. |
0 commit comments