From 201fe2519d86c223baf68ffff564c7fadf760da3 Mon Sep 17 00:00:00 2001 From: Konstantin Holm Date: Wed, 31 Jul 2024 16:24:59 +0200 Subject: [PATCH] Update readme files regarding reference on global plugin parameters --- packages/core/README.md | 24 +++++++++++++++------ packages/plugins/AddressSearch/README.md | 2 ++ packages/plugins/Attributions/README.md | 2 ++ packages/plugins/Draw/README.md | 2 ++ packages/plugins/Export/README.md | 2 ++ packages/plugins/Filter/README.md | 2 ++ packages/plugins/Fullscreen/README.md | 2 ++ packages/plugins/GeoLocation/README.md | 2 ++ packages/plugins/Gfi/README.md | 2 ++ packages/plugins/IconMenu/README.md | 2 ++ packages/plugins/LayerChooser/README.md | 2 ++ packages/plugins/LoadingIndicator/README.md | 4 ++++ packages/plugins/Pins/README.md | 2 ++ packages/plugins/ReverseGeocoder/README.md | 2 ++ packages/plugins/Scale/README.md | 4 ++++ packages/plugins/Toast/README.md | 2 ++ packages/plugins/Zoom/README.md | 2 ++ 17 files changed, 53 insertions(+), 7 deletions(-) diff --git a/packages/core/README.md b/packages/core/README.md index 2fcd20f3d..0f0524adb 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -74,7 +74,7 @@ The mapConfiguration allows controlling many client instance details. | layerConf | LayerConf | Layer configuration as required by masterportalAPI. | | language | enum["de", "en"] | Initial language. | | <...masterportalAPI.fields> | various | The object is also used to initialize the masterportalAPI. Please refer to their documentation for options. | -| | various? | Many plugins added with `addPlugin` may respect additional configuration. Please see the respective plugin documentations. Global plugin parameters are described below. | +| | various? | Fields for configuring plugins added with `addPlugin`. Refer to each plugin's documentation for specific fields and options. Global plugin parameters are described [below](../core/README.md#global-plugin-parameters). | | locales | LanguageOption[]? | All locales in POLAR's plugins can be overridden to fit your needs.| | vuetify | object? | You may add vuetify configuration here. | | extendedMasterportalapiMarkers | extendedMasterportalapiMarkers? | Optional. If set, all configured visible vector layers' features can be hovered and selected by mouseover and click respectively. They are available as features in the store. Layers with `clusterDistance` will be clustered to a multi-marker that supports the same features. Please mind that this only works properly if you configure nothing but point marker vector layers styled by the masterportalAPI. | @@ -199,21 +199,31 @@ The `<...masterportalAPI.fields>` means that any masterportalAPI field may also ##### -On how to configure a plugin, see the respective plugin. The configuration is given in the `mapConfiguration` object by the plugin's name as specified in its respective documentation. For example, a `@polar/plugin-address-search` plugin can be configured like this: +Plugins in POLAR are modular components that extend the functionality of the map client. They can be added using the [addPlugin](../core/README.md#addPlugins) method and configured through the `mapConfiguration` object. Each plugin has its own set of fields and options that can be customized. + +On how to configure a plugin, see the respective plugin. The configuration is given in the `mapConfiguration` object by the plugin's name as specified in its respective documentation. + +###### Global Plugin Parameters +Most plugins honor this additional field. + +| fieldName | type | description | +| - | - | - | +| displayComponent | boolean? | Optional field that allows hiding UI elements from the user. The store will still be initialized, allowing you to add your own UI elements and control the plugin's functionality via the Store. This may or may not make sense, depending on the plugin. Defaults to `false` , meaning the default UI is hidden. | + +###### Example Configuration + +For example, a `@polar/plugin-address-search` plugin can be configured like this: ```js { addressSearch: { + // Plugin-specific configuration + displayComponent: true, // Optional field to control UI elements // ... } } ``` -Most plugins honor this additional field. - -| fieldName | type | description | -| - | - | - | -| displayComponent | boolean? | Optional field that allows hiding UI elements from the user. The store will still be initialized, allowing you to add your own UI elements and control the plugin's functionality via the Store. This may or may not make sense, depending on the plugin. Defaults to `false` , meaning the default UI is hidden. | ##### mapConfiguration.vuetify diff --git a/packages/plugins/AddressSearch/README.md b/packages/plugins/AddressSearch/README.md index 2617ae643..a63aebe65 100644 --- a/packages/plugins/AddressSearch/README.md +++ b/packages/plugins/AddressSearch/README.md @@ -36,6 +36,8 @@ In `categoryProperties` and `groupProperties`, id strings called `groupId` and ` | removeLoading | string? | Optional loading action name to end loading. | | waitMs | number? | Debounce time in ms for search requests after last user input. Defaults to 0. | +For details on the `displayComponent` attribute, refer to the [Global Plugin Parameters](../../core/README.md#global-plugin-parameters) section of `@polar/core`. + #### addressSearch.searchMethodsObject | fieldName | type | description | diff --git a/packages/plugins/Attributions/README.md b/packages/plugins/Attributions/README.md index fe8ddb057..65a2d2b5b 100644 --- a/packages/plugins/Attributions/README.md +++ b/packages/plugins/Attributions/README.md @@ -19,6 +19,8 @@ All parameters are optional. However, setting neither `layerAttributions` nor `s | staticAttributions | string[]? | List of static attributions that are always shown. | | windowWidth | number? | If `renderType` is set to `independent`, sets the width of the container of the attributions. Defaults to 500. | +For details on the `displayComponent` attribute, refer to the [Global Plugin Parameters](../../core/README.md#global-plugin-parameters) section of `@polar/core`. + #### attributions.layerAttribution | fieldName | type | description | diff --git a/packages/plugins/Draw/README.md b/packages/plugins/Draw/README.md index c2171ab40..53b7ef1b5 100644 --- a/packages/plugins/Draw/README.md +++ b/packages/plugins/Draw/README.md @@ -37,6 +37,8 @@ The styling of the drawn features can be configured to overwrite the default ol- | style | style? | Please see example below for styling options. Defaults to standard OpenLayers styling. | | textStyle | object? | Use this object with properties 'font' and 'textColor' to style text feature. | +For details on the `displayComponent` attribute, refer to the [Global Plugin Parameters](../../core/README.md#global-plugin-parameters) section of `@polar/core`. + ##### draw.textStyle | fieldName | type | description | diff --git a/packages/plugins/Export/README.md b/packages/plugins/Export/README.md index 7c11857f0..f81f71ed1 100644 --- a/packages/plugins/Export/README.md +++ b/packages/plugins/Export/README.md @@ -15,6 +15,8 @@ The Export plugin offers users to download the currently visible map canvas in a | showPdf | boolean? | Tools offers current map view as PDF. Defaults to `true`. | | showPng | boolean? | Tools offers current map view as PNG. Defaults to `true`. | +For details on the `displayComponent` attribute, refer to the [Global Plugin Parameters](../../core/README.md#global-plugin-parameters) section of `@polar/core`. + ## Store To remove user control, add `displayComponent: false` to the configuration and use the following interactions. diff --git a/packages/plugins/Filter/README.md b/packages/plugins/Filter/README.md index d32a6c2a3..6fc703f2f 100644 --- a/packages/plugins/Filter/README.md +++ b/packages/plugins/Filter/README.md @@ -12,6 +12,8 @@ The Filter plugin can be used to filter arbitrary configurable vector layers by | - | - | - | | layers | Record | Maps layer id to filter configuration. | +For details on the `displayComponent` attribute, refer to the [Global Plugin Parameters](../../core/README.md#global-plugin-parameters) section of `@polar/core`. + ``` The following chapters contain drafts in this format. Please mind that they neither represent UI nor localisation, but are merely there to communicate the idea with an example. ``` diff --git a/packages/plugins/Fullscreen/README.md b/packages/plugins/Fullscreen/README.md index 2900c73cf..fd6ec88c8 100644 --- a/packages/plugins/Fullscreen/README.md +++ b/packages/plugins/Fullscreen/README.md @@ -13,6 +13,8 @@ The fullscreen plugin allows viewing the map in fullscreen mode. It relies solel | renderType | 'iconMenu' \| 'independent'? | Whether the fullscreen button is being rendered independently or as part of the IconMenu. Defaults to 'independent'. | | targetContainerId | string? | Specifies the html element on which the fullscreen mode should be applied. If the parameter is omitted, it falls back to the configured global field `containerId`. | +For details on the `displayComponent` attribute, refer to the [Global Plugin Parameters](../../core/README.md#global-plugin-parameters) section of `@polar/core`. + ## Store ### State diff --git a/packages/plugins/GeoLocation/README.md b/packages/plugins/GeoLocation/README.md index 5227ec478..bc389a065 100644 --- a/packages/plugins/GeoLocation/README.md +++ b/packages/plugins/GeoLocation/README.md @@ -21,6 +21,8 @@ either `true` or `false`. When a users denies the location tracking, the button | toastAction | string? | If the user is not locatable within the boundary of the maps extent or the boundary of the layer of `boundaryLayerId`, this string will be used as action to send a toast information to the user. If no toast information is desired, leave this field undefined; for testing purposes, you can still find information in the console. | | zoomLevel | number? | Specifies to which zoom level gets zoomed after a successfull tracking of the location. Defaults to `7`. | +For details on the `displayComponent` attribute, refer to the [Global Plugin Parameters](../../core/README.md#global-plugin-parameters) section of `@polar/core`. + #### Example configuration ```json diff --git a/packages/plugins/Gfi/README.md b/packages/plugins/Gfi/README.md index 3f966c613..aa240bc31 100644 --- a/packages/plugins/Gfi/README.md +++ b/packages/plugins/Gfi/README.md @@ -23,6 +23,8 @@ The GFI plugin can be used to fetch and optionally display GFI (GetFeatureInfo) | mode | enum["bboxDot", "intersects"]? | Method of calculating which feature has been chosen by the user. `bboxDot` utilizes the `bbox`-url parameter using the clicked coordinate while `intersects` uses a `Filter` to calculate the intersected features. Layers can have their own `gfiMode` parameter which would override this global mode. To apply this, add the desired value to the parameter in the `mapConfiguration`. Defaults to `'bboxDot'`. | | renderType | ('iconMenu' \| 'independent')? | Only relevant if `window` is set to `true` for at least one layer. Whether the gfi plugin is rendered independently or as part of the IconMenu. Defaults to 'independent'. | +For details on the `displayComponent` attribute, refer to the [Global Plugin Parameters](../../core/README.md#global-plugin-parameters) section of `@polar/core`. + ##### gfi.gfiLayerConfiguration | fieldName | type | description | diff --git a/packages/plugins/IconMenu/README.md b/packages/plugins/IconMenu/README.md index ff54980b6..6a7f4bbaf 100644 --- a/packages/plugins/IconMenu/README.md +++ b/packages/plugins/IconMenu/README.md @@ -13,6 +13,8 @@ _Please note that the average user has never seen the client before and just wan > ⚠️ This plugin can't be configured with the `mapConfiguration`, but is configured during client construction. Currently, no way exists to add plugins to it after the build took place. +For details on the `displayComponent` attribute, refer to the [Global Plugin Parameters](../../core/README.md#global-plugin-parameters) section of `@polar/core`. + Usage during client build: ```js diff --git a/packages/plugins/LayerChooser/README.md b/packages/plugins/LayerChooser/README.md index 92a125267..6858f01bc 100644 --- a/packages/plugins/LayerChooser/README.md +++ b/packages/plugins/LayerChooser/README.md @@ -25,6 +25,8 @@ Each object in `mapConfiguration.layers` array fits this definition: | options | options? | Shows a layer-specific sub-menu; its contents are configurable. | | visibility | boolean? | Initial visibility. Defaults to `false`. | +For details on the `displayComponent` attribute, refer to the [Global Plugin Parameters](../../core/README.md#global-plugin-parameters) section of `@polar/core`. + ### mapConfiguration.layers.options An option wheel will appear in the layer chooser that allows opening a sub-menu with configured configuration options for the end user. diff --git a/packages/plugins/LoadingIndicator/README.md b/packages/plugins/LoadingIndicator/README.md index 33e07719f..48127f697 100644 --- a/packages/plugins/LoadingIndicator/README.md +++ b/packages/plugins/LoadingIndicator/README.md @@ -4,6 +4,10 @@ A generic loading indicator that may be used by any plugin or outside procedure to indicate loading. +## Configuration + +For details on the `displayComponent` attribute, refer to the [Global Plugin Parameters](../../core/README.md#global-plugin-parameters) section of `@polar/core`. + ## Store ### Mutations diff --git a/packages/plugins/Pins/README.md b/packages/plugins/Pins/README.md index 41d721c40..69c68a16e 100644 --- a/packages/plugins/Pins/README.md +++ b/packages/plugins/Pins/README.md @@ -22,6 +22,8 @@ The usage of `displayComponent` has no influence on the creation of Pins on the | toastAction | string? | If `boundaryLayerId` is set, and the pin is moved or created outside the boundary, this string will be used as action to send a toast information to the user. If no toast information is desired, leave this field undefined; for testing purposes, you can still find information in the console. | | toZoomLevel | number? | Zoom level to use on outside input by e.g. address search. Defaults to `0`. | +For details on the `displayComponent` attribute, refer to the [Global Plugin Parameters](../../core/README.md#global-plugin-parameters) section of `@polar/core`. + #### pins.appearOnClick | fieldName | type | description | diff --git a/packages/plugins/ReverseGeocoder/README.md b/packages/plugins/ReverseGeocoder/README.md index 3edaa8b18..1281a0a92 100644 --- a/packages/plugins/ReverseGeocoder/README.md +++ b/packages/plugins/ReverseGeocoder/README.md @@ -19,6 +19,8 @@ This module has been written for the HH WPS service. The return format is custom | removeLoading | string? | Points to an action in the store; commited with a loading key as payload on finishing reverse geocoding. | | zoomTo | number? | If specified, plugin zooms to given coordinate after successful reverse geocoding; number indicates maximal zoom level. | +For details on the `displayComponent` attribute, refer to the [Global Plugin Parameters](../../core/README.md#global-plugin-parameters) section of `@polar/core`. + ## Store The ReverseGeocoder plugin does not hold any state. diff --git a/packages/plugins/Scale/README.md b/packages/plugins/Scale/README.md index c05e15074..2255e528a 100644 --- a/packages/plugins/Scale/README.md +++ b/packages/plugins/Scale/README.md @@ -5,3 +5,7 @@ ## Scope The scale plugin shows the current map resolution as relative scale (1:x) and/or absolute scale (a drawn line has length x units). + +## Configuration + +For details on the `displayComponent` attribute, refer to the [Global Plugin Parameters](../../core/README.md#global-plugin-parameters) section of `@polar/core`. diff --git a/packages/plugins/Toast/README.md b/packages/plugins/Toast/README.md index 8a03f7c01..0b2cf32e3 100644 --- a/packages/plugins/Toast/README.md +++ b/packages/plugins/Toast/README.md @@ -17,6 +17,8 @@ Please check the vuetify documentation to override the success, warning, info, o | success | toastStyle? | Design override for success messages. | | warning | toastStyle? | Design override for warning messages. | +For details on the `displayComponent` attribute, refer to the [Global Plugin Parameters](../../core/README.md#global-plugin-parameters) section of `@polar/core`. + #### toast.toastStyle | fieldName | type | description | diff --git a/packages/plugins/Zoom/README.md b/packages/plugins/Zoom/README.md index bfad5a7db..8f9da423e 100644 --- a/packages/plugins/Zoom/README.md +++ b/packages/plugins/Zoom/README.md @@ -14,6 +14,8 @@ It can be configured as followed. | renderType | 'iconMenu' \| 'independent'? | Whether the zoom related buttons are being rendered independently or as part of the IconMenu. Defaults to `'independent'`. | | showMobile | boolean? | Whether the zoom related buttons should be displayed on smaller devices; defaults to `false`. | +For details on the `displayComponent` attribute, refer to the [Global Plugin Parameters](../../core/README.md#global-plugin-parameters) section of `@polar/core`. + ## Store ### State