Themes configuration

A theme corresponds to a QGIS project, published as WMS and served by QGIS Server.

The basic steps for configuring a theme are:

Creating and publishing a QGIS project

The first step is to prepare a QGIS project for publishing. Besides the common tasks of adding and styling layers, the following table gives an overview of settings which influence how the theme is displayed in QWC:

What Where Description
Map projection Project Properties → CRS Map projection used in QWC.
Service Metadata Project Properties → QGIS Server → Service capabilities Shown in the theme info dialog, invokable from the Layer Tree panel titlebar.
Title, keywords Project Properties → QGIS Server → Service capabilities Theme title, displayed in the Theme Switcher, and keywords, useful for filtering.
Map extent Project Properties → QGIS Server → WMS → Advertised extent The extent used as initial map extent when loading the theme, unless overridden in themesConfig.json.
Queryable layers Project Properties → Data sources Mark layers as identifyable by the client.
FeatureInfo geometry Project Properties → QGIS Server → WMS Capabilities → Add geometry to feature response Return feature geometries with the GetFeatureInfo request. Allows the client to highlight the selected features.
Layer Display Field Vector Layer Properties → Display The field used in the identify results.
Layer Map Tip Vector Layer Properties → Display The contents of the Map Tip shown when hovering over layers in the client, if displaying Map Tips is enabled in the Layer Tree.
Layer Metadata Layer Properties → QGIS Server Shown in the client Layer Info dialog, invokable from the Layer Tree.
Scale range Layer Properties → Rendering → Scale dependent visibility The scale range within which a layer is visible, useful to improve rendering performance.
Refresh interval Layer Properties → Rendering → Refresh layer at interval Automatic layer refresh interval.
Initial visibility Layers Panel Initial visibility of layers and groups.
Rendering order Layer Order Panel or Layers Panel Rendering order of the layers. If layer re-ordering is enabled in config.json, the order from the Layer Order Panel is ignored.
Print layouts Layout manager The print layouts offered in the Print plugin.
Print layout labels Layout manager Print layout labels with an ID will be exposed in the Print plugin. Note: a label ID starting with __ will not be exposed.
Attribute form Vector Layer Properties → Attributes Form The configured attribute form will be displayed when editing in QWC.
External layers Layer Properties → QGIS Server → Data URL Mark the layer as an external layer to avoid cascaded requests. See Configuring external layers.

Then, store the project in the publishing directory of your QGIS Server instance. When using qwc-docker, store the project as *.qgs below qwc-docker/volumes/qgs-resources.

Alternatively, when using qwc-docker, you can also store the project in a database in QGIS using Project → Save To → PostgreSQL (see Storing projects in database).

Ensuring valid datasources

A common issue is that the project will reference datasources in locations which cannot be resolved when QGIS Server reads the project, in particular when running QGIS Server inside a docker container. To avoid such issues:

  • Make sure that any file-based resources are located on the same level or below the level of the *.qgs project file. Remember to copy all resources along with the *.qgs project file to the server.
  • Load any PostgreSQL datasource in QGIS using a service, and make sure the service definition exists both in the pg_service.conf on your host system as well as in the qwc_docker/pg_service.conf and qwc_docker/pg_service-write.conf which are mounted inside the docker containers. For instance, to use default qwc-docker database, use the qwc_geodb service and add the service definition to your host pg_service.conf as follows:
[qwc_geodb]
host=localhost
port=5439
dbname=qwc_demo
user=qwc_service
password=qwc_service
sslmode=disable

Configuring the themes in themesConfig.json

The next step is to configure the theme for QWC. There are two approaches:

  • Automatic theme configuration (only when using qwc-docker): Just copy the project file to the designated location and the qwc-config-generator will automatically generate a theme configuration using default parameters.
  • Manual theme configuration: Manually configure a theme with the full set of configuration options.

Automatic theme configuration

When using qwc-docker, save your QGIS projects below qwc-docker/volumes/qgs-resources/scan. Adjust the default settings (defaultBackgroundLayers, defaultSearchProviders, etc.) as desired in qwc-docker/volumes/config-in/<tenant>/themesConfig.json. Then generate the theme configuration.

You can configure an automatically configured theme as default theme by setting defaultTheme in themesConfig.json to the path to the QGIS project file below qwc-docker/volumes/qgs-resources, without the .qgs extension. For example to set qwc-docker/volumes/qgs-resources/scan/project.qgs as default theme, you'd write

...
"defaultTheme": "scan/project"
...

To use a custom thumbnail for an automatically configured theme, place a an image called <project_basename>.png in qwc-docker/volumes/qwc2/assets/img/mapthumbs. For example. if the project is called project_name.qgs, the name thumbnail image would be named project_name.png.

