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:

Create a QGIS project and deploy it to QGIS Server
Writing the QWC2 theme configuration
Generating the themes configuration

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 QWC2:

What	Where	Description
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.
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 QWC2.
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 QWC2. 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 (defaultMapCrs, defaultBackgroundLayers, etc.) as desired in qwc-docker/volumes/config-in/<tentant>/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/<tentant>/themesConfig.json.

Manual theme configuration ¶

The theme configuration file is located as follows:

Standalone viewer: qwc2-app/themesConfig.json
qwc-docker: qwc-docker/volumes/config-in/<tentant>/themesConfig.json

Note: when using qwc-docker, the themes configuration may also be embedded as themesConfig directly in qwc-docker/volumes/config-in/<tentant>/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>,
        "items": [{ <ThemeDefinition> }, ...],
        "groups": [ { <Group> }, ...]
        },
        ...
    ],
    "externalLayers": [
      { <ExternalLayerDefinition> },
      ...
    ],
    "themeInfoLinks": [
      { <ThemeInfoLinkDefinition> },
      ...
    ],
    "pluginData": {
      "<PluginName>": [{ <PluginDataReource>}, ...],
      ...
    },
    "backgroundLayers": [
      { <BackgroundLayerDefinition> },
      ...
    ],
  },
  "defaultMapCrs": "<Default map crs, defaults to EPSG:3857>",
  "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>],
  "defaultPrintGrid": [<Print grid, see theme definition below>],
  "defaultTheme": "<Default theme id>"
}

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.

The format of the theme definitions is as follows:

