Skip to content

How to work with the <discover-swiss-map> component

The HTML <discover-swiss-map> custom element represents a map view with optional filtering control and list view.

Example

<!doctype html>
<head>
  <title>Simple discover-swiss-map demo</title>

  <script src="https://scripts-test.discover.swiss/webcomponents/discover-swiss-map-1.js"></script>
  <script src="https://scripts-test.discover.swiss/webcomponents/discover-swiss-mapbox-1.js"></script>
  <script src="https://scripts-test.discover.swiss/webcomponents/discover-swiss-search-1.js"></script>

  <style>
    discover-swiss-map {
      width: 100%;
      height: 100%;
    }
  </style>
</head>
<div style="width: 800px; height: 360px;">
  <discover-swiss-map
    config='
      {
        "map": {
          "layout": "simple",
           "stylesheets": [
             "map-example.css"
           ]
        },
        "mapbox": {
          "controls": {
            "geolocate": null,
            "navigation": "top-right",
            "settings": "top-right",
          },
          "images": {
            "marker-default": "https://upload.wikimedia.org/wikipedia/commons/thumb/8/88/Map_marker.svg/156px-Map_marker.svg.png"
          },
          "infobox": {
            "enable": true,
            "maxWidth": 320
          },
          "showLabels": false,
          "styles": {
            "default": "https://api.maptiler.com/maps/topo/style.json?key=qJ6Vl7bSilkWSgxelVMY",
            "spring": "https://api.maptiler.com/maps/5bf0b841-ab9c-471f-950e-5f6e082cc681/style.json?key=qJ6Vl7bSilkWSgxelVMY",
            "summer": "https://api.maptiler.com/maps/71c67f03-2693-4da4-bfdc-a0aa49b46aa7/style.json?key=qJ6Vl7bSilkWSgxelVMY",
            "autumn": "https://api.maptiler.com/maps/e8b2d1ca-3eb5-4997-b94e-958b42a275bf/style.json?key=qJ6Vl7bSilkWSgxelVMY",
            "winter": "https://api.maptiler.com/maps/f4e63500-473b-4f1b-870d-1b6730c84a6c/style.json?key=qJ6Vl7bSilkWSgxelVMY"
          }
        },
        "search": {
          "id": "simple-discover-swiss-map-demp",
          "infocenter": {
            "headers": {
              "Ocp-Apim-Subscription-Key": "yoloyoloyoloyoloyoloyoloyoloyolo"
            },
            "project: "someproject"
          },
          "request": {
            "filters": [
              "identifier eq &#x27;plc_4kq_cfdfjafd&#x27;"
            ]
          }
        }
      }
    '
  />
</div>

Example example.css stylsheet:

.mapboxgl-popup-content {
  font: monospace;
  background-color: red;
  padding: 20px !important;
}

Attributes

config

The config JSON attribute is used to configure all aspects of the <discover-swiss-map> element and its subcomponents.

map

The map object configures the overall <discover-swiss-map> element.

map.altitudeChart.enable

Specifies whether to show an altitude chart under the map which displays the height profile of the focused item (if it is a tour). This will only work with the "simple" map layout.

Default value: false

map.bookmarks.enable

Specifies whether to enable bookmarks support. The value is a boolean.

See bookmarks property, setBookmarks() method, and "bookmarks" event for integration details.

Default value: false

map.bookmarks.disable

This allows to temporarily disable bookmarks support, e.g. if the backing storage isn't ready yet or if it requires login. While disabled, the bookmark icon will be grayed out. The value is either a boolean, or a string. Setting it to true will disable bookmarks support with a default tooltip. Setting it to a string customizes the tooltip.

Default value: false

map.filter.enable

Specifies whether to enable the filter or not. The value is a boolean.

Default value: false

map.filter.showAllItemsByDefault

Specifies whether to show all items if no filtering criteria have been specified. The value is a boolean.

Default value: true

