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 theqwc_docker/pg_service.conf
andqwc_docker/pg_service-write.conf
which are mounted inside the docker containers. For instance, to use defaultqwc-docker
database, use theqwc_geodb
service and add the service definition to your hostpg_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 theqwc-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 an empty list, resolutions are freely choseable. 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>} |
Optional, object 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 thet
query parameter. - When using
qwc-docker
, theurl
can be specified as/ows/<relative_path_to_qgs>
whererelative_path_to_qgs
is the path to the QGIS project file belowqwc-docker/volumes/qgs-resources
, without the.qgs
extension. In the above sample, the project file would be located atqwc-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 specifiyprojection
andtileGridConfig
. If labels are cropped you could also setdeclutter
totrue
)
{
"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 theqwc-admin-gui
administration backend, running on http://localhost:8088/qwc_admin by default. Log in asadmin
user, then press the greenGenerate service configuration
button. This will invoce theqwc-config-generator
, which will generatemapViewerConfig.json
located belowqwc-docker/volumes/config/<tentant>
. You can then inspect the generatedthemes.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 toqwc-docker/pg_service.conf
. - Write a theme configuration entry in
themesConfig.json
using with"url": "/ows/pg/<schema>/<projectname>"
, whereschema
andprojectname
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 toplevelconfig
section oftenantConfig.json
. - If using
qwc-docker
, setQGIS_PROJECT_SUFFIX=qgz
in theqwc-qgis-server
environment indocker-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 theqwc-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 totrue
. -
Generate the themes configuration.
Note: ELSE
symbol rules are currently unsupported, respectively will display the entire layer contents.