diff --git a/docs/assets/images/customise-layers.png b/docs/assets/images/customise-layers.png new file mode 100644 index 0000000..6744f3b Binary files /dev/null and b/docs/assets/images/customise-layers.png differ diff --git a/docs/db/layers.md b/docs/db/layers.md index c9b452c..054ced6 100644 --- a/docs/db/layers.md +++ b/docs/db/layers.md @@ -83,8 +83,8 @@ Common additional parameters you may want to use include: #### Other options -- `projection` - If the projection is anything other than EPSG:3857, set it here. For WMS based layers, this is enough. 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. +- `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 @@ -110,49 +110,7 @@ Once this has been created, the layer table has the following fields to fill in: #### Info Templates -Info templates control how the user see's data when they click an item on the map. There are two info templates used by GIFramework Maps. - -- `InfoTemplate` - The template for what appears when you select a single map feature - -
- ![An InfoTemplate for a single map feature](../assets/images/feature-details-address-information.png){width="350"} -
An `InfoTemplate` for a single map feature. Mapping © Crown Copyright OS.
-
- -- `InfoListTitleTemplate` - The template for what appears when you select multiple map features and are presented with a list of features - -
-![An InfoListTitleTemplate for multiple features](../assets/images/feature-details-multiple-addresses.png){width="350"} -
An `InfoListTitleTemplate` for multiple features. Mapping © Crown Copyright OS.
-
- -`InfoTemplate`s use a system called [nunjucks](https://mozilla.github.io/nunjucks/templating.html) for templating. You can read their documentation or the [section below](#advanced-templating) for advanced uses. For basic uses, you simply write standard HTML, and use the placeholder `{{COLUMN_NAME}}` to inject attributes into the template. - -!!! example - - Template (assuming there are attributes called `ADDRESS` and `UPRN`): - - `

{{ADDRESS}}

UPRN: {{UPRN}}

` - - Output: - - `

1 Somewhere Drive, Someplace, SM1 1AA

UPRN: 10010101001

` - -`InfoListTitleTemplate`s are simpler, and are designed for a single line of text with placeholders. It still uses nunjucks and the placeholder `{{COLUMN_NAME}}`, but should be kept simple as there may be many results listed. - -!!! warning - Avoid using HTML in an `InfoListTitleTemplate`. The template is injected into an `` tag within a `
  • ` tag, so adding further HTML may cause unexpected results. - -!!! example - Template (assuming there is an attribute called `ADDRESS`): - - `Address: {{ADDRESS}}` - - Output: - - - `Address: 1 Somewhere Drive, Someplace, SM1 1AA` - - `Address: 2 Somewhere Drive, Someplace, SM1 1AA` - - `Address: 3 Somewhere Drive, Someplace, SM1 1AA` +See ['Creating info templates'](../gui/layers.md#info-templates) ### CategoryLayer @@ -179,66 +137,6 @@ The ImageWMS source is used for WMS layers that are provided 'untiled', so a sin ## Advanced configuration -### Advanced templating - -There are a number of advanced features built into the templating engine to allow for some smart customisation. - -#### Date formatting - -You can apply custom date formatting to datetime attributes to make them more user friendly. - -!!! warning - This is a custom extension to nunjucks and not part of the standard nunjucks templating engine - -To apply basic datetime formatting, simply add ` | date` after your attribute name. For example `{{DATE_ATTRIBUTE | date}}` will attempt to render the attribute `DATE_ATTRIBUTE` using the [`toLocaleDateString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleDateString#using_tolocaledatestring) JavaScript function. In `en-GB` locales this would convert the ISO date `2023-02-07T17:10:00.000Z` to `07/02/2023`. - -You can also apply custom formatting by passing a `format` string to the `date` function. For example `{{DATE_ATTRIBUTE | date('yyyy')}}` will convert the ISO date `2023-02-07T17:10:00.000Z` to `2023`. This custom formatting is applied using a library called [luxon](https://moment.github.io/luxon), who provide [a table of tokens](https://moment.github.io/luxon/#/formatting?id=table-of-tokens) you can use. - -!!! example "Examples" - Assuming an attribute called `DATE_ATTRIBUTE` with the value `2023-02-07T17:10:00.000Z` (Feb 7th, 2023 at 17:10) - - - `{{DATE_ATTRIBUTE | date}}` :material-arrow-right: `07/02/2023` - - `{{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` - -#### Conditionals - -You can use basic if statements to conditionally show/hide content in a template or render it in a different way. - -!!! info - You can read the full documentation on if statements in nunjucks [in their documentation](https://mozilla.github.io/nunjucks/templating.html#if) - -If statements are very simple and flexible. A basic example is -``` -{% if attribute === 'something' %} - 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. - -For example, the following will wrap the `STATUS` attribute in a `` with the class `text-danger` (rendering it as red text) if the `STATUS` is 'Closed', otherwise it will not wrap it in anything. -``` -{% if STATUS === 'Closed' %} - {{STATUS}} -{% else %} - {{STATUS}} -{% endif %} -``` - -#### Everything else - -There are many more helpers available. The best way to find out more is to read the [nunjucks templating documentation](https://mozilla.github.io/nunjucks/templating.html). - -Some useful ones you might consider: - -- [Math](https://mozilla.github.io/nunjucks/templating.html#math) - Perform simple math operations -- [capitalize](https://mozilla.github.io/nunjucks/templating.html#capitalize) - Make the first letter uppercase, the rest lower case -- [int](https://mozilla.github.io/nunjucks/templating.html#int) - Convert the value into an integer. If the conversion fails 0 is returned. -- [lower](https://mozilla.github.io/nunjucks/templating.html#lower) - Convert string to all lower case -- [round](https://mozilla.github.io/nunjucks/templating.html#round) - Round a number -- [truncate](https://mozilla.github.io/nunjucks/templating.html#truncate) - Return a truncated copy of the string -- [upper](https://mozilla.github.io/nunjucks/templating.html#upper) - Convert the string to upper case - ### XYZ reprojection XYZ layers can be provided in different projections. To make use of on the fly reprojection, you need to provide an appropriate `tilegrid` option, describing the resolutions and origins of the XYZ layer. The service provider should be able to provide this. diff --git a/docs/db/projections.md b/docs/db/projections.md new file mode 100644 index 0000000..aa53da3 --- /dev/null +++ b/docs/db/projections.md @@ -0,0 +1,28 @@ +# Projections + +GIFramework Maps can use multiple projections for both the actual map rendering and the display coordinates. The Projections table defines what projections are available to the application. + +## Relevant tables + +| Table Name | Description | +| --------------------------------- | ------------------------------------ | +| Projections | The projection definitions | +| VersionProjections | Table that defines which versions have which projections | + +### Projections + +This table contains the projection definition. + +- `EPSGCode` - The EPSG code of the projection. +- `Name` - The name of the projection +- `Description` - A description of what this projection is and where it covers +- `Proj4Definition` - A Proj4 or WKT definition of the projection +- `MinBoundX` - The bottom left X coordinate of this projections maximum bounds, in Lat/Lon +- `MinBoundY` - The bottom left Y coordinate of this projections maximum bounds, in Lat/Lon +- `MaxBoundX` - The top right X coordinate of this projections maximum bounds, in Lat/Lon +- `MaxBoundY` - The top right Y coordinate of this projections maximum bounds, in Lat/Lon +- `DefaultRenderedDecimalPlaces` - The number of decimal places shown by default when showing coordinates in this projection + +### VersionProjections + +See [VersionProjections](../db/versions.md#versionprojection) diff --git a/docs/db/versions.md b/docs/db/versions.md index b390e44..a4b4e4d 100644 --- a/docs/db/versions.md +++ b/docs/db/versions.md @@ -9,17 +9,21 @@ The `Versions` table contains all the basic information about a version of GIFra | Table Name | Description | | ----------------------------------- | ------------------------------------ | | Versions | Contains the basic details about a version, including name, slug, start bound, theme and more | -| VersionBasemaps | Contains an optional `BoundId` column used to define what bounds the layer covers | -| VersionCategory | Contains a `BoundId` column used to define what bounds the basemap covers | -| VersionPrintConfiguration | Contains a `BoundId` column used to define what bounds the basemap covers | -| VersionSearchDefinition | Contains a `BoundId` column used to define what bounds the basemap covers | -| VersionUser | Contains a `BoundId` column used to define what bounds the basemap covers | +| VersionAnalytic | Identifies which analytics providers are enabled for a version | +| VersionBasemaps | Contains details of the basemaps that a version has available and their default options | +| VersionCategory | Contains a list of layer categories that a version has | +| VersionContact | Lists the users that should be contacted regarding a version | +| VersionLayer | Contains per-layer customisations applied to a version | +| VersionPrintConfiguration | Identifies which print configuration a version uses | +| VersionProjections | Lists the projections available to a version and what the defaults are | +| VersionSearchDefinition | Lists the search definitions that are enabled in a version and their default settings | +| VersionUser | Contains the users that have access to a version | ### Versions - `Name` - The name of the version. This also appears to the user in the top left - `Description` - A friendly description of the version. This also appears in the HTML meta description which is shown to search engines -- `Slug` - The `Slug` is the bit on the end of the URL. You can have up to 3 parts to a slug, seperated by slashes. See section below on [slugs](#slugs) for more info +- `Slug` - The `Slug` is the bit on the end of the URL. You can have up to 3 parts to a slug, seperated by slashes. See [slugs](../gui/versions.md#slugs) for more info - `Enabled` - A boolean indicating whether this version is enabled or not. Disabled versions will show a specific 'Disabled' message, rather than the standard 'Not found' - `RequireLogin` - A boolean indicating whether this version requires the user to login or not. Permissions need to be given to users using the [`VersionUser`](#versionuser) table. - `RedirectionURL` - An optional URL to redirect the user to instead of loading the version. Can be useful if a version changes slug, or you want to point people elsewhere. Will issue a `HTTP 302 Found` response with the URL provided @@ -35,7 +39,8 @@ The `Versions` table contains all the basic information about a version of GIFra - `VersionImageURL` - An optional URL to an image that will show on a version's card on the version home page. If a URL is not supplied, a default image of the world will be used. - `Hidden` - A boolean indicating whether to hide a version from the versions home page (this will not delete a version or stop it being accessed directly by its URL). -#### Slugs +### VersionAnalytic +The `VersionAnalytic` table defines which analytics providers are available in which versions. Slugs are the bit on the end of your application URL which direct you to different versions of GIFramework Maps. You can have a maximum of three slugs seperated by forward slashes. @@ -92,6 +97,29 @@ The `VersionCategory` table defines which categories are available in which vers !!! info If your category is a child, both the parent AND child categories need to be added to this table. +### VersionContact +The `VersionContact` table defines which users should be contacted about a version. + +- `VersionContactId` - Unique ID for this entry +- `VersionId` - The `Id` from the `Versions` table +- `UserId` - The users unique identifier provided by the identity provider +- `DisplayName` - The users display name +- `Enabled` - Whether they should be included in the email drafting list + +### VersionLayer +The `VersionLayer` table contains any per-layer customisations that have been applied to this version. + +- `VersionId` - The `Id` from the `Versions` table +- `LayerId` - The `Id` from the `Layer` table +- `CategoryId` - The `Id` from the `Category` table +- `IsDefault` - Whether this layer is turned on by default or not +- `DefaultOpacity` - The default opacity of the layer +- `DefaultSaturation` - The default saturation of the layer +- `SortOrder` - The position this layer appears within its category +- `MaxZoom` - The maximum viewable zoom level of the layer +- `MinZoom` - The minimum viewable zoom level of the layer +- `Id` - Unique autogenerated ID for this customisation + ### VersionPrintConfiguration The `VersionPrintConfiguration` table defines which print configurations are used in which versions. @@ -102,6 +130,15 @@ The `VersionPrintConfiguration` table defines which print configurations are use !!! note If a specific configuration is not set for a version, it will fall back to that defined for the 'general' version +### VersionProjection + +The `VersionProjection` table defines which projection the map renders in and what projections are available for viewing. + +- `VersionId` - The `Id` from the `Versions` table +- `ProjectionId` - The `Id` from the `Projections` table +- `IsDefaultMapProjection` - Whether this projection is the one used for map rendering +- `IsDefaultViewProjection` - Whether this projection is the default one set as the display coordinates + ### VersionSearchDefinition The `VersionSearchDefinition` table defines which searches are available in which versions. diff --git a/docs/gui/layers.md b/docs/gui/layers.md index b979a88..4316a75 100644 --- a/docs/gui/layers.md +++ b/docs/gui/layers.md @@ -4,10 +4,229 @@ Layers are the bedrock of GIFramework Maps. Without layers, your maps are basica Layers are pretty configurable, and have lots of various options. -## Add a new layer - There are three parts to creating a layer: layer sources, layer details and layer categories. +You can [manually create](#add-a-new-layer-manually) a layer, or [use the wizard](#add-a-new-layer-using-the-wizard). We highly recommend you use the wizard, even if you have to make changes to what it generates, as it reduces the chance of getting anything wrong. + +## Add a new layer using 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. + +### Add a layer from a WMS 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. + +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 +- 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. + +There is a collapsible section for 'Advanced settings'. You should generally leave this alone as it contains details that will be used behind the scenes to make your layer work. However, you can edit them if you need to. + +- Base URL - This should be set to the 'base' url of the WMS service. This is normally provided to you by the service, and will look something like `https:///wms` +- Layer Name - This is the name of the layer in the web service, not the name that users will see. This name will be used by OpenLayers to make appropriate requests to the service. +- Format - The image format that will be used. This was available to select from the previous screen, so if you want something different, you should go back and select from the list. +- 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. + +#### 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. + +### Add a layer from an XYZ/TMS template + +You can enter an XYZ/TMS URL template to create a layer. + +This follows the widely-used Google grid where x 0 and y 0 are in the top left. Grids like TMS where x 0 and y 0 are in the bottom left can be used by using the {-y} placeholder in the URL template, so long as the source does not have a custom tile grid. + +Must include `{x}`, `{y}` or `{-y}`, and `{z}` placeholders. A `{?-?}` template pattern, for example subdomain{a-f}.domain.com, may be used to split traffic across multiple domains. + +!!! example + + For the OpenStreetMap tile server, you would use + + `https://tile.openstreetmap.org/{z}/{x}/{y}.png` + + This is just an example. Do not use the OpenStreetMap tile server for heavy workloads. + +When you hit 'Create XYZ source' you will be taken to a page to check and update the details if necessary. + +- Name - a friendly name for administrators +- Description - a basic description of the layer +- Attribution - the [attribution](../gui/attributions.md) you want your layer to use + +There is a collapsible section for 'Advanced settings'. You should generally leave this alone as it contains details that will be used behind the scenes to make your layer work. However, you can edit them if you need to. + +- URL Template - This is what you entered on the previous screen. If you made a mistake you can update it here. +- Projection - If the layer is NOT in the standard EPSG:3857, you can put an alternative projection here. You will also need to enter a custom tile grid. +- Custom tile grid - To make use of on the fly reprojection, you need to provide an appropriate custom tile grid, describing the resolutions and origins of the XYZ layer. The service provider should be able to provide this. It will be a simple JSON object + +!!! example + The custom tile grid for British National Grid EPSG:27700 is + ``` + { + "resolutions": [896.0, 448.0, 224.0, 112.0, 56.0, 28.0, 14.0, 7.0, 3.5, 1.75], + "origin": [-238375.0, 1376256.0] + } + ``` + +## 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. + +- Name +- Minimum viewable zoom level (optional) - the minimum zoom this layer will be turned on for, for example if set to 12, the layer will turn off once you zoom out past level 12 +- Maximum viewable zoom level (optional) - the maximum zoom this layer will be turned on for, for example if set to 15, the layer will turn off once you zoom in past level 15. Set to blank for no restriction +- 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) +- Filterable - whether you want the layer to be filterable + +!!! note + If you are creating a layer for an XYZ/TMS source, some options will not be available + +You'll also see a button for *Advanced settings*, which are optional. + +- Restricted bounds (optional) - The maximum [bounds](bounds.md) this layer covers. This will restrict map rendering and querying outside of these bounds, which can improve performance and prevent areas you don't want shown from appearing. +- Default Opacity - The opacity (transparency) of the layer when you first turn it on. Users can override this value. +- Default Saturation - The saturation of the layer when you first turn it on. Users can override this value. +- Default filter is editable - Whether any default filters applied to the layer source are editable by end users. +- Proxy Map Requests - Whether GetMap requests should go via the [Proxy](../db/proxy.md) +- Proxy Map Requests - Whether Feature Info and other metadata requests should go via the [Proxy](../db/proxy.md) + +### Info Templates + +Info templates control how the user see's data when they click an item on the map. Templates are a powerful feature that allows you to convert the unfriendly attribute based tables returned from a service into friendly, human readable popups. There are two info templates used by GIFramework Maps. + +- Info Template - The template for what appears when you select a single map feature + +
    + ![An Info Template for a single map feature](../assets/images/feature-details-address-information.png){width="350"} +
    An Info Template for a single map feature. Mapping © Crown Copyright OS.
    +
    + +- Info List Template - The template for what appears when you select multiple map features and are presented with a list of features + +
    +![An Info List Template for multiple features](../assets/images/feature-details-multiple-addresses.png){width="350"} +
    An Info List Template for multiple features. Mapping © Crown Copyright OS.
    +
    + +The templates use a system called [nunjucks](https://mozilla.github.io/nunjucks/templating.html) for templating. You can read their documentation or the [section below](#advanced-templating) for advanced uses. For basic uses, you simply write standard HTML, and use the placeholder `{{COLUMN_NAME}}` to inject attributes into the template. + +!!! example + + Template (assuming there are attributes called `ADDRESS` and `UPRN`): + + `

    {{ADDRESS}}

    UPRN: {{UPRN}}

    ` + + Output: + + `

    1 Somewhere Drive, Someplace, SM1 1AA

    UPRN: 10010101001

    ` + +Info List Templates are simpler, and are designed for a single line of text with placeholders. It still uses nunjucks and the placeholder `{{COLUMN_NAME}}`, but should be kept simple as there may be many results listed. + +!!! warning + Avoid using HTML in an info list template. The template is injected into an `    ` tag within a `
  • ` tag, so adding further HTML may cause unexpected results. + +!!! example + Template (assuming there is an attribute called `ADDRESS`): + + `Address: {{ADDRESS}}` + + Output: + + - `Address: 1 Somewhere Drive, Someplace, SM1 1AA` + - `Address: 2 Somewhere Drive, Someplace, SM1 1AA` + - `Address: 3 Somewhere Drive, Someplace, SM1 1AA` + +The admin interface has template helpers for the Info List Template and Info Template. These helpers allow you to build your template with HTML tags and appropriate attributes. + +- HTML tags (Info Templates only) - Gives you all the basic opening and closing tags for headers, paragraphs, basic styling and images. See the [MDN docs on HTML basics](https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/HTML_basics) to learn more. +- Attributes - Gives you a list of all the attributes available in the layer source you selected. Clicking them will insert that attribute into the template, surrounded by curly braces. In some instance we may not be able to get the attributes from the service. This can often be a warning that the service will not be queryable, so you will need to check. In these cases you will get a warning and will have to write your template manually. +- Date formatting - Gives you some helpers to insert date formatting strings. See [date formatting](#date-formatting) below for more detail. +- Preview - The preview will show you how your template will be rendered by grabbing a real feature from the service and rendering your template. In some instance we may not be able to get a feature from the service, so the preview won't work. + +### Advanced templating +There are a number of advanced features built into the templating engine to allow for some smart customisation. + +#### Date formatting + +You can apply custom date formatting to datetime attributes to make them more user friendly. + +!!! warning + This is a custom extension to nunjucks and not part of the standard nunjucks templating engine + +To apply basic datetime formatting, simply add ` | date` after your attribute name. For example `{{DATE_ATTRIBUTE | date}}` will attempt to render the attribute `DATE_ATTRIBUTE` using the [`toLocaleDateString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleDateString#using_tolocaledatestring) JavaScript function. In `en-GB` locales this would convert the ISO date `2023-02-07T17:10:00.000Z` to `07/02/2023`. + +You can also apply custom formatting by passing a `format` string to the `date` function. For example `{{DATE_ATTRIBUTE | date('yyyy')}}` will convert the ISO date `2023-02-07T17:10:00.000Z` to `2023`. This custom formatting is applied using a library called [luxon](https://moment.github.io/luxon), who provide [a table of tokens](https://moment.github.io/luxon/#/formatting?id=table-of-tokens) you can use. + +!!! example "Examples" + Assuming an attribute called `DATE_ATTRIBUTE` with the value `2023-02-07T17:10:00.000Z` (Feb 7th, 2023 at 17:10) + + - `{{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` + +#### Conditionals + +You can use basic if statements to conditionally show/hide content in a template or render it in a different way. + +!!! info + You can read the full documentation on if statements in nunjucks [in their documentation](https://mozilla.github.io/nunjucks/templating.html#if) + +If statements are very simple and flexible. A basic example is +``` +{% if attribute === 'something' %} + 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. + +For example, the following will wrap the `STATUS` attribute in a `` with the class `text-danger` (rendering it as red text) if the `STATUS` is 'Closed', otherwise it will not wrap it in anything. +``` +{% if STATUS === 'Closed' %} + {{STATUS}} +{% else %} + {{STATUS}} +{% endif %} +``` + +#### Everything else + +There are many more helpers available. The best way to find out more is to read the [nunjucks templating documentation](https://mozilla.github.io/nunjucks/templating.html). + +Some useful ones you might consider: + +- [Math](https://mozilla.github.io/nunjucks/templating.html#math) - Perform simple math operations +- [capitalize](https://mozilla.github.io/nunjucks/templating.html#capitalize) - Make the first letter uppercase, the rest lower case +- [int](https://mozilla.github.io/nunjucks/templating.html#int) - Convert the value into an integer. If the conversion fails 0 is returned. +- [lower](https://mozilla.github.io/nunjucks/templating.html#lower) - Convert string to all lower case +- [round](https://mozilla.github.io/nunjucks/templating.html#round) - Round a number +- [truncate](https://mozilla.github.io/nunjucks/templating.html#truncate) - Return a truncated copy of the string +- [upper](https://mozilla.github.io/nunjucks/templating.html#upper) - Convert the string to upper case + + +## Add a new layer manually + +You can create a layer manually by + +1. Creating a Layer Source +2. Adding the relevant Layer Source Options +3. Adding a layer +4. Adding it to a category + +!!! warning + We **strongly** suggest you use the wizard, even if you use it just to create the basics, then edit it as you need. Creating a layer source incorrectly can result in your entire map not loading correctly. + ### Layer sources This section covers where your layers come from. Select **Add new layer source** and fill in the details: @@ -19,7 +238,7 @@ This section covers where your layers come from. Select **Add new layer source** Tick the *Create layer source option on save* box to automatically fill in details that will appear on the right side of the screen. You can edit these manually if you need to, but you will need to know what you are doing. For more detailed information on these options, see [database layers](../db/layers.md#LayerSourceOption). -###Layer details +### Layer details This section is where you add in the details for your layers. Select **Add new layer**, you will be prompted to pick a layer source from the list. Fill in the details: @@ -34,7 +253,7 @@ This section is where you add in the details for your layers. Select **Add new l 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. -###Layer categories +### Layer categories This section is where you manage the categories that layers are organised into. Select **Create new category** and fill in the details: diff --git a/docs/gui/system.md b/docs/gui/system.md index 94c56e0..69d4293 100644 --- a/docs/gui/system.md +++ b/docs/gui/system.md @@ -24,7 +24,7 @@ Most of the data is cached for varying amounts of time, to improve performance. ## Web layer service definitions -Web layer service definitions detail pre-defined services that users can add layers from onto their map. These services are defined just once for all versions. +Web layer service definitions detail pre-defined services that users can add layers from onto their map, and that Admins can choose to add layers from in the [Add Layer wizard](layers.md#add-a-new-layer-using-the-wizard). These services are defined just once for all versions. ### Add a new web layer service definition @@ -38,6 +38,7 @@ Select **Manage web layer service definitions** then **Add new web layer service - Category - a category to group the list by. All services with the same category will be grouped in the select list presented to users - Whether you want to enable proxy map requests - only tick this if the layer can't be used with [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) - Whether you want to enable proxy metadata requests - only tick this if the layer can't be used with [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) +- Available to Admins only? - makes this service only visible to administrators on the map and in the [Add Layer wizard](layers.md#add-a-new-layer-using-the-wizard) !!! warning Proxying requests can reduce performance and may even be blocked by the service provider. If in doubt, check with the service provider. @@ -73,4 +74,50 @@ Select the tool you wish to edit from the tool list by product name. Make the ch ### Delete an analytics tool -Select the **Remove** link on the right of the tool list. This will remove your analytics entry. \ No newline at end of file +Select the **Remove** link on the right of the tool list. This will remove your analytics entry. + +## Projections + +GIFramework Maps can use multiple projections for both the actual map rendering and the display coordinates. The Projections section lets you manage what projections are available. + +### Register new projection + +To add a new projection to the list of available projections, choose 'Register new projection'. See [Getting projection details](#getting-projection-details) below to find out how to get the information you need. + +- `EPSG Code` - The EPSG code of the projection +- `Name` - The name of the projection +- `Description` - A description of what this projection is and where it covers +- `Proj4 or WKT Definition` - A Proj4 or WKT definition of the projection +- `Bottom Left X (Min X)` - The bottom left X coordinate of this projections maximum bounds, in Lat/Lon +- `Bottom Left Y (Min Y)` - The bottom left Y coordinate of this projections maximum bounds, in Lat/Lon +- `Top Right X (Max X)` - The top right X coordinate of this projections maximum bounds, in Lat/Lon +- `Top Right Y (Max Y)` - The top right Y coordinate of this projections maximum bounds, in Lat/Lon +- `Default display decimal places` - The number of decimal places shown by default when showing coordinates in this projection + +### Edit a projection + +Select the projection you want to edit from the list. Make the changes you want and hit Save. + +!!! warning + Be careful editing projections, as these can have a dramatic effect on the application + +### Delete a projection + +Select the projection you want to delete from the list. At the bottom, hit Delete and confirm your choice. + +!!! danger + Make sure your projection is not being used anywhere before deleting it + +### Getting projection details + +Projections are defined using the EPSG Code, Proj4Definition and bounds. You can get these using websites such as https://epsg.io or https://epsg.org/. You can use a Proj4 or WKT style definition for the projection definition. You do not have to provide a definition for the [built-in projections](#built-in-projections). + +### Built-in projections + +The following projections are built-in, and do not require a Proj4 or WKT definition. + +- EPSG:3857 - Spherical Mercator +- EPSG:4326 - WGS84 Lat/Lon +- EPSG:4269 - NAD83 (North America) + +You will still need to add the projection to the list to make it available to the application. \ No newline at end of file diff --git a/docs/gui/versions.md b/docs/gui/versions.md index e99484e..9ee2709 100644 --- a/docs/gui/versions.md +++ b/docs/gui/versions.md @@ -7,8 +7,9 @@ Versions are the best way to split maps up into different themes, with different Select **Create new version** and fill in the details: - Name -- Slug - the bit at the end of the URL. For example: 'highways' -> `https:///highways` -- Description +- Slug - the bit at the end of the URL. See [slugs](#slugs) for more information +- Description (optional) - A friendly description that is shown to users and put in the metadata of the version +- Version Notes (optional) - A description for administrators about this version - Theme - the [theme](../gui/themes.md) you want your version to use - Start extents - the [bound](../gui/bounds.md) to set the map to - Enabled - sets whether the version is enabled or not @@ -21,19 +22,101 @@ Select **Create new version** and fill in the details: - Help URL (optional) - include a link to custom documentation - Feedback URL (optional) - include a link to a feedback form - Redirection URL (optional) - a URL to redirect the user to instead of loading the version. Can be useful if a version changes slug, or you want to point people elsewhere +- Purge memory cache on save? - ticking this box will purge the cache and allow your version to be available for testing or use straight away - Version image URL (optional) - include a URL to an image to use on the version home page. Leaving this blank will use a default image of the world instead - Purge cache - ticking this box will purge the cache and allow your version to be available for testing or use straight away On the right side of the screen, you'll see options for: - Basemaps - choose which basemaps you want to include in your version and which one you want to set as the default -- Categories - choose which layer categories you want to include in your version +- [Projections](../gui/system.md#projections) - choose which projections are available and what the default map and viewing projection is +- [Categories](../gui/layers.md#layer-categories) - choose which layer categories you want to include in your version ## Edit a version Select the version you want to edit. Make the changes you want and hit Save. +On the right side of the screen you will also see new options for: + +- [Layer customisations](#layer-customisations) - allows you to customise how individual layers are configured for this specific version only +- [Version contacts](#version-contacts) - add users who are considered a 'contact' for the version + ## Delete a version -Select the version you want to delete. You will be asked if you're sure, press Delete again to confirm. \ No newline at end of file +Select the version you want to delete. You will be asked if you're sure, press Delete again to confirm. + +## Slugs + +Slugs are the bit on the end of your application URL which direct you to different versions of GIFramework Maps. You can have a maximum of three slugs seperated by forward slashes. + +By default, there should be one called 'general' which is where you will be directed if you have no slug on your URL. + +!!! danger "Reserved slugs" + There are a number of slugs that are reserved for use by the GIFramework Maps application. Using these will not work and may cause other unintended consequences. + + - `general` + - `account` + - `api` + - `print` + - `search` + - `broadcasthub` + - `css` + - `img` + - `lib` + + You should not use these as the first part of the slug, regardless of any additional parts you put on the end, e.g. `lib/myversion` is **not** valid + + + +!!! example "Examples" + 'general' -> Root of application e.g. `https:///` + + 'highways' -> `https:///highways` + + 'very/long/slug' -> `https:///very/long/slug` + +# Layer customisations + +Layer customisations allow you to customise how individual layers are configured for this specific version only. The most common use is to turn one or many layers on by default, so users don't have to switch them on themselves, but you can also set the starting opacity/saturation, set the zoom levels and change where it appears within its category. + +You will be shown a list of all layers that are currently enabled in your version. Any that already have customisation will be at the top and highlighted. +
    +![The layer customisations table for a version](../assets/images/customise-layers.png){width="650"} +
    The layer customisations table for a version
    +
    + +Choose a layer you want to customise and you'll be taken to the customisations screen. You can set the following options on the layer: +- On by default - Check to make this layer be switched on by default when the user opens this version +- Minimum viewable zoom level - Set the minimum viewable zoom level. Zooming out beyond this level will switch the layer off automatically +- Maximum viewable zoom level - Set the maximum viewable zoom level. Zooming in beyond this level will switch the layer off automatically +- Sort order within category - Change the position it appears sorted in within its folder +- Default opacity - Set the default opacity of the layer +- Default saturation - Set the default saturation of the layer + +!!! note + Setting 'On by default' on a layer will override a users share link and always turn on the layer, so use with caution + +If you are editing an existing customisation, you can also delete the customisation using the Delete button. + +Every layer customisation applied to a version can be removed in one go by going to the Layer Customisations list and choosing 'Remove all custonisations'. + +# Version contacts + +Version contacts allow you to add one or many users as 'contacts' for the version. This could be for any reason, such as being the named person in charge of the version, or an interested party. Administrators can then use this list to quickly get in touch with relevant people for a version. + +Go the edit screen of a version, and choose the 'Version contacts' button on the right. You will be shown a list of any existing contacts and a button to add a contact entry. + +## Adding or editing a contact + +When you add a user, you can choose to provide a friendly name to identify them to administrators, in case the name provided by the identity provider is different. + +!!! note + The list of users comes from the list of users provided by your identity provider. There is no way at this time to add users who are not part of this list. + +You can check the 'Enable alerts for user' to make sure they are included in any emails or any future automated alert functionality. + +## Emailing users + +On the version contacts list, there is a button to 'Draft an email'. This will simply open an email addressed to all users with 'Yes' in the Mailing List column in your default mail program. + diff --git a/docs/index.md b/docs/index.md index 3abf03b..c9f91ca 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,5 +2,8 @@ This guide will help you administer a standard installation of GIFramework Maps, either via the management interface (recommended) or via the database backend. +!!! warning + We **highly** reccommend you use the management interface. Incorrect editing of the database directly can result in a broken application. + * [Adminstration via the management interface](gui/getting-started.md) * [Administration via the backend database (advanced)](db/getting-started.md) diff --git a/docs/stylesheets/custom.css b/docs/stylesheets/custom.css index 59fa5c3..f54772e 100644 --- a/docs/stylesheets/custom.css +++ b/docs/stylesheets/custom.css @@ -1,7 +1,9 @@ :root { - --md-primary-fg-color: #05476d; - --md-primary-fg-color--light: #00598c; - --md-primary-fg-color--dark: #022e47; + --md-primary-fg-color: #05476d; + --md-accent-fg-color: #DE4259; + } + [data-md-color-scheme="slate"] { + --md-typeset-a-color: #DE4259; } body{ font-family: system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",Arial,"Noto Sans","Liberation Sans",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji"; diff --git a/mkdocs.yml b/mkdocs.yml index e30b97c..8d36c2b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,14 +10,30 @@ theme: features: - navigation.instant palette: - - scheme: default + # Palette toggle for automatic mode + - media: "(prefers-color-scheme)" + primary: custom + accent: custom toggle: - icon: material/weather-night - name: Switch to dark mode - - scheme: slate + icon: material/brightness-auto + name: Switch to light mode + + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + primary: custom + accent: custom toggle: icon: material/weather-sunny - name: Switch to light mode + name: Switch to dark mode + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: custom + accent: custom + toggle: + icon: material/weather-night + name: Switch to system preference markdown_extensions: - toc: permalink: true @@ -28,8 +44,8 @@ markdown_extensions: - pymdownx.details - pymdownx.superfences - pymdownx.emoji: - emoji_index: !!python/name:materialx.emoji.twemoji - emoji_generator: !!python/name:materialx.emoji.to_svg + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg extra: social: - icon: fontawesome/brands/github @@ -37,7 +53,7 @@ extra: copyright: All content is available under the Open Government Licence v3.0 except where otherwise stated nav: - Home: 'index.md' - - 'Administration via the GUI': + - 'Administration via the management interface': - 'Getting started': 'gui/getting-started.md' - 'Atttributions': 'gui/attributions.md' - 'Bounds': 'gui/bounds.md' @@ -60,6 +76,7 @@ nav: - 'Categories': 'db/categories.md' - 'Layers': 'db/layers.md' - 'Print Configuration': 'db/print-config.md' + - 'Projections': 'db/projections.md' - 'Proxying': 'db/proxy.md' - 'Search Definitions': 'db/search-definitions.md' - 'Theming': 'db/theming.md'