Note: The auto-scan directory can be is controlled by qgis_projects_scan_base_dir in qwc-docker/volumes/config-in/<tenant>/themesConfig.json.

Manual theme configuration

The theme configuration file is located as follows:

  • Standalone viewer: qwc-app/static/themesConfig.json
  • qwc-docker: qwc-docker/volumes/config-in/<tenant>/themesConfig.json

Note: when using qwc-docker, the themes configuration may also be embedded as themesConfig directly in qwc-docker/volumes/config-in/<tenant>/tenantConfig.json.

The themesConfig.json file contains a list of themes, optionally organized in groups, as well as a list of background layers:

{
  "themes": {
    "items": [
      { <ThemeDefinition> },
      ...
    ], "groups": [
      {
        "title": "<Group title>",
        "titleMsgId": "<Group title translation msgID>",
        "items": [{ <ThemeDefinition> }, ...],
        "groups": [ { <Group> }, ...]
        },
        ...
    ],
    "externalLayers": [
      { <ExternalLayerDefinition> },
      ...
    ],
    "themeInfoLinks": [
      { <ThemeInfoLinkDefinition> },
      ...
    ],
    "pluginData": {
      "<PluginName>": [{ <PluginDataReource>}, ...],
      ...
    },
    "backgroundLayers": [
      { <BackgroundLayerDefinition> },
      ...
    ],
  },
  "defaultBackgroundLayers": "<Default background layers, see theme definition below>",
  "defaultWMSVersion": "<Default WMS version, i.e. 1.3.0>",
  "defaultScales": [<Scale denominators, see theme definition below>],
  "defaultPrintScales" [<Scale denominators, see theme definition below>],
  "defaultPrintResolutions": [<DPIs, see theme definition below>],
  "defaultSearchProviders": [<Search providers, see theme definition below>],
  "defaultMapTips": <boolean>|null,
  "defaultMapCrs": "<EPSG:XXXX>",
  "defaultMapExtent": [xxmin>, <ymin>, <xmax>, <ymax>],
  "defaultPrintGrid": [<Print grid, see theme definition below>],
  "defaultLabelProfiles": {<Label profiles, see theme definition below>},
  "defaultTheme": "<Default theme id>"
}

The defaultMapCrs, defaultMapExtent, defaultScales and defaultBackgroundLayers will also be used to construct an empty theme, if there is no default theme resp. if the default theme cannot be loaded. The defaultMapExtent should be specified in the CRS specified in defaultMapCrs. If latter is not defined, it is assumed to be EPSG:3857.

Refer to External layers, Theme info links, Plugin data and Background layers for the format of the respective definitions.

Refer to the sample themesConfig.json for a complete example.

A bare minimum theme entry might look as follows:

{
  "id": "theme_id",
  "title": "My theme",
  "url": "/ows/my_theme",
  "mapCrs": "EPSG:3857",
  "backgroundLayers": [{"name": "background_layer_name"}],
  "searchProviders" ["coordinates"]
}

Note:

  • The theme identifier id can be freely defined and will appear in the viewer URL as the t query parameter.
  • When using qwc-docker, the url can be specified as /ows/<relative_path_to_qgs> where relative_path_to_qgs is the path to the QGIS project file below qwc-docker/volumes/qgs-resources, without the .qgs extension. In the above sample, the project file would be located at qwc-docker/volumes/qgs-resources/my_theme.qgs.

The format of the theme definitions is as follows:

Field Type Description
additionalMouseCrs array of string Additional projections for displaying the mouse position, as EPSG codes. WGS84 and mapCrs are available by default, other projections must be defined in config.json.
attribution string Attribution shown in the bottom right corner of the map.
attributionUrl string Link of the attribution.
backgroundLayers array of Theme background layer Available background layers, defaults to defaultBackgroundLayers.
collapseLayerGroupsBelowLevel integer Layer tree level below which groups are initially collapsed. By default the tree is completely expanded.
config object Viewer configuration overriding the global entries of config.json for this theme, including desktop, mobile and plugins entries.
default boolean Use this theme as default theme.
defaultDisplayCrs string Default CRS for the coordinates in the bottom bar and in measurements, defaults to mapCrs.
defaultPrintLayout string Name of the print layout selected by default.
description string Additional description, shown below the theme title.
disabled boolean Skip this theme when generating the themes configuration. Default: false.
editConfig one of Editing configuration, keyed by layer name, or the path of a file containing it. Usually generated by the config generator.
    Configuration object
    File path string
extent array of number [4] Initial extent as [xmin, ymin, xmax, ymax] in mapCrs, overrides the extent advertised by the WMS.
externalLayers array of object External layers replacing internal layers of the project.
    internalLayer string Name of the project layer to replace. Required.
    name string Name of the matching external layer definition in themes.externalLayers. Required.
