agssearch

Use this bundle to register layers as stores. Registered layers can be used as data sources for feature selection and feature search for example.

You can register the following layer types as stores with this bundle:

• Feature layer
• MapImagery sublayer
• OGC API - Features
• OGC WFS
• CSV layer
• GeoJSON layer

See the API for interface declarations.

Usage

Register stores with map layer references

The following code sample shows the minimal configuration of a store. The layerId property references a layer that is configured in the map.

"agssearch": {
    "AGSStore":[{
        "id": "boundaries-store",
        "layerId": "boundaries"
    }]
},
"map-init": {
    "Config": {
        "map": {
            "layers": [
                {
                    "id": "boundaries",
                    "url": "https://services.conterra.de/arcgis/rest/services/common/grenzen/FeatureServer/0",
                    "type": "AGS_FEATURE"
                }
            ]
        }
    }
}

The following sample shows the minimal configuration for different layer types to use the layers in selection and search:

"agssearch": {
    "AGSStore": [
        {
            "id": "store01-feature",
            "layerId": "communities",
            "useIn": ["search","selection"],
            "searchAttribute": "g_name"
        },
        {
            "id": "store02-mapserver",
            "layerId": "boundaries/0",
            "useIn": ["search","selection"],
            "searchAttribute": "g_name"
        },
        {
            "id": "store03-ogcapi",
            "layerId": "nurseries_ogcapi_layer",
            "useIn": ["search","selection"],
            "searchAttribute": "name"
        },
        {
            "id": "store04-wfs",
            "layerId": "nurseries_wfs_layer",
            "useIn": ["search","selection"],
            "searchAttribute": "E_NAME"
        },
        {
            "id": "store05-geojson",
            "layerId": "earthquakes_geojson",
            "useIn": ["search","selection"],
            "searchAttribute": "title"
        },
        {
            "id": "store06-csv",
            "layerId": "earthquakes_csv",
            "useIn": ["search","selection"],
            "searchAttribute": "place"
        }
    ]
},
"map-init": {
    "Config": {
        "map": {
            "layers": [
                {
                    "id": "communities",
                    "type": "AGS_FEATURE",
                    "url": "https://services.conterra.de/arcgis/rest/services/common/grenzen/FeatureServer/0",
                    "displayField": "g_name"
                },
                {
                    "id": "boundaries",
                    "type": "AGS_DYNAMIC",
                    "url": "https://services.conterra.de/arcgis/rest/services/common/grenzen/MapServer",
                    "sublayers": [
                        {
                            "id": 0
                        }
                    ],
                    "displayField": "g_name"
                },
                {
                    "id": "nurseries_ogcapi_layer",
                    "type": "OGC_FEATURE",
                    "url": "https://ogc-api.nrw.de/inspire-us-kindergarten/v1",
                    "collectionId": "governmentalservice"
                },
                {
                    "id": "nurseries_wfs_layer",
                    "type": "WFS",
                    "url": "https://www.stadt-muenster.de/ows/mapserv706/kitaserv",
                    "name": "ms:kitas01"
                },
                {
                    "id": "earthquakes_geojson",
                    "type": "GEOJSON",
                    "url": "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_month.geojson"
                },
                {
                    "id": "earthquakes_csv",
                    "type": "CSV",
                    "url": "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_week.csv"
                }
            ]
        }
    }
}

Register stores with URLs

Use the url property instead of the layerId property to register a store that is not configured in the map.

"agssearch": {
    "AGSStore":[{
        "id": "boundaries-store",
        "url": "https://services.conterra.de/arcgis/rest/services/common/grenzen/FeatureServer/0"
    }]
}

The following sample shows the minimal configuration for different layer types to use the layers in selection and search:

