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 QWC 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 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
*.qgsproject file. Remember to copy all resources along with the*.qgsproject 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.confon your host system as well as in theqwc_docker/pg_service.confandqwc_docker/pg_service-write.confwhich are mounted inside the docker containers. For instance, to use defaultqwc-dockerdatabase, use theqwc_geodbservice and add the service definition to your hostpg_service.confas 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 theqwc-config-generatorwill 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
idcan be freely defined and will appear in the viewer URL as thetquery parameter. - When using
qwc-docker, theurlcan be specified as/ows/<relative_path_to_qgs>whererelative_path_to_qgsis the path to the QGIS project file belowqwc-docker/volumes/qgs-resources, without the.qgsextension. In the above sample, the project file would be located atqwc-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. |
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. |
"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 specifiyprojectionandtileGridConfig. If labels are cropped you could also setdecluttertotrue)
{
"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 theqwc-admin-guiadministration backend, running on http://localhost:8088/qwc_admin by default. Log in asadminuser, then press the greenGenerate service configurationbutton. This will invoce theqwc-config-generator, which will generatemapViewerConfig.jsonlocated belowqwc-docker/volumes/config/<tenant>. You can then inspect the generatedthemes.jsonat http://localhost:8088/themes.json. -
When using QWC as a standalone viewer, the
themes.jsoncan 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
qgisprojectsservice definition for the used database toqwc-docker/pg_service.conf. - Write a theme configuration entry in
themesConfig.jsonusing with"url": "/ows/pg/<schema>/<projectname>", whereschemaandprojectnameas 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_extensionto.qgzin the toplevelconfigsection oftenantConfig.json. - If using
qwc-docker, setQGIS_PROJECT_SUFFIX=qgzin theqwc-qgis-serverenvironment indocker-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_categorizedin theqwc-qgis-servercontainer 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_layerand set it totrue. -
Generate the themes configuration.
Note: ELSE symbol rules are currently unsupported, respectively will display the entire layer contents.