extraLegendParameters string Additional query parameters of the GetLegendGraphic requests, as KEY=VALUE&KEY2=VALUE2.
extraPrintLayers array of string Additional layers marked as internal print layers, omitted from the layer tree.
extraPrintParameters string Additional query parameters of the GetPrint requests, as KEY=VALUE&KEY2=VALUE2 (QGIS Server 3.32 or later).
extraPrintTemplates array of string Paths of additional print templates added to the theme, relative to the print layouts directory.
featureInfoUrl string Base URL of the GetFeatureInfo requests, only used by the qwc2 scripts.
featureReport map Feature report templates of the document service, keyed by sublayer name.
    <key> one of
        Template name string
        Reports array of object
            format string Report format, e.g. pdf, html, csv, docx, ods, odt, pptx, rtf, xlsx or xml. Default: "pdf".
            single_report boolean Compile one report for all features instead of one report per feature. Default: false.
            template string Report template name. Required.
            title string Report title.
filter object Fixed filter applied to the theme.
    layerfilter object Filter expression per layer name, in the format of the MapFilter plugin.
flags array of string Arbitrary flags, used to show or hide menu items, toolbar items and map buttons.
format string Image format of the WMS GetMap requests. Default: "image/png".
hidden_in_ows_landing_page boolean Hide the service from the OGC service landing page. Default: false.
id string Theme identifier, used in the t URL parameter of the viewer. Generated if not specified.
labelProfiles map Labelling profiles of the Redlining plugin, keyed by layer name.
    <key> array of object Profiles of the layer.
        expression string Label expression, in QGIS expression syntax.
        name string Profile name. Required.
        size number Label size. Default: 1.
        title string Profile title, defaults to the name.
layerTreeHiddenSublayers array of string Sublayers omitted from the layer tree, but still displayed in the map.
legendUrl string Base URL of the GetLegendGraphic requests, only used by the qwc2 scripts.
lockedVisibilityPreset string Visibility preset (QGIS map theme) whose layer styles are locked.
map3d Theme 3D view 3D view configuration of a theme. When present, a map button switching to the 3D view is displayed.
mapCrs string Map projection as EPSG code, defaults to the project projection. The projection must be defined in config.json.
mapExtent array of number [4] Full allowed extent of the map as [xmin, ymin, xmax, ymax] in mapCrs.
mapTips boolean | null Whether map tips are enabled by default. If null or not set, defaultMapTips applies.
minSearchScaleDenom number Minimum scale denominator when zooming to search results, overrides the value of config.json.
obliqueDatasets array of object Oblique aerial imagery datasets.
    backgroundLayer string Name of the background layer displayed with the dataset.
    backgroundOpacity integer Opacity of the background layer, from 0 (transparent) to 255 (opaque). Default: 127.
    dataset string Dataset configured in the obliqueImagery service. Required.
    default boolean Display this dataset by default, otherwise the first one is used.
    title string Title in the dataset switcher, defaults to the dataset.
    titleMsgId string Translation message ID of the title, alternative to title.
pluginData map Data passed to custom plugins: names of the matching plugin data resources in themes.pluginData, keyed by plugin name.
    <key> array of string Plugin data resource names.
predefinedFilters array of Predefined filter Predefined filters of the MapFilter plugin.
printGrid array of object Scale dependent grid intervals for printing, in descending order by scale denominator: an entry applies to the scales between its own and the next entry's scale denominator.
    s number Scale denominator. Required.
    x number Grid interval in x direction. Required.
    y number Grid interval in y direction. Required.
printLabelBlacklist array of string IDs of the print layout labels not exposed in the print dialog.
printLabelConfig map Input configuration of the print layout labels, keyed by label ID.
    <key> object Label input configuration, with any additional textarea property, e.g. maxLength, rows or placeholder.
        defaultValue string Default value. Can contain the placeholders {username} and {user_infos.<field>}, which are replaced with the values of the logged in user.
        hidden boolean Whether to hide the field from the user and submit the default value.
        options array of string Options of a combo box, displayed instead of a text field.
