Skip to content

Commit 7d7772c

Browse files
manisandromanisandro
committed
Improve formatting for Search chapter
1 parent 2faa650 commit 7d7772c

File tree

1 file changed

+72
-72
lines changed

1 file changed

+72
-72
lines changed

‎src/topics/Search.md‎

Lines changed: 72 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -6,20 +6,20 @@ QWC can be configured to use arbitrary custom search providers. In addition, the
66

77
Search providers can be defined as follows:
88

9-
- As resource, defined in `static/assets/searchProviders.js`. This file is structured as follows:
9+
- In an external script loaded at runtime, defined i.e. in `static/assets/searchProviders.js`. This file is structured as follows:
1010
```js
1111
window.QWC2SearchProviders = {
1212
<providerkey1>: <ProviderDefinition1>,
1313
<providerkey2>: <ProviderDefinition2>,
1414
...
1515
};
1616
```
17-
This script file needs to be loaded explicitly by `index.html` via
17+
This script file needs to be include in `index.html`:
1818
```html
1919
<script type="text/javascript" src="assets/searchProviders.js" ></script>
2020
```
2121

22-
- Built-in, defined in `js/SearchProviders.js`. This file is structured as follows:
22+
- Built-in in a custom QWC build, i.e. defined in `js/SearchProviders.js`. This file is structured as follows:
2323
```js
2424
window.QWC2SearchProviders = {
2525
<providerkey1>: <ProviderDefinition1>,
@@ -71,61 +71,63 @@ The format of `ProviderDefinition` is
7171
```
7272
*Notes:*
7373

74-
* The format of `searchParams` is
75-
```js
76-
{
77-
displaycrs: "EPSG:XXXX", // Currently selected mouse coordinate display CRS
78-
mapcrs: "EPSG:XXXX", // The current map CRS
79-
lang: "<code>", // The current application language, i.e. en-US or en
80-
cfgParams: <params>, // Additional parameters passed in the theme search provider configuration, see below
81-
limit: <number>, // Result count limit
82-
activeLayers: ["<layername>", ...], // List of active layers in the map
83-
filterBBox: [xmin, ymin, xmax, ymax]|null, // A filter bbox, in mapcrs, the search component may pass to the provider to narrow down the results
84-
filterPoly: [[x0, y0], [x1, y1], ....], // A filter polygon, in mapcrs, the search component may pass to the provider to narrow down the results
85-
}
86-
```
87-
* `axios` is passed for convenience so that providers can use the compiled-in `axios` library for network requests.
74+
* The format of `searchParams` is as follows:
75+
76+
| Field | Description |
77+
|-----------------------------------------------|-------------------------------------------------------------------------------------------------------|
78+
| `{` | |
79+
| ` displaycrs: "EPSG:XXXX",` | Currently selected mouse coordinate display CRS. |
80+
| ` mapcrs: "EPSG:XXXX",` | The current map CRS. |
81+
| ` lang: "<code>",` | The current application language, i.e. en-US or en. |
82+
| ` cfgParams: <params>,` | Additional parameters passed in the theme search provider configuration, see below. |
83+
| ` limit: <number>,` | Result count limit. |
84+
| ` activeLayers: ["<layername>", ...],` | List of active layers in the map. |
85+
| ` filterBBox: [xmin, ymin, xmax, ymax]|null,` | A filter bbox, in mapcrs, the search component may pass to the provider to narrow down the results. |
86+
| ` filterPoly: [[x0, y0], [x1, y1], ...]|null` | A filter polygon, in mapcrs, the search component may pass to the provider to narrow down the results.|
87+
| `}` | |
8888