map.filter.showControls

Specifies whether to show filter controls. The value is a boolean.

Default value: true

map.information.title

Adds a title to the default map layout. The value is a string.

Default value: ""

map.information.subtype

When set to "guide", lets the map know it is used for displaying guide points. The value is a string.

Default value: null

map.layout

Specifies how the <discover-swiss-map> element should be presented. The value can be

  • "default": Indicates that the element should contain a list view, a detail view, and filter controls alongside the map view. If the device screen is large enough, then both will be shown at the same time. Otherwise map and list view can be toggled.

  • "simple": Indicates that only the map view should be contained.

    In simple layout the integrated search does not download categories.

Default value: "default"

map.stylesheets

Specifies the stylesheets that should be used by the children of the <discover-swiss-map> element. Stylesheets get propagated down to child components. The value is an array of URLs to stylesheets.

Default value: []

mapbox

The mapbox object configures the <discover-swiss-mapbox> child component, which is responsible for rendering the map.

mapbox.center

The inital geographical centerpoint of the map. This value works in conjunction with mapbox.zoom. The value is either null or an array of two numbers representing longitude and latitude. If null, then the the centerpoint and zoom level will be choosen to show all items on the map.

For details, check the documentation for the center parameter of Mapbox GL JS's Map object.

Default value: null

mapbox.controls.geolocate

The position of the geolocation controls. The value can be:

  • "top-left"
  • "top-right"
  • "bottom-left"
  • "bottom-right"
  • null: don't show the geolocation controls.

Default value: null

mapbox.controls.navigation

The position of the navigation controls. The value can be:

  • "top-left"
  • "top-right"
  • "bottom-left"
  • "bottom-right"
  • null: don't show the navigation controls.

Default value: null

mapbox.controls.settings

The position of the settings controls. The value can be:

  • "top-left"
  • "top-right"
  • "bottom-left"
  • "bottom-right"
  • null: don't show the settings controls.

Default value: null

mapbox.images

Override the images shown on the map. The value is an object mapping image identifiers to image URLs.

Following image identifiers are recognized:

  • "marker-default"
  • "marker-event"
  • "marker-gastronomy"
  • "marker-lodging"
  • "marker-place"
  • "marker-tour"
  • "marker-winter"
  • "sign-closed"
  • "sign-open"

Default value:

  {
    "marker-default": "icons/map-marker.png",
    "sign-closed": "icons/closed.png",
    "sign-open": "icons/open.png"
  }

The other marker-* identifiers default to the value of "marker-default".

mapbox.infobox.enable

Specifies whether the infobox (popup) should be shown when clicking on a map feature. The value is a boolean.

Default value: false

mapbox.infobox.height

Height of the infobox in pixels. The value is an integer.

Default value: mapbox.infobox.maxWidth / 4

mapbox.infobox.image.height

Height of the image shown in the infobox. The value is an integer.

Default value: mapbox.infobox.height

mapbox.infobox.image.width

Width of the image shown in the infobox. The value is an integer.

Default value: mapbox.infobox.image.height

mapbox.infobox.maxWidth

Maximum width of the infobox in pixels. The value is an integer.

Default value: 240

mapbox.infobox.templateConfig.filterLinkTypes

Specifies which link types should be shown in the infobox. The value is either null or an array of strings. If null, then all link types will be shown. Otherwise only the link types specified in the array will be shown.

Default value: null

Note: to actually show links mapbox.infobox.templateConfig.showLink must be true.

mapbox.infobox.templateConfig.showDescription

Specifies whether to show the item description in the infobox. The value is a boolean.

Default value: true

mapbox.infobox.templateConfig.showImage

Specifies whether to show the item image in the infobox. The value is a boolean.

Default value: true

Note: to show static images instead of the actual item images, mapbox.infobox.templateConfig.staticImage can be used.

Specifies whether to show the item links in the infobox. The value is a boolean.

Default value: false