printLabelForAttribution string ID of the print layout label receiving the current attribution when printing.
printLabelForSearchResult string ID of the print layout label receiving the current search result when printing.
printResolutions array of number Available print resolutions in DPI, defaults to defaultPrintResolutions. If empty, the resolution can be freely chosen.
printScales array of number Allowed print scale denominators, defaults to defaultPrintScales.
printTemplateBlacklist array of string Print templates to ignore.
printUrl string Base URL of the GetPrint requests, only used by the qwc2 scripts.
scales array of number Allowed map scale denominators, defaults to defaultScales.
searchProviders array of Search provider Search providers, defaults to defaultSearchProviders.
skipEmptyFeatureAttributes boolean Skip empty attributes in the identify results. Default: false.
snapping object Snapping configuration.
    featureCount integer Maximum number of snapping geometries retrieved for the current map extent. Default: 500.
    snaplayers array of object Layers to snap to. Required.
        max number Maximum scale denominator at which snapping is active.
        min number Minimum scale denominator at which snapping is active.
        name string Name of the sublayer providing the snapping geometries. Required.
    wfsMaxScale number Scale denominator below which loaded WFS layers are used for snapping.
startupView string View mode in which the theme is initially displayed. One of "2d", "3d", "3d2d", "oblique". Default: "2d".
themeInfoLinks object Links shown as a menu next to the theme in the theme switcher.
    entries array of string Names of the matching link definitions in themes.themeInfoLinks.
    title string Menu title.
    titleMsgId string Translation message ID of the menu title, alternative to title.
thumbnail string Image file in assets/img/mapthumbs. If omitted, <project_basename>.png is used if it exists, otherwise the thumbnail is generated with a WMS GetMap.
tiled boolean Use tiled WMS requests. Default: false.
tileSize array of integer [2] WMS tile width and height.
title string Theme title, overrides the WMS title.
url string URL of the WMS served by QGIS Server. With qwc-docker, /ows/<path> where <path> is the path of the QGIS project below qgs-resources, without extension. Required.
version string WMS version, overrides defaultWMSVersion.
visibilityPresetsBlacklist array of string Visibility presets (QGIS map themes) to exclude, * matching any characters.
watermark object Watermark added to raster export images, each entry being passed as WATERMARK_<KEY> parameter of the export request.
    backgroundcolor string Frame background color, as #RRGGBB.
    fontcolor string Font color, as #RRGGBB.
    fontfamily string Font family.
    fontsize one of Font size.
        Number number
        Text string
    framecolor string Frame color, as #RRGGBB.
    framewidth one of Frame width.
        Number number
        Text string
    texpadding one of Padding between the text and the frame, in points.
        Number number
        Text string
    text string Text.
wmsBasicAuth object HTTP basic authentication credentials for QGIS Server, only used when generating the themes configuration with the qwc2 scripts and not stored in themes.json.
    password string Password.
    username string User name.
wmsOnly boolean Only configure the entry as a WMS, not as a theme. Default: false.

Theme background layer

Reference to a background layer definition, as listed in the backgroundLayers of a theme.

Field Type Description
name string Name of the matching background layer definition in themes.backgroundLayers. Required.
omitFromCycle boolean Exclude the layer when cycling through the background layers.
omitFromSelect boolean Hide the layer from the background layer selection.
overview boolean Set the layer as the overview map layer, i.e. it is displayed in the overview map regardless of the background layer visible in the main map.
printLayer one of QGIS layer name or layer resource string to use as matching background layer when printing. Alternatively, a list of layers by scale, ordered in ascending order by maxScale, whose last entry has a null maxScale and is used for all remaining scales. If omitted, no background is printed, unless the layer is of type wms and printExternalLayers is true in the Print plugin configuration.
    Layer name string
    Layers by scale array of object
        maxScale number | null Scale denominator up to which this layer is used, null or omitted for the last entry.
        name string QGIS layer name or layer resource string. Required.
visibility boolean Initial visibility of the layer when the theme is loaded.

Theme 3D view

3D view configuration of a theme. When present, a map button switching to the 3D view is displayed.

Field Type Description
basemaps array of Theme background layer Background layers of the 3D view.
dtm object Terrain model.
    crs string CRS of the terrain model. Default: "EPSG:3857".
    max number Maximum elevation, used together with min.
    min number Minimum elevation, used together with max.
    url string URL of a cloud optimized GeoTIFF.
extent object Extent of the 3D view, defaults to the initial extent of the theme.
    bounds array of number [4] Extent as [xmin, ymin, xmax, ymax].
    crs string CRS of the bounds.
initialView object Initial view of the 3D view. If not set, the 3D view follows the 2D view.
    camera array of number [3] Camera position as [x, y, z].
    personHeight number Person height, activates the first person view when greater than 0.
    target array of number [3] Camera target as [x, y, z].