89-
* The format of the `results` list returned by `onSearch` is as follows:
90-
```js
91-
results = [
92-
{
93-
id: "<categoryid>", // Unique category ID
94-
title: "<display_title>", // Text to display as group title in the search results
95-
titlemsgid: "<display_title_msgid>", // Translation message id for group title, instead of "title"
96-
resultCount: <result_count>, // Optional: true result count (i.e. not limited to the "limit" specified in searchParams).
97-
priority: priority_nr, // Optional: search result group priority. Groups with higher priority are displayed first in the list.
98-
type: SearchResultType.{PLACE|THEMELAYER|EXTERNALLAYER}, // Specifies the type of results. Default: SearchResultType.PLACE
99-
items: [
100-
// PLACE result
101-
{
102-
id: "<item_id>", // Unique item ID
103-
text: "<display_text>", // Text to display as search result
104-
label: "<map_marker_text>", // Optional, text to show next to the position marker on the map instead of `text`
105-
x: x, // X coordinate of result
106-
y: y, // Y coordinate of result
107-
crs: crs, // CRS of result coordinates and bbox. If not specified, the current map crs is assumed.
108-
bbox: [xmin, ymin, xmax, ymax], // Bounding box of result (if non-empty, map will zoom to this extent when selecting result)
109-
geometry: <GeoJSON geometry>, // Optional, result geometry. Note: geometries may also be fetched separately via getResultGeometry.
110-
thumbnail: "<thumbnail_url>", // Optional: thumbnail to display next to the search result text in the result list,
111-
externalLink: "<url>" // Optional: a url to an external resource. If specified, a info icon is displayed in the result entry to open the link.
112-
target: "<target>" // Optional: external link target, i.e. _blank or iframe
113-
},
114-
// THEMELAYER or EXTERNALLAYER result
115-
{
116-
id: "<item_id>", // Unique item ID
117-
text: "<display_text>", // Text to display as search result
118-
layer: {<layer_definition>} // Optional: layer definition, in the same format as a "sublayers" entry in themes.json. Layer definitions may also be fetched separately via getLayerDefinition.
119-
info: <bool>, // Optional: Whether to display a info icon in the result list. The info is read from layer.abstract. If layer is not specified, the layer is fecthed via getLayerDefinition.
120-
thumbnail: "<thumbnail_url>", // Optional: thumbnail to display next to the search result text in the result list,
121-
sublayers: [{<sublayer>}, ...] // Optional: list of sublayers, in the format {id: "<item_id>", text: "<display_text>", has_info: <bool>, etc..}
122-
}
123-
]
124-
}
125-
]
126-
```
89+
* `axios` is passed for convenience so that providers can use the compiled-in `axios` library for network requests.
12790