Entry	Description
`"id": "<id>",`	Theme identificator. Autogenerated if not specified.
`"url": "<WMS URL>",`	The address of desired WMS served by QGIS Server.
`"mapCrs: "<EPSG code>",`	Optional, map projection, defaults to `defaultMapCrs`.
`"title": "<Custom title>",`	Optional, override WMS title.
`"description": "<Description>",`	Optional, an additional description to show below the theme title.
`"thumbnail": "<Filename>",`	Optional, image file in `assets/img/mapthumbs` (see Viewer assets). If omitted, `<project_basename>.png` will be used if it exists below `assets/img/mapthumbs`, otherwise it is autogenerated via WMS GetMap.
`"attribution": "<Attribution>",`	Optional, attribution which will be shown in the bottom right corner of the map.
`"attributionUrl": "<URL>",`	Optional, link associated to the attribution
`"scales": [<Scale denominators>],`	List of denominators of allowed map scales. If omitted, defaults to `defaultScales`.
`"printScales": [<Scale denominators>],`	List of denominators of allowed print scales. If omitted, defaults to `defaultPrintScales`.
`"printResolutions": [<DPIs>],`	List of available print resolutions. If omitted, defaults to `defaultPrintResolutions`.
`"printGrid": [`	List of grid scale-dependent grid intervals to use when printing. If omitted, defaults to `defaultPrintGrid`.
`⁣ {"s": <Scale1>, "x": <Width1>, "y": <Height1>},`	Keep this list sorted in descending order by scale denominator.
`⁣ {"s": <Scale2>, "x": <Width2>, "y": <Height2>}`	In this example, `{x: <Width2>, y: <Height2>}` will be used for `<Scale1> > Scale >= <Scale2>`.
`],`
`"defaultPrintLayout": "<ID>",`	Optional, name print layout to select by default.
`"printLabelForSearchResult": "<ID>",`	Optional, an ID of a print layout label to which the current search result text (if any) will be written to when printing.
`"printLabelForAttribution": "<ID>",`	Optional, an ID of a print layout label to which the current attribution text (if any) will be written to when printing.
`"printLabelConfig": {`	Optional, configuration of the text input fields for print layout labels.
`⁣ "<LabelId>": {`
`⁣ ⁣ "defaultValue": "<value">,`	Optional, default value.
`⁣ ⁣ <textarea config>,`	Optional, additional `textarea` properties, i.e. `maxLength`, `rows`, `placeholder`, ...
`⁣ ⁣ "options": ["<value1>","<value2>",...]`	Optional, to display a ComboBox with the specified options instead of a free-input textfield.
`},`
`"extent": [<xmin>, <ymin>, <xmax>, <ymax>],`	Optional, override theme extent. In `mapCrs`.
`"tiled": <boolean>,`	Optional, use tiled WMS, defaults to `false`.
`"tileSize": [<tile_width>, <tile_height>]`	Optional, the WMS tile width and height.
`"format": "<mimetype>",`	Optional, the format to use for WMS GetMap. Defaults to `image/png`.
`"externalLayers": [{`	Optional, external layers to use as replacements for internal layers.
`⁣ "name": "<external_layer_name>",`	Name of the external layer, matching a `ExternalLayerDefinition`, see below.
`⁣ "internalLayer": "<QGis_layer_name>"`	Name of an internal layer, as contained in the QGIS project, to replace with the external layer.
`}],`
`"themeInfoLinks": {`	Optional, custom links to additional resources, shown as a menu in the theme selector in the theme switcher.\
`⁣ "title": "<Menu title>",`	An arbitrary string shown as title of the menu.
`⁣ "titleMsgId": "<Menu title msgID>",`	Alternative to `title`, a message ID, translated through the translation files.
`⁣ "entries": ["<link_name>", ...]`	List of theme info link names, see below.
`},`
`"backgroundLayers": [{,`	Optional, list of available background layers, defaults to `defaultBackgroundLayers`.
`⁣ "name": "<Background layer name>",`	Name of matching `BackgroundLayerDefinition`, see below.
`⁣ "printLayer": "<layer name>"\\|[<list>],`	Optional, a QGIS layer name or layer resource string to use as matching background layer when printing. Alternatively, a list `[{"maxScale": <scale>, "name": "<layer name>"}, ..., {"maxScale": null, "name": "<layer name>"}]` can be provided, ordered in ascending order by `maxScale`. The last entry should have `maxScale` `null`, as the layer used for all remaining scales. If omitted, no background is printed, unless layer is of type `wms` and `printExternalLayers` is `true` in the Print plugin configuration. See Printing.
`⁣ "visibility": <boolean>`,	Optional, initial visibility of the layer when theme is loaded.
`⁣ "overview": <boolean>`,	Optional, set the layer as the overview map layer (i.e. this layer will be displayed in the overview map regardless of the background layer visible in the main map).
`}],`
`"searchProviders": ["<Provider>"],`	Optional, list of search providers, see Search. Defaults to `defaultSearchProviders`.
`"minSearchScaleDenom": <number>,`	Optional, minimum scale to enforce when zooming to search results. Takes precedence over value in `config.json`.
`"featureReport": {`	Optional, available feature report templates.
`⁣ "<LayerId>": "<TemplateID>"`	WMS sublayer ID and associated template ID to pass to the `featureReportService`.
`},`
`"additionalMouseCrs": ["<EPSG code>"],`	Optional, list of additional projections for displaying the mouse position. WGS84 and `mapCrs` are available by default. Additional projections definitions must be added to `config.json`.
`"watermark": {`	Optional, configuration of watermark to add to raster export images.
`⁣ "text": "<text>",`	Arbitrary text.
`⁣ "texpadding": <number>,`	Optional, padding between text and frame, in points.
`⁣ "fontsize": <number>,`	Optional, font size.
`⁣ "fontfamily": "<Font family>",`	Optional, font family.
`⁣ "fontcolor": "#RRGGBB",`	Optional, font color.
`⁣ "backgroundcolor": "#RRGGBB",`	Optional, frame background color.
`⁣ "framecolor": "#RRGGBB",`	Optional, frame color.
`⁣ "framewidth": <number>,`	Optional, frame width.
`},`
`"collapseLayerGroupsBelowLevel": <level>,`	Optional, layer tree level below which to initially collapse groups. By default the tree is completely expanded.
`"skipEmptyFeatureAttributes": <boolean>,`	Optional, whether to skip empty attributes in the identify results. Default is `false`.
`"mapTips": <boolean>\|null,`	Optional, per-theme setting whether map-tips are unavailable (`null`), disabled by default (`false`) or enabled by default (`true`).
`"extraLegendParameters": "<&KEY=VALUE>",`	Optional, additional query parameters to append to GetLegendGraphic request.
`"extraDxfParameters": "<&KEY=VALUE>",`	Optional, additional query parameters to append to DXF export request.
`"extraPrintParameters": "<&KEY=VALUE>",`	Optional, additional query parameters to append to GetPrint request (requires QGIS Server >= 3.32.0).
`"extraPrintLayers": ["<layername>", ...],`	Optional, extra list of layers to mark as internal print layers, i.e. which are omitted from the QWC2 LayerTree.
`"printLabelBlacklist": ["<LabelId>", ...]`	Optional, list of composer label ids to not expose in the print dialog.
`"editConfig": "<editConfig.json>"`	Optional, object or path to a filename containing the editing configuration for the theme, see Editing.
`"snapping": {...},`	Optional, snapping configuration, see Snapping.
`"flags": ["<flag1>", "<flag2>", ...],`	Optional, list of arbitrary flag names. The visibility of menu items, toolbar items and map buttons can be controlled based on the flags a theme declares. See Plugin Configuration.
`"config": {`	Optional, per-theme configuration entries which override the global entries in `config.json`, see Viewer Configuration.
`⁣ "<...>": ...,`	Global config settings overridden in theme, see `config.json`.
`⁣ "plugins": {...},`	Plugin configuration overridden in theme, See `config.json`.
`⁣ "desktop": {...},`	Desktop specific global and plugin configuration overridden in theme.
`⁣ "mobile": {...}`	Mobile specific global and plugin configuration overridden in theme.
`}`
`"pluginData": {`	Optional, data to pass to custom plugins.
`⁣ "<PluginName>": ["<plugin_data_resource_name>"],`	A list of plugin resource names for the specified plugin. See below.
`⁣ ...`
`},`
`"wmsBasicAuth": "{`	Optional, allows to authenticate to QGIS Server during themes.json generation. NOTE: these credentials will solely be used by `yarn run themesConfig` and won't be stored in `themes.json`.
`⁣ "username": <username>`	Optional: http basic authentication username.
`⁣ "password": <password>`	Optional: http basic authentication password.
`},`
`"layerTreeHiddenSublayers": ["<layername>", ...]`,	Optional: list of sublayer names to omit in layertree (but still displayed in map).
`"predefinedFilters": [{<filter_config>}, ...]`,	Optional: predefined filter configuration, see MapFilter.

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.

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 QWC2 (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.

Theme info links ¶

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.
`"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`.
`"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.
`"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.
`"layerConfig": {...},`	Optional, extra OpenLayers layer configuration, according to the API of the specific layer type.
`"sourceConfig": {...},`	Optional, extra OpenLayers source configuration, according to the API of the specific source type.
`<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",
  "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, which will then be resolved at runtime. 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",
    "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 QWC2 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/<tentant>. You can then inspect the generated themes.json at http://localhost:8088/themes.json.
When using QWC2 as a standalone viewer, the themes.json can be generated by invoking

yarn run themesconfig

Note: this command is automatically invoked when starting the development server via yarn 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 QWC2.

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:

Download the split_categorized, i.e. to volumes/qgis-server-plugins/split_categorized and configure the qwc-qgis-server container as follows:

  qwc-qgis-server:
    image: docker.io/sourcepole/qwc-qgis-server:<TAG>
    volumes:
      - ./volumes/qgis-server-plugins/split_categorized:/usr/share/qgis/python/plugins/split_categorized:ro
    ...

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.