objects array of one of Scene objects: 3D tiles, GLTF objects and groups.
    3D tiles object
        name string Unique name, also used for the 3D object permissions. Required.
        title string Title, defaults to the name.
        visibility boolean Initial visibility. Default: true.
        alphaAttr string Feature attribute storing the feature alpha as integer between 0 and 255.
        baseColor string Fallback color of the tile objects, as CSS color, white if another style attribute is set.
        colorAttr string Feature attribute storing the feature color as 0xRRGGBB integer.
        idAttr string Feature attribute storing the object ID. Default: "id".
        infoAttrBlacklist array of string Feature attributes to omit from the identify results.
        labelAttr string Feature attribute storing the feature label, displayed above the geometry.
        snap boolean Include the tileset in the snappable scene objects when drawing. Default: true.
        style string Tileset style enabled by default, defaults to the first style.
        styles map Available tileset styles, tileset style URL keyed by style name. Takes precedence over colorAttr, alphaAttr and labelAttr.
            <key> string
        url string URL of the tileset.json. Required.
        type "tiles3d" Entry type. Required.
    GLTF object object
        name string Unique name, also used for the 3D object permissions. Required.
        title string Title, defaults to the name.
        visibility boolean Initial visibility. Default: true.
        snap boolean Include the object in the snappable scene objects when drawing. Default: true.
        url string URL of the GLTF file. Required.
        type "object3d" Entry type. Required.
    Group object
        name string Unique name, also used for the 3D object permissions.
        title string Title, defaults to the name.
        visibility boolean Initial visibility. Default: true.
        expanded boolean Initially expand the group. Default: true.
        items array of one of Child entries. Same structure as objects, recursively. Required.
        mutuallyExclusive boolean Allow only one visible child. Default: false.
        type "group" Entry type. Required.
objects3d array of object Deprecated, use objects entries of type object3d.
    name string Unique name, also used for the 3D object permissions. Required.
    title string Title, defaults to the name.
    visibility boolean Initial visibility. Default: true.
    snap boolean Include the object in the snappable scene objects when drawing. Default: true.
    url string URL of the GLTF file. Required.
tiles3d array of object Deprecated, use objects entries of type tiles3d.
    name string Unique name, also used for the 3D object permissions. Required.
    title string Title, defaults to the name.
    visibility boolean Initial visibility. Default: true.
    alphaAttr string Feature attribute storing the feature alpha as integer between 0 and 255.
    baseColor string Fallback color of the tile objects, as CSS color, white if another style attribute is set.
    colorAttr string Feature attribute storing the feature color as 0xRRGGBB integer.
    idAttr string Feature attribute storing the object ID. Default: "id".
    infoAttrBlacklist array of string Feature attributes to omit from the identify results.
    labelAttr string Feature attribute storing the feature label, displayed above the geometry.
    snap boolean Include the tileset in the snappable scene objects when drawing. Default: true.
    style string Tileset style enabled by default, defaults to the first style.
    styles map Available tileset styles, tileset style URL keyed by style name. Takes precedence over colorAttr, alphaAttr and labelAttr.
        <key> string
    url string URL of the tileset.json. Required.

Predefined filter

Predefined filter of the MapFilter plugin, as listed in the predefinedFilters of a theme.

Field Type Description
defaultValues object Values used for the fields left empty, keyed by field ID.
fields array of object Input fields of the filter. Required.
    defaultValue one of Default value.
        Text string
        Number number
        Yes/no boolean
        None null
    id string Field ID, used as $<id>$ placeholder in the filter expressions. Required.
    inputConfig object Input configuration: any HTML input element property, e.g. {"type": "number", "min": 0}, with type select for a combo box or datetime for a date and time input. Required.
        options array of one of Options of a select input, either values or value/label pairs.
            Text value string
            Number value number
            Value and label object
                label string Option label.
                labelmsgid string Translation message ID of the option label, alternative to label.
                value one of Option value. Required.
                    Text string
                    Number number
        type string HTML input type, or select, or datetime.
    title string Field title.
    titlemsgid string Translation message ID of the field title, alternative to title.
filter map Data service filter expression per layer name, where $<field_id>$ placeholders are replaced by the field values, e.g. ["<name>", "<op>", "$<field_id>$"] or [[...], "and", [...]]. Required.
    <key> array
id string Filter ID, also used in the f URL parameter. Required.
title string Filter title.
titlemsgid string Translation message ID of the filter title, alternative to title.

Search provider

Search provider entry, as listed in the searchProviders of a theme: either a provider key, a QGIS feature search, or another provider with parameters.