Note: to control which link types to show mapbox.infobox.templateConfig.filterLinkTypes can be used.

mapbox.infobox.templateConfig.showName

Specifies whether to show the item name in the infobox. The value is a boolean.

Default value: true

mapbox.infobox.templateConfig.staticImage

Specifices the URL of a static image to be shown instead of the actual item image. The value is either null or a string. If null, then the actual item image will be shown.

Default value: null

Note: to actually show this image mapbox.infobox.templateConfig.showImage must be true.

mapbox.showLabels

Specifies whether to show marker labels. The value is a boolean.

Default value: false

mapbox.styles

Map style to be used. The value is an object mapping seasons to style URLs.

Following seasons are recognized:

  • "default": style to be used for seasons that have no style specified
  • "spring": style to be used in March, April, May
  • "summer": style to be used in June, July, August
  • "autumn": style to be used in September, October, November
  • "winter": style to be used in December, January, February

Default value:

  {
    "default": "mapbox://styles/mapbox/streets-v11"
  }

mapbox.zoom

The initial zoom level of the map. The initial zoom level is only used when mapbox.center is specified. The value is a number.

Default: 0

The search object configures the <discover-swiss-search> child component, which is responsible for the communication with the Infocenter search API.

search.enable

Specifies whether to enable integrated search. The value is a boolean. If set to false, then categories and items can be fetched externally, and provided using the searchResult property and the setSearchResult() method.

Note: when the integrated search is disabled, search.infocenter.headers, search.infocenter.url, and search.request are still used for filtering items when the search input bar is used. This means that these three options have to be configured to be able to fetch (at least) the items provided externally. It is safe but less efficient to configure a request that will fetch more than the externally provided items, as superfluous results will be ignored. If on the other hand the request is configured to fetch less items than provided externally, any missing item cannot be found using the search bar.

Default value: true

search.id

The identifier for the search instance. It is used to cache search results. This value is a string and should be unique across a domain. If not unique, then caches of multiple searches will interfere with each other.

Default value: ""

search.infocenter.headers["Ocp-Apim-Subscription-Key"]

Ocp-Apim-Subscription-Key header to be sent to the Infocenter API. This value is either null or a string. If null, then no header will be sent to the API.

This Header must be set otherwise data can't be retrieved from the API.

Default value: null

search.infocenter.headers["Accept-Language"]

Accept-Language header to be sent to the Infocenter API. This value is either null or a string. If null, then no header will be sent to the API.

Default value: null

search.infocenter.project

The project query parameter to be used when querying the Infocenter API. The value must match the partner assigned to the subscription key defined in search.infocenter.headers["Ocp-Apim-Subscription-Key"]. This value is either null or a string. If null, then no project parameter will be sent to the API.

Default value: null

search.infocenter.url

Base path of the Infocenter API. This value is a string.

Default value: "https://api.discover.swiss/test/info/v2"

search.request

Full search request to be sent to the search API. This value is an object of the FullSearchRequest schema.

Default value: {}

Note: the attributes facets, select, currentPage, and resultsPerPage are not configurable. Any attempt to configure these will be overridden by the <discover-swiss-search> component as these are used internally.

For details about the FullSearchRequest schema, see the documentation of the search API.

Properties

bookmarks

The bookmarks property can be used to set the initial bookmarks. It has the same value as the bookmarks parameter to the setBookmarks() method described below.

searchResult

The searchResult property is used to set the initial search result. It has the same value as the searchResult parameter to the setSearchResult() method described below.

Methods

setBookmarks(bookmarks)

The setBookmarks() method is used to set the bookmarks.

Parameters

bookmarks

Array of strings representing the bookmarks. Duplicate values will be ignored.

setConfig(config)

The setConfig() is used to set the elements configuration.

Parameters

config

The config parameter is an object as described in the attributes section above.

getConfig()

The getConfig() is used to get the elements configuration.

Parameters

none

