Merge pull request #2 from Dorset-Council-UK/task-add-vector-info

docs/db/layers.md

@@ -81,10 +81,27 @@ Common additional parameters you may want to use include:
 !!! warning
     Incorrectly formatting this JSON object can result in the layer or the entire map failing to load correctly. Edit with caution.
 
+#### Vector layers
+
+For vector layers, you will need a minimum of the `url` option. Additionally, unless you want the default OpenLayers styles, you will need a `style` option as well. See [Styling vector layers](../gui/layers.md#styling-vector-layers) for more information.
+
+Additional options include:
+- `typename` - When using a WFS service, you should set the `url` to the base server URL, and the `typename` as the layer name you are requesting
+- `format` - The format the data is in. Defaults to 'application/json' unless specified.
+- `loadingstrategy` - Can be `bbox` or `all`. This defines how the vector layer is loaded, either with a bbox strategy (loading just a bounding box worth of data at a time) or loading everything at once. In reality, WFS based layers will default to `bbox` unless specifically set to `all`, and non-WFS layers will default to `all`
+
+!!! info "Supported vector formats"
+    - JSON (`application/json`, `text/json`, `geojson` or `json`)
+    - GML3 (`text/xml; subtype=gml/3.1.1`, `gml3`)
+    - GML2 (`text/xml; subtype=gml/2.1.2`, `gml2`)
+    - KML (`application/vnd.google-earth.kml xml`, `application/vnd.google-earth.kml+xml`, `kml`)
+
+!!! warning "Limitation"
+    Vectors cannot have a filter pre-applied to them.
+
 #### Other options
 
 - `projection` - If the layer is only available in a projection that is not the same as the map you are putting it in to, set the projection here, otherwise you can not include it, and the layer will be requested in the projection of the map. For XYZ layers, see the section on [XYZ reprojection](#xyz-reprojection)
-- `cswendpoint` - An endpoint to retrieve a CSW Metadata document, describing the layer. The metadata document should use Dublin Core and will be available via the 'i' button next to the layer name in the layer control. 
 
 ### Layer
 
@@ -122,7 +139,7 @@ The `CategoryLayer` table defines which layers are available in which categories
 
 ### LayerSourceType
 
-There are currently 3 supported layer types in GIFramework Maps. More may be added in the future.
+There are currently 7 supported layer types in GIFramework Maps. More may be added in the future.
 
 #### XYZ
 The XYZ source is used for tile data that is accessed through URLs that include a zoom level and tile grid x/y coordinates. Examples include OpenStreetMap and OpenCycleMap.
@@ -135,6 +152,18 @@ This is normally the best option, as it is more efficient and quicker, and can b
 #### ImageWMS
 The ImageWMS source is used for WMS layers that are provided 'untiled', so a single image is returned for the entire map screen. Normally you would choose TileWMS when available, but ImageWMS is particularly good if you have labels, or, if the layer is very complex, a single tile can load quicker than many smaller tiles.
 
+#### Vector
+The Vector source is used for WFS layers or file based layers (such as a KML or GeoJSON file at a specific URL). Currently, GIFramework Maps can handle GML2, GML3, GeoJSON, JSON and KML formats as a vector source. This source type uses standard vector rendering, so is very precise and can handle things like rotating labels, but because of this it is not suitable for large datasets or those with complex geometries.
+
+#### VectorImage
+The VectorImage source is fundamentally the same as the Vector source, but can handle larger datasets and geometries slightly better, by rendering the vector as an image on the client. This does mean some sharpness is occasionally lost, and things like labels don't rotate, but its much less 'laggy' when moving the map around with large or complex datasets.
+
+#### VectorTile
+The VectorTile source is used to render VectorTiles, a common format for things like basemaps which splits vectors up into tiles and delivers them efficiently to the browser ([learn more](https://en.wikipedia.org/wiki/Vector_tiles)). MVT (Mapbox Vector Tiles) is the most common standard for this.
+
+#### OGC VectorTile
+The OGC VectorTile format is the new OGC standard for VectorTiles. It works in a similar way to VectorTiles, but is the standard promoted by the Open Geospatial Consortium. 
+
 ## Advanced configuration
 
 ### XYZ reprojection

docs/gui/basemaps.md

@@ -0,0 +1,21 @@
+# Basemaps
+
+All [versions](../gui/versions.md) have one or more basemaps (sometimes referred to as background maps). A basemap is made up of a layer source and a basemap definition.
+
+### Creating the layer source
+
+A basemap first requires a [layer source](../gui/layers.md) to be created that defines where the layer comes from.
+
+The easiest way to create a layer source and then a basemap is to use the [layer wizard](../gui/layers.md#add-a-new-layer-using-the-wizard). This will take you through the steps to create a layer source and then present you with the basemap configuration interface.
+
+### Configuring a basemap
+
+A basemap is similar to a layer, but with a few less options.
+
+- Name: The friendly name for the basemap
+- Minimum viewable zoom level: This is the furthest zoomed out this basemap can be rendered at. This will restrict the map from being zoomed out any further than this
+- Maximum viewable zoom level: This is the furthest zoomed in this basemap can be rendered at. This will restrict the map from being zoomed in any further than this
+- Preview image URL: A URL to a preview image that will appear in the basemaps panel. This can be any valid image file. We recommend it be around 800x200 pixels
+- Max bounds: The maximum extent that this basemap should render to. Can be used to prevent basemaps being shown outside of your area of interest
+
+Once created, the basemap can be added to versions just like any other.

docs/gui/layers.md

@@ -12,19 +12,19 @@ You can [manually create](#add-a-new-layer-manually) a layer, or [use the wizard
 
 Using the wizard is the most straightforward way to get a layer into your map. Choose the 'Add Layer Wizard' option from the Layers management page.
 
-You will have two options, WMS and XYZ/TMS.  
+You will have two options, WMS/WFS and XYZ/TMS.  
 
-### Add a layer from a WMS service
+### Add a layer from a WMS or WFS service
 
 You can choose from the list of [pre-defined web service definitions](system.md#add-a-new-web-layer-service-definition), or enter a GetCapabilities URL to retrieve a list of layers.
 
-Once you've found the layer you want to add, check the projection and image format and change them if necessary, and then hit Add. 
+Once you've found the layer you want to add, check the projection and format and change them if necessary, and then hit Add. 
 
 You will be taken to a page to check and update the details if necessary. Most of the details should have been pre-filled for you.
 
 - Name - a friendly name for administrators. This is automatically taken from the Title of the WMS layer if available
 - Description - a basic description of the layer. This is shown to end users when the layer has no other description metadata available from source. This is automatically taken from the Abstract of the WMS layer if available
-- Layer type - choose the type. This will default to TileWMS, indicating you want the layer to be tiled. This is normally the right option, but you can also choose ImageWMS for untiled. Check the [help documentation on Layer types](../db/layers.md#layersourcetype) for more information
+- Layer type - choose the type. This will default to TileWMS for WMS, or Vector for WFS. These are normally the right options, but you can change this depending on your requirements. Check the [help documentation on Layer types](../db/layers.md#layersourcetype) for more information
 - Attribution - the [attribution](../gui/attributions.md) you want your layer to use. If the service provided an attribution string, the system will attempt to find the best match in your list of attributions and pre-select it. This can generate false positives, and often services do not provide an attribution string, so you'll need to check this and set it yourself.
 - Projection - The projection of the data you will be requesting. If you selected 'auto' on the previous screen, this will be blank. If its blank, the layer will automatically request data in the projection of the map its within. See [Auto Projection](#auto-projection) below for more information.
 
@@ -36,9 +36,24 @@ There is a collapsible section for 'Advanced settings'. You should generally lea
 - Version - The WMS version you will be using. This will generally be 1.1.0 or 1.3.0 and will have been selected for you, but you can override it here if you know what you are doing.
 - Require use of proxy? - Indicates whether this layer source requires the proxy. Will have been pre-selected for you based on your choices on the previous screen.
 
+!!! warning "Limitation"
+    Vectors cannot currently have a filter pre-applied to them. Users can apply filters to WFS based layers manually.
+
+#### Styling Vector layers
+
+!!! warning
+    This functionality is still in the early stages and there may be bugs and other issues. Use with caution.
+
+Vector layers work differently from WMS based layers. With vector data, styling is done on the client, so you need to provide styling rules to the application to tell it how to style a layer, otherwise you will get the OpenLayers defaults of blue dots/lines/polygons.
+
+!!! note
+    KML layers work a little different. They can have styling information built in, so if you don't provide a style rule, it will use that. 
+
+ Styling rules can either be provided as a URL or as a full JSON object, either in GeoStyler style format, Mapbox style format, or as an OpenLayers flat style. The easiest thing to do is to use the [GeoStyler demo](https://geostyler.github.io/geostyler-demo/) page and add your data (or a sample of it) and use the UI to style it how you want, or to import an SLD from GeoServer or QGIS into the GeoStyler demo, and convert it to GeoStyler style format.
+
 #### Auto Projection
 
-GIFramework Maps will automatically request data in the projection of the map it is within unless you specifically set a projection. Auto projection is ideal in most cases where the server the data is coming from is able to handle the projections you want. However, if the server hosting the source data does not handle the projection of the map, you will need to explicity set the projection on the layer source. GIFramework Maps will then handle the reprojection required to display it properly. If you aren't sure, set the projection to one advertised by the server as compatible. 
+GIFramework Maps will automatically request data in the projection of the map it is within unless you specifically set a projection. Auto projection is ideal in most cases where the server the data is coming from is able to handle the projections you want. However, if the server hosting the source data does not handle the projection of the map, you will need to explicitly set the projection on the layer source. GIFramework Maps will then handle the reprojection required to display it properly. If you aren't sure, set the projection to one advertised by the server as compatible. 
 
 ### Add a layer from an XYZ/TMS template
 
@@ -77,6 +92,10 @@ There is a collapsible section for 'Advanced settings'. You should generally lea
     }
     ```
 
+### Adding non-WFS based vector layers
+
+GIFramework Maps can also render vector layers from a non-WFS source, such as a KML or GeoJSON file on a web server or a non OGC API that is capable of producing valid GeoJSON. This cannot be done using the layer wizard, and must be manually added by creating a layer source with the appropriate parameters. Check the documentation on [adding a layer manually](#add-a-new-layer-manually) for more details.
+
 ## The layer details screen
 
 When you've created a source, or if you are editing an existing layer, you will see the layer details screen.
@@ -87,7 +106,7 @@ When you've created a source, or if you are editing an existing layer, you will
 - Layer Z-Index - this is the 'layer order' on the map. Higher numbers will, by default, appear above lower numbers when both layers are turned on. For things like Aerial Photography, this should generally be set very low (such as -500). Leave blank for default of 0
 - Info List Template - the template for what appears when you click multiple items and are presented with a list of features. See [Info Templates](#info-templates) below for more information
 - Info Template - the template for what appears when you select a single map feature. See [Info Templates](#info-templates) below for more information
-- Querayable - whether you want the layer to be queryable (clicking on a feature will display further information)
+- Queryable - whether you want the layer to be queryable (clicking on a feature will display further information)
 - Filterable - whether you want the layer to be filterable
 
 !!! note
@@ -174,7 +193,7 @@ You can also apply custom formatting by passing a `format` string to the `date`
 
     - `{{DATE_ATTRIBUTE | date}}` :material-arrow-right: `07/02/2023` (assuming `en-GB` locale, will be different depending on users locale)
     - `{{DATE_ATTRIBUTE | date('yyyy')}}` :material-arrow-right: `2023`
-    - `{{DATE_ATTRIBUTE | date('ccc dd LLLL yyyy T')}}` :material-arrow-right: `Tuesday  07 February 2023 17:10`
+    - `{{DATE_ATTRIBUTE | date('ccc dd LLLL yyyy T')}}` :material-arrow-right: `Tuesday 07 February 2023 17:10`
 
 #### Conditionals
 
@@ -189,7 +208,7 @@ If statements are very simple and flexible. A basic example is
   It is something
 {% endif %}
 ```
-This will render the string 'It is something' if the `attribute` is equal to 'something'. Everthing between the tags can include placeholders and HTML as normal. 
+This will render the string 'It is something' if the `attribute` is equal to 'something'. Everything between the tags can include placeholders and HTML as normal. 
 
 For example, the following will wrap the `STATUS` attribute in a `<span>` with the class `text-danger` (rendering it as red text) if the `STATUS` is 'Closed', otherwise it will not wrap it in anything.
 ```
@@ -248,7 +267,7 @@ This section is where you add in the details for your layers. Select **Add new l
 - Layer Z-Index - this is the 'layer order' on the map. Higher numbers will, by default, appear above lower numbers when both layers are turned on. For things like Aerial Photography, this should generally be set very low (such as -500). Leave blank for default of 0
 - Info List Template - the template for what appears when you click multiple items and are presented with a list of features. See [Info Templates](../db/layers.md#info-templates) for more information
 - Info Template - the template for what appears when you select a single map feature. See [Info Templates](../db/layers.md#info-templates) for more information
-- Querayable - whether you want the layer to be queryable (clicking on a feature will display further information)
+- Queryable - whether you want the layer to be queryable (clicking on a feature will display further information)
 - Filterable - whether you want the layer to be filterable
 
 You'll also see a button for *Advanced settings*, which are optional. You can change the default opacity and saturation here if you want to.