Field Type Description
Provider key string Provider key, e.g. coordinates, nominatim, or the key of a custom provider.
QGIS feature search object
    key string Key to disambiguate multiple configurations of the same provider type.
    label string Provider label displayed in the provider selection menu.
    labelmsgid string Translation message ID of the provider label, alternative to label.
    params object QGIS feature search parameters. Required.
        default boolean Select the search by default in the FeatureSearch plugin.
        description string Text displayed above the search fields in the FeatureSearch plugin.
        expression map Filter expression per layer name: either a WMS GetFeatureInfo FILTER expression with $TEXT$ or $<FIELD>$ placeholders, or a data service filter expression.
            <key> one of
                WMS filter expression string
                Data service filter expression array
        featureCount integer Maximum number of returned features. Default: 100.
        featuresearch boolean Include the search in the FeatureSearch plugin. Default: true.
        fields map Input fields of the FeatureSearch plugin form, keyed by placeholder name.
            <key> object Input field.
                label string Field label.
                label_field string Feature property used as option label when options_query returns features.
                labelmsgid string Translation message ID of the field label, alternative to label.
                options one of For select fields, the list of values or of value/label pairs. For other fields, additional HTML input attributes, e.g. min and max.
                    Select options array
                    Input attributes object
                options_query string URL returning the options of a select field, where $<FIELD>$ placeholders are replaced by the current form values.
                order number Position of the field in the search form.
                type string HTML input type, or select for a combo box, or checkbox for a yes/no choice.
                value_field string Feature property used as option value when options_query returns features.
        group string Group name of the search in the FeatureSearch selection.
        resultTitle string Format string for the result title, with {layername} and {<fieldname>} placeholders.
        title string Search name, also used as result group title and for sorting in the FeatureSearch plugin.
        titlemsgid string Translation message ID of the search name, alternative to title.
    provider "qgis" Provider key. Required.
Other provider object
    key string Key to disambiguate multiple configurations of the same provider type.
    label string Provider label displayed in the provider selection menu.
    labelmsgid string Translation message ID of the provider label, alternative to label.
    params object Provider parameters. For fulltext: default (search facets enabled by default) and layers (facet enabled when a theme layer is visible, keyed by layer name). For nominatim: additional Nominatim API parameters, e.g. countrycodes.
    provider string Provider key, e.g. fulltext, nominatim or the key of a custom provider. Required.
Legacy entry object Deprecated entry identified by key without provider, as used by older applications. The standard search providers ignore it.
    key string Provider key. Required.
    label string Provider label.

External layers

External layers can be used to selectively replace layers in a QGIS project with a layer from an external source, for instance in the case of a WMS layer embedded in a QGIS project, to avoid cascading WMS requests. They are handled transparently by QWC (they are positioned in the layer tree identically to the internal layer they replace), but the GetMap and GetFeatureInfo requests are sent directly to the specified WMS Service.

Configuring external layers via Data Url

The simplest way to define an external layer is to set the "Data Url" for a layer in QGIS (Layer Properties → QGIS Server → Data Url) to a string of these forms

wms:<service_url>?<options>#<layername>
wmts:<capabilities_url>?<options>#<layername>
mvt:<tile_url>|<style_url>

For instance:

wms:http://wms.geo.admin.ch?tiled=false&infoFormat=application/geojson#ch.are.bauzonen
wmts:https://wmts10.geo.admin.ch/EPSG/2056/1.0.0/WMTSCapabilities.xml?crs=EPSG:2056#ch.swisstopo.swissboundaries3d-gemeinde-flaeche.fill
mvt:https://kataster.bev.gv.at/tiles/kataster/{z}/{x}/{y}.pbf|https://kataster.bev.gv.at/styles/kataster/style_vermv.json

Note: Support for WMTS/MVT in Data Url is currently only implemented when using qwc-docker.

Note: You can pass parameters which control the behaviour of the WMS client in QGIS Server by prefexing the parameters with extwms. when the layer is requested by QGIS Server, i.e. when printing. Example to override the step width/heigth of the QGIS WMS Client:

wms:http://wms.geo.admin.ch?extwms.stepWidth=4096&extwms.stepHeight=4096#ch.swisstopo.pixelkarte-farbe-pk1000.noscale

Manually configuring external layers

Rather than setting the "Data Url", you can provide a manual ExternalLayerDefinition as follows:

Entry Description
{
⁣  "name": "<external_layer_name>", The name of the external layer, as referenced in the theme definitions.
⁣  "type": "<layer_type>", Layer type, "wms" or "wmts"
⁣  "url": "<wms_baseurl>", The WMS URL or WMTS resource URL for the external layer.
}

For external WMS layers, the following additional parameters apply:

Entry Description
"params": { Parameters for the GetMap request.
⁣  "LAYERS": "<wms_layername>,...", Comma-separated list of WMS layer names.
⁣  "OPACITIES": "<0-255>,..." Optional, if WMS server supports opacities.
},
"featureInfoUrl": "<wms_featureinfo_baseurl>", Optional, base URL for WMS GetFeatureInfo, if different from url.
"legendUrl": "<wms_legendgraphic_baseurl>" , Optional, base URL for WMS GetLegendGraphic, if different from url.
"queryLayers": ["<wms_featureinfo_layername>", ...], Optional, list of GetFeatureInfo query layers, if different from params.LAYERS.
"infoFormats": ["<featureinfo_format>", ...] List of GetFeatureInfo query formats which the WMS service supports.