setDetailItem(identifier)

Set the item to be shown in the detail view. This method is only effective if the map layout contains a detail view. See config.map.layout above for more information about layouts.

setFilterCategories(categories)

Select categories to be used for filtering.

Parameters

categories

The categories parameter is an array of strings, interpreted as category identifiers. Unknown category identifiers are ignored.

For available category identifiers, see the category tree overview.

Parameters

identifier

The identifier parameter is a string containing the identifier of the item to be shown in the detail view, or null if no item should be shown in detail. If the parameter is a string, then it must reference an existing item.

setFocusItem(identifier)

Set the item to be focused. If the focused item is not yet centered in the map view, the map view will change its center to the focused item.

Parameters

identifier

The identifier parameter is a string containing the identifier of the item to be focused, or null if the focus should be removed. If the parameter is a string, then it must reference an existing item.

`setSearchCategory({ category, subcategories })

DEPRECATED: use the setFilterCategories() method instead.

Set the main- and subcategories filters.

Parameters

category

The category parameter is a string interpreted as category identifier. The parameter must identify an existing top-level category. Top-level categories are the direct children of the root category.

For available category identifiers, see the category tree overview.

subcategories

The subcategories parameter is either null or an array of strings, interpreted as category identifiers. If the parameter is an array, then each array item must identify an existing subcategory of the main category defined by the category parameter. Subcategories a all direct and indirect children of the main category.

For available category identifiers, see the category tree overview.

setSearchFilterText(text)

Set the contents of the search input bar.

Parameters

text

The text parameter is a string to be used as text for the search input bar.

setSearchResult(searchResult)

The searchResult() method is used to set the search result.

Parameters

searchResult

The searchResult parameter is an object with two properties categories and items. The categories property is an array accepting objects of the Category schema. The items property is an array accepting objects of following schemas:

  • AdministrativeArea
  • CivicStructure
  • Condition
  • Event
  • FoodEstablishment
  • LocalBusiness
  • LodgingBusiness
  • Place
  • Tour
  • Webcam

For details about the various schemas, see the documentation of the Infocenter API.

Events

"bookmarks"

A "bookmarks" event will be emitted whenever the set of bookmarks has been modified within the element. This happens e.g. when the user clicks on the bookmark icon of an item.

The event conveys the array of strings in its detail property, representing the current set of bookmarks. This value can be used as the bookmarks parameter of the setBookmarks() method.

detailItem

A "detailItem" event will be emitted whenever the item to be shown in the detail view changes, either because the user has interacted with the element, or because a call to the setDetailItem() method has succeeded.

The event conveys either a string or null in its detail property. If it is a string, then it represents the item's identifier. If it is null, then no item is shown in detail.

"filterCategories"

A "filterCategories" event will be emitted whenever the filter categories change, either bcause the user has interacted with the element, or because a call to the setFilterCategories() method has succeeded.

The event conveys an array of strings, representing the filter categories' identifiers.

focusItem

A "focusItem" event will be emitted whenever the item to be focused changes, either because the user has interacted with the element, or because a call to the setFocusItem() method has succeeded.

The event conveys either a string or null in its detail property. If it is a string, then it represents the focused item's identifier. If it is null, then the focus has removed.

searchCategory

DEPRECATED: use the "filterCategories" event instead.

A "searchCategory" event will be emitted whenever the search category changes, either bcause the user has interacted with the element, or because a call to the setSearchCategory() method has succeeded.

The event conveys an object with the two properties category and subcategories. category is a string, representing the main search category's identifier. subcategories is either null or an array of strings, representing the sub search categories's identifiers.

For compatibility, the "searchCategory" event gets emitted alongside the "filterCategories" event.

searchFilterText

A "searchFilterText" event will be emitted when the user enters a search query in the search input bar or when the setSearchFilterText() method gets called.

The event conveys a string representing the search query.


Last update: March 17, 2021 13:48:34