"agssearch": {
    "AGSStore": [
        {
            "id": "store01-feature",
            "url": "https://services.conterra.de/arcgis/rest/services/common/grenzen/FeatureServer/0",
            "useIn": ["search","selection"],
            "searchAttribute": "g_name"
        },
        {
            "id": "store02-mapserver",
            "url": "https://services.conterra.de/arcgis/rest/services/common/grenzen/MapServer/0",
            "useIn": ["search","selection"],
            "searchAttribute": "g_name"
        },
        {
            "id": "store03-ogcapi",
            "url": "https://ogc-api.nrw.de/inspire-us-kindergarten/v1",
            "type": "ogc-feature",
            "collectionId": "governmentalservice",
            "useIn": ["search","selection"],
            "objectIdField": "id",
            "searchAttribute": "name"
        },
        {
            "id": "store04-wfs",
            "url": "https://www.stadt-muenster.de/ows/mapserv706/kitaserv",
            "name": "ms:kitas01",
            "type": "wfs",
            "useIn": ["search","selection"],
            "searchAttribute": "E_NAME"
        },
        {
            "id": "store05-geojson",
            "url": "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_month.geojson",
            "type": "geojson",
            "useIn": ["search","selection"],
            "searchAttribute": "title"
        },
        {
            "id": "store06-csv",
            "url": "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_week.csv",
            "type": "csv",
            "useIn": ["search","selection"],
            "searchAttribute": "place"
        }
    ]
}

Register all supported layers as stores automatically

To automatically register all map layers of types supported by this bundle as stores, enable the AutoStoreRegistration component just as this:

"agssearch": {
    "AutoStoreRegistration": {
        "componentEnabled": true
    }
}

To use this stores for search, read the additional hints in Use auto-registered stores for search.

Constraints

• A store created with this bundle can only search on attribute fields of type string.
• Searching on multiple fields per layer with one store is not possible.
• The component AutoStoreRegistration respects the visible state (on/off) of a layer. It does not respect if the layer can be seen in the map (for example depending on the extent or map scale).
• Services with group layers are not fully supported for AutoStoreRegistration.
• Limitation of the ogc-feature support for search and selection:
  • Tested with the ldproxy and ArcGIS Server OGCFeatureService implementation.
  • The ArcGIS Server OGCFeatureService only supports bbox and point selection. Selection using polygon geometry is not supported.
  • For filtering using long queries (for example when using polygon selection), it can be required that the server supports HTTP POST requests for filter queries, see supportsPostQueries option. This may require an extra module installation for ldproxy, see Custom Extension - Scope.

Configuration reference

The following code sample shows the configurable properties in a sample store:

"agssearch": {
    "AGSStore":[ {
        "id": "Airports",
        "url": "https://myserver/arcgis/rest/services/myservice/MapServer/0",
        "type": "feature",
        "apiKey": "__KEY__",
        "layerId": "myservice/0", // use instead of url
        "title": "Airports",
        "description": "Find all international airports",
        "useIn":[ "search", "selection"],
        "searchAttribute": "icao_name",
        "searchLabel": "${icao_name} (${city})",
        "searchPriority": 1,
        "filterOptions": {
            "suggestContains": true,
            "metadata": {
                "fields":[ {
                    "name": "OBJECTID",
                    "title": "ID"
                },
                {
                    "name": "icao_name",
                    "title": "NAME"
                }]
            }
        },
        "popupEnabled": true,
        "popupTemplate": {
            "title": "",
            "content": []
        },
        "fieldConfig": [
            {
                "name": "year",
                "title": "other-alias",
                "dateFormat": "short-date",
                "digitSeparator": true,
                "places": 2
            }
        ]
    }]
}

The following property is required if type is set to wfs:

The following properties are supported if type is set to ogc-feature:

For known limitations of the ogc-feature support, see constraints.

Use cases

Configure popups for stores

To add default popups to a store, set "popupEnabled": true and add the popups-default bundle to your app.

"agssearch": {
    "AGSStore":[{
        "id": "Airports",
        "url": "https://myserver/arcgis/rest/services/Airports/MapServer/0",
        "popupEnabled": true
    }]
}

To add an individual popup to a store, configure the property popupTemplate as in the following sample:

"agssearch": {
    "AGSStore":[{
        "id": "Airports",
        "url": "https://myserver/arcgis/rest/services/Airports/MapServer/0",
        "popupTemplate": {
            "title": "{name}",
            "content": [
                {
                    "type": "fields",
                    "fieldInfos": [
                        {
                            "fieldName": "myfield",
                            "label": "My field"
                        }
                    ]
                }
            ]
        }
    }]
}

For more information about configuring individual popups, see Individual popups in the product documentation.

To add a customized popup to a store, set the popupType and/or customActions as in the following code sample:

"agssearch": {
    "AGSStore":[{
        "id": "Airports",
        "url": "https://myserver/arcgis/rest/services/Airports/MapServer/0",
        "popupTemplate": {
            "popupType": "mywidget",
            "customActions": [
                "fullScreenWindowAction"
            ]
        }
    }]
}

For more information about adding custom popup types and actions, see the popups bundle documentation.

Format display of results in the Result UI

To control how values of an item of a store are displayed in a data table in the Result UI, configure the fieldConfig array:

"agssearch": {
    "AGSStore":[{
        "id": "Airports",
        "url": "https://myserver/arcgis/rest/services/Airports/MapServer/0",
        "useIn": ["selection"],
        "fieldConfig": [
            {
                "name": "expression/title",
                "title": "Title"
            },
            {
                "name": "year",
                "title": "other-alias",
                "dateFormat": "short-date",
                "digitSeparator": true,
                "places": 2
            }
        ],
        "expressionInfos": [
            {
                "name": "title",
                "expression": "`${$feature.name} (${$feature.hauptstadt})`"
            }
        ]
    }]
}

If you use fieldConfig to configure fields in the Result UI, only the fields that are configured in fieldConfig are displayed, all others are not displayed.

It is possible to define virtual fields using ArcGIS Arcade expressions. In the sample the field with name expression/title demonstrates this feature. It declares a virtual field with the title Title and references the expression with name title in the expressionInfos option. In the result-ui this virtual field will be displayed as column.

For more information about ArcGIS Arcade, see https://developers.arcgis.com/arcade/.

Limitation: An Arcade expression for virtual fields has no access to the geometry or the layer of a feature. It only has access to the fields of a feature.

If a store is created from the auto-store registration, the fieldConfig array has to be added to the layer configuration in the map-init bundle.

Use auto-registered stores for search

When AutoStoreRegistration is enabled, stores for the supported layer types are created automatically. To allow searching features in stores of the types geojson, csv, wfs and ogc-feature, specify the displayField property in the map layer configuration.

"map-init": {
    "Config": {
        "map": {
            "layers": [
                {
                    "id": "kitas_wfs_layer",
                    "url": "https://www.stadt-muenster.de/ows/mapserv706/kitaserv",
                    "type": "WFS",
                    "name": "ms:kitas01",
                    "displayField": "E_NAME"
                }
            ]
        }
    }
}

Or use the options field to declare a search field.

"map-init": {
    "Config": {
        "map": {
            "layers": [
                {
                    "id": "kitas_wfs_layer",
                    "url": "https://www.stadt-muenster.de/ows/mapserv706/kitaserv",
                    "type": "WFS",
                    "name": "ms:kitas01",
                    "options": {
                        "searchAttribute": "E_NAME"
                    }
                }
            ]
        }
    }
}

Create custom store instances

Use the service name agssearch.AGSStoreFactory to obtain a factory reference for your component:

// manifest.json
// ...
"components": [
    {
        "name": "MyExampleComponent",
        "references": [
            {
                "name": "_storeFactory",
                "providing": "agssearch.AGSStoreFactory"
            }
        ]
    }
]
// ...

You can then use the createStore() method to construct a new instance:

class MyExampleComponent {
    async exampleMethod() {
        const store = await this._storeFactory.createStore({
            id: "my-new-store",
            layerId: "a-valid-layer-id"
            // or url: "https://example.com/some/FeatureServer"
        });
        await store.load(); // Need to load metadata before store can be used.
    }
}