For external WMTS layers, the following additional parameters apply (you can use the qwc2/scripts/wmts_config_generator.py script to obtain these values):

Entry Description
"tileMatrixSet": "<tile_matrix_set_name>", The name of the tile matrix set.
"originX": <origin_x>, The X origin of the tile matrix.
"originY": <origin_y>, The Y origin of the tile matrix.
"projection": "EPSG:<code>", The layer projection.
"resolutions": [<resolution>, ...], The list of WMTS resolutions.
"tileSize": [<tile_width>, <tile_height>] The tile width and height.

You can specify links to display in an info-menu next to the respective theme title in the theme switcher entries.

The format of a ThemeInfoLinkDefinition is as follows:

Entry Description
"name": "<link_name>", The name of the link, as referenced in the theme definitions.
"title": "<link_title>", The title for the link, as displayed in the info menu of the theme entry in the theme switcher.
"url": "<link>", A link URL.
"target": "<link_target>" The link target, i.e. _blank.

Note: When using qwc-services, theme info links must be explicitly permitted by creating appropriate Theme info link resources and permissions in the qwc-admin-gui.

Plugin data

Plugin data is useful to provide a per-theme configuration for custom plugins. The format for a PluginDataReource is as follows:

Entry Description
"name": "<resource_name>", The name of the resource.
"...": ..., Arbitrary additional fields.

Note: When using qwc-services, theme plugin data entries must be explicitly permitted by creating appropriate Plugin data resources (as child of a respective Plugin resource) and permissions in the qwc-admin-gui.

Background layers

Background layers are handled completely client-side and do not appear in the layer tree.

The format of the background layer definitions is as follows:

Entry Description
"name": "<Name>", The name of the background layer, used in the theme definitions.
"title": "<Title>", The title of the background layer, as displayed in the background switcher.
"titleMsgId": "<Title msgID>", Alternative to title, a message ID, translated through the translation files.
"attribution": "<Attribution>", Optional, attribution which will be shown in the bottom right corner of the map.
"attributionUrl": "<URL>", Optional, link associated to the attribution
"group": "<GroupId>", Optional, a group ID string. Background layers with the same group ID will be grouped together in the background switcher.
"layerConfig": {...}, Optional, extra OpenLayers layer configuration, according to the API of the specific layer type.
"minScale": <min_scale>, Optional, minimum scale denominator from which to render the layer.
"maxScale": <max_scale>, Optional, maximum scale denominator from which to render the layer.
"opacity": <opacity>, Optional, the layer opacity (between 0 and 255). Default: 255.
"sourceConfig": {...}, Optional, extra OpenLayers source configuration, according to the API of the specific source type.
"thumbnail": "<Filename>", Optional, image file in assets/img/mapthumbs (see Viewer assets). Defaults to img/mapthumbs/default.jpg.
"type": "<Type>", The background layer type, i.e. wms or wmts.
<Layer params> Parameters according to the specified layer type.

Some minimal examples of supported background layers:

  • WMS:
{
  "name": "swissboundaries",
  "type":"wms",
  "url":"https://wms.geo.admin.ch",
  "projection:":"EPSG:2056",
  "params": {
    "LAYERS": "ch.swisstopo.swissboundaries3d-gemeinde-flaeche.fill",
    "VERSION": "1.3.0",
    ...
  }
}
  • WMTS:
{
  "name":"bluemarble",
  "type":"wmts",
  "url":"http://gibs.earthdata.nasa.gov/wmts/epsg3857/best/BlueMarble_ShadedRelief/default/{TileMatrixSet}/{TileMatrix}/{TileRow}/{TileCol}.jpeg",
  "bbox":{
    "bounds":[-180.0,-85.051129,180.0,85.051129],
    "crs":"EPSG:4326"
  },
  "originX":-20037508.34278925,
  "originY":20037508.34278925,
  "projection:":"EPSG:3857",
  "resolutions":[156543.03390625,78271.516953125,39135.7584765625,19567.87923828125,9783.939619140625,4891.9698095703125,2445.9849047851562,1222.9924523925781],
  "tileMatrixPrefix":"",
  "tileMatrixSet":"GoogleMapsCompatible_Level8",
  "tileSize":[256,256]
}