128-
Consult [static/assets/searchProviders.js](https://github.com/qgis/qwc2-demo-app/blob/master/static/assets/searchProviders.js) for a full examples.
91+
* `onSearch` is expected to return a list of search category results structured as follows:
92+
93+
| Field | Description |
94+
|------------------------------------------|-------------------------------------------------------------------------------------------------------|
95+
| `{` | |
96+
| ` id: "<categoryid>",` | Unique category ID. |
97+
| ` title: "<display_title>",` | Text to display as group title in the search results. |
98+
| ` titlemsgid: "<display_title_msgid>",` | Translation message id for group title, instead of `title`. |
99+
| ` resultCount: <result_count>,` | Optional: true result count (i.e. not limited to the `limit` specified in searchParams). |
100+
| ` priority: <priority_nr>,` | Optional: search result group priority. Groups with higher priority are displayed first in the list. |
101+
| ` type: SearchResultType.{PLACE|THEMELAYER|EXTERNALLAYER},` |Specifies the type of results. Defaults to `SearchResultType.PLACE`. |
102+
| ` items: [` | |
103+
| `  {` | Format for `PLACE` result: |
104+
| `   id: "<item_id>",` | Unique item ID. |
105+
| `   text: "<display_text>",` | Text to display as search result. |
106+
| `   label: "<map_marker_text>",` | Optional, text to show next to the position marker on the map instead of `text`. |
107+
| `   x: <x>,` | X coordinate of result. |
108+
| `   y: <y>,` | Y coordinate of result |
109+
| `   crs: <crs>,` | CRS of result coordinates and bbox. If not specified, the current map crs is assumed. |
110+
| `   bbox: [xmin, ymin, xmax, ymax],` | Bounding box of result (if non-empty, map will zoom to this extent when selecting result). |
111+
| `   geometry: <GeoJSON geometry>,` | Optional, result geometry. Geometries may also be fetched separately via `getResultGeometry`. |
112+
| `   thumbnail: "<thumbnail_url>",` | Optional: thumbnail image to display next to the search result text in the result list. |
113+
| `   externalLink: "<url>",` | Optional: a url to an external resource. If specified, a info icon is displayed in the result entry to open the link. |
114+
| `   target: "<target>"` | Optional: external link target. Can be `_blank` (default) or `iframe`. |
115+
| `  },` | |
116+
| `  {` | Format for `THEMELAYER` or `EXTERNALLAYER` result: |
117+
| `   id: "<item_id>",` | Unique item ID. |
118+
| `   text: "<display_text>",` | Text to display as search result. |
119+
| `   layer: {<layer_definition>},` | Optional, layer definition:., in the same format as a "sublayers" entry in themes.json. |
120+
| | * For `THEMELAYER` results, the entry should be in the same format as a `sublayer` entry of a theme layer in `themes.json`. |
121+
| | * For `EXTERNALLAYER` results, the entry can be of the form `{resource: "<resource_string>}` or a full layer definition. |
122+
| | If `layer` is not specified, the layer definition will be queried via `getLayerDefinition`. |
123+
| `   info: <bool>,` | Optional: Whether to display a info icon in the result list. The info is read from `layer.abstract`. |
124+
| `   thumbnail: "<thumbnail_url>",` | Optional: thumbnail image to display next to the search result text in the result list. |
125+
| `   sublayers: [{<sublayer>}, ...]` | Optional: list of sublayers, in the same format as the format parent result item (i.e. `{id: "<item_id>", text: "<display_text>", layer: {<layer>}, ...}`). |
126+
| `  }` | |
127+
| ` ]` | |
128+
| `}` | |
129+
130+
Consult [static/assets/searchProviders.js](https://github.com/qgis/qwc2-demo-app/blob/master/static/assets/searchProviders.js) for a full example.
129131

130132
## Filtering <a name="filtering"></a>
131133

@@ -160,22 +162,20 @@ Alternatively, you can also set `searchFilterRegions` to an URL returning a JSON
160162
## Configuring theme search providers
161163

162164
For each theme item in `themesConfig.json`, you can define a list of search providers to enable for the theme as follows:
163-
```json
164-
...
165-
searchProviders: [
166-
"<providerkey1>", // Simple form
167-
{ // Provider with custom params
168-
"provider": "<providerkey2>",
169-
"key": "<key>", // Optional: key to disambiguate multiple provider configurations of the same provider type (i.e. multiple `qgis` provider configurations)
170-
"label": "<label>", // Optional: provider label (displayed in provider selection menu). If not specified, the label/labelmsgid from the provider definition is used.
171-
"labelmsgid": "<msgid>", // Optional: translateable label message ID, instead of `label`
172-
"params": {
173-
... // Additional params passed to the provider `onSearch` function as `searchParams.cfgParams`
174-
}
175-
}
176-
]
177-
...
178-
```
165+
166+
| Field | Description |
167+
|------------------------------------------|-------------------------------------------------------------------------------------------------------|
168+
| `searchProviders: [` | |
169+
| ` "<providerkey1>",` | Simple form. |
170+
| ` {` | Complex form with custom params: |
171+
| `  "provider": "<providerkey2>",` | Provider key. |
172+
| `  "key": "<key>",` | Optional: key to disambiguate multiple provider configurations of the same provider type (i.e. multiple `qgis` provider configurations). |
173+
| `  "label": "<label>",` | Optional: provider label (displayed in provider selection menu). If not specified, the label/labelmsgid from the provider definition is used. |
174+
| `  "labelmsgid": "<msgid>",` | Optional: translateable label message ID, instead of `label`. |
175+
| `  "params": {...}` | Additional params passed to the provider `onSearch` function as `searchParams.cfgParams`. |
176+
| ` }` | |
177+
| `]` | |
178+
179179
Note: The QWC stock application (also used by the `qwc-map-viewer` docker image) includes four providers by default: `coordinates`, `nominatim` (OpenStreetMap location search, see <a href="#nominatim-search">below</a>), `qgis` (see <a href="#qgis-search">below</a>) and `fulltext` (see <a href="#fulltext-search">below</a>).
180180

181181
## Configuring the nominatim (OpenStreetMap) location search <a name="nominatim-search"></a>

0 commit comments

Comments
 (0)