Note: You can use the helper python script located at qwc2/scripts/wmts_config_generator.py to easily generate WMTS background layer configurations.

  • OpenStreetMap:
  {
    "name":"mapnik",
    "type":"osm"
  }
  • Bing:
  {
    "name": "bing",
    "type": "bing",
    "apiKey": "<get from https://www.bingmapsportal.com/>",
    "imagerySet": "<Aerial|AerialWithLabelsOnDemand|RoadOnDemand|CanvasDark|OrdnanceSurvey>"
  }
  • XYZ:
  {
    "name": "OpenCycleMap",
    "type": "xyz",
    "url":"https://{a-c}.tile.thunderforest.com/cycle/{z}/{x}/{y}.png"
  }
  • VectorTiles: (note: if the tile projection is not EPSG:3857, you need to specifiy projection and tileGridConfig. If labels are cropped you could also set declutter to true)
  {
    "name": "mvt_example",
    "type": "mvt",
    "url": "http://foobar.baz/tileset/{z}/{x}/{y}.pbf",
    "style": "http://foobar.baz/style.json",
    "declutter": false,
    "projection": "EPSG:XXXX",
    "tileGridConfig": {
      "origin": [<x>, <y>],
      "resolutions": [<resolutions>]
    }
  }

Alternatively, WMS and WMTS background layers can also be defined specifiying a resource identifier. For example:

{
    "name":"ch.swisstopo.pixelkarte-grau",
    "title":"National map (gray)",
    "resource": "wmts:https://wmts10.geo.admin.ch/EPSG/2056/1.0.0/WMTSCapabilities.xml#ch.swisstopo.pixelkarte-grau",
    "projection": "EPSG:2056",
    "thumbnail":"img/mapthumbs/default.jpg"
}

A background layer definition can also be a group of layers, in the format

{
  "name": "<Name>",
  "title": "<Title>",
  "type": "group",
  "items": [
    { <BackgroundLayerDefinition> },
    { <BackgroundLayerDefinition> },
    ...
  ]
}

Instead of specifiying a full background layer definition in a group, you can also reference an existing one with "ref": "<bg_layer_name>", and selectively override certain properties, such as minScale and maxScale:

{
  ...
  "items": [
    {
      "ref": "<bg_layer_name>",
      "minScale": <min_scale>,
      "maxScale": <max_scale>
    },
    ...
  ]
}

Generating the themes configuration

The file ultimately read by the QWC viewer is the themes.json configuration, which includes the contents of themesConfig.json completed with additional data obtained from the QGIS Project.

  • When using qwc-docker, you can generate the themes from the qwc-admin-gui administration backend, running on http://localhost:8088/qwc_admin by default. Log in as admin user, then press the green Generate service configuration button. This will invoce theqwc-config-generator, which will generate mapViewerConfig.json located below qwc-docker/volumes/config/<tenant>. You can then inspect the generated themes.json at http://localhost:8088/themes.json.

  • When using QWC as a standalone viewer, the themes.json can be generated by invoking

npm run themesconfig

Note: this command is automatically invoked when starting the development server via npm start.

If working in an environment without node, using the equivalent command

python3 qwc2/scripts/themesConfig.py

If you want to manage multiple themesConfig.json files, you can specify which while should be processed by the theme generation script via the QWC2_THEMES_CONFIG environment variable.

Storing projects in database

When you are using qwc-docker, you can configure QWC to read the QGIS projects directly from the database. To do this, proceed as follows:

  • Set up a PostgreSQL database connection in QGIS, checking the "Allow saving/loading QGIS projects in the database" option.
  • Save the project to the configured database in QGIS using Project → Save To → PostgreSQL.
  • Add a qgisprojects service definition for the used database to qwc-docker/pg_service.conf.
  • Write a theme configuration entry in themesConfig.json using with "url": "/ows/pg/<schema>/<projectname>", where schema and projectname as as specified when saving the project in QGIS.

Using the QGZ project file format

You can configure qwc-docker to look for qgz project files instead of qgs project files as follows:

  • Set qgis_project_extension to .qgz in the toplevel config section of tenantConfig.json.
  • If using qwc-docker, set QGIS_PROJECT_SUFFIX=qgz in the qwc-qgis-server environment in docker-compose.yml.

Split categorized layers

By default, symbol categories of a classified layer won't be exposed via WMS and hence in QWC.

To expose symbol categories as separate layers via WMS, you can use the split_categorized QGIS Server plugin.

To configure the plugin in qwc-docker, proceed as follows:

  • Enable the split_categorized in the qwc-qgis-server container as follows:
  qwc-qgis-server:
    image: docker.io/sourcepole/qwc-qgis-server:<TAG>
    environment:
      ENABLED_PLUGINS: '["split_categorized"]'
    ...
  • For all layers that you want to split, create the variable convert_categorized_layer and set it to true.

  • Generate the themes configuration.

Note: ELSE symbol rules are currently unsupported, respectively will display the entire layer contents.