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-5.js"></script>
<script src="https://scripts-test.discover.swiss/webcomponents/discover-swiss-mapbox-3.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",
"https://cdn-test.discover.swiss/css/infobox-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,
"eventLink": {
"enable": true,
"title": "open details"
},
"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 'plc_4kq_cfdfjafd'"
]
}
}
}
'
/>
</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:
if mapbox.controls.filter
is defined, then true
. Otherwise false
.
Note: due to the limited data that's contained in IndexResponse
objects,
filtering by category and tag can only be done if search.useIndexOnly
is
false
(default).
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 a valid, non-null value, lets the map know it is used for displaying guide points.
Valid non-null values are:
"ds-guide"
"guarda-guide"
(deprecated)"guide"
(deprecated)"prismic-guide"
"susch-guide"
(deprecated)
Deprecated subtypes will be removed in the following major versions.
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.filter
¶
The position of the filter controls. The value can be:
"top-left"
"top-right"
"bottom-left"
"bottom-right"
null
: don't show the filter controls.
Default value: null
Note: the filter controls require search.request.facets
to select some
facets that are suitable for filtering. Otherwise no filter options will be
available.
Following facets are suitable for filtering:
"campaignTag"
"categoryTree"
"sourcePartner"
"tag"
For each facet "scope"
has to be set to "all"
, "current"
, or "parent"
.
An example configuration for search.request.facets
:
[
{
"name": "campaignTag",
"responseName": "Custom Campaign Tag Name"
},
{
"name": "categoryTree",
"count": 100,
"scope": "all"
},
{
"name": "sourcePartner",
"filterValues": [
"tessvm"
],
"scope": "all"
},
{
"name": "tag",
"filterValues": [
"accessibility-wheelchair-accessible",
"reduction-general"
],
"scope": "all"
}
]
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.controls.trackStyle
¶
The position of the track style controls.
The value can be either null
, a string, or an object.
If it is null
, then the track style control is disabled.
If it is a string, then it specifies the control's position.
Following positions are recognized:
"top-left"
"top-right"
"bottom-left"
"bottom-right"
If it is an object, then it can have following properties:
enable
: boolean that enables or disables the control. Default value:true
-
initialStyle
: string that specifies the initial track style.Following styles are recognized:
"pin"
"tour"
Default value:
"pin"
-position
: string that specifies the control's position as described above. Default value:"top-right"
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"
This is the marker image shown when no more specific marker image is configured.
-
"marker-type:<Type>"
This allows to specify markers for a given type when there is no matching campaign tag marker image configured. For this identifier to match an item,
<Type>
has to exactly match the item's type field.Example:
{ "marker-type:schema.org/Tour" }
-
"marker-campaign-tag:<CampaignTag>"
This allows to specify markers for items that have a given campaign tag. For this identifier to match an item, it must contain the exact tag in its
campaignTag
field.Example:
{ "marker-campaign-tag:demo_recommendation" }
-
"sign-closed"
This is the image drawn on tours that are closed.
-
"sign-open"
This is the image drawn on tours that are open.
-
"sign-warning"
This is the image drawn on tours for which a warning exists.
Default value:
{
"marker-default": "https://cdn.discover.swiss/icons/map/pin_2x.png",
"sign-closed": "https://cdn.discover.swiss/icons/map/closed_1x.png",
"sign-open": "https://cdn.discover.swiss/icons/map/open_1x.png",
"sign-warning": "https://cdn.discover.swiss/icons/map/warning_1x.png"
}
mapbox.infobox.enable
¶
Specifies whether the infobox (popup) should be shown when clicking on a map feature. The value is a boolean.
The infobox can be styled using stylesheets by adding them using map.stylesheets
.
Available classes for styling are documented in
the infobox example stylesheet.
Default value: false
mapbox.infobox.eventLink.enable
¶
Specifies whether the infobox should contain a link that will produce
an "infoboxItem"
event.
The value is a boolean.
Default value: false
mapbox.infobox.eventLink.title
¶
Specifies the text to be used for the event link. The value is a string.
Default value: "open item"
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.
mapbox.infobox.templateConfig.showLink
¶
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.traceVisibleItems
¶
Specifies whether to emit "visibleItems"
events whenever the set of visible
items on the map changes.
The value is a boolean.
Default value: false
.
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
search
¶
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.fetchReviews
¶
Specifies whether recommended POIs / reviews should be retrieved in addition
to the items retrievable by search.request
.
The value is a boolean.
If set to true
, then the search request will be extended to include all
review items. Otherwise the unaltered search request will be used.
Default value: false
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
, currentPage
, and resultsPerPage
are not
configurable.
The attribute select
is not configurable while search.useIndexOnly
is
set to false
.
Any unconfigurable attribute in search.request
will be ignored silently as
they are used by the <discover-swiss-search>
component internally.
_Note: if not configured explicitly, the project
attribute will be set to
[ config.search.infocenter.project ]
.
For details about the FullSearchRequest
schema, see
the documentation of the search API.
search.resultsPerPage
¶
Specifies the number of results per page when using the search API. This value is a positive integer.
Default value: 1000
search.useIndexOnly
¶
Specifies whether only the IndexResponse
objects returned by a search
request should be used, or whether proper objects should be fetched.
The value is a boolean.
Setting it to true
will synthesize objects from IndexReponse
objects.
Setting it to false
will in addition to the search fetch proper objects.
Default value:
false
if map.layout
is set to "default"
;
true
if map.layout
is set to "simple"
Note: to fine tune the fields to be fetched, the search.request.select
option can be used. It is recommended to always explicitly select all
necessary fields as this will improve performance, e.g.
"identifier,name,type,additionalType,geo,link,lastModified,campaignTag"
.
For details about the IndexReponse
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.
center
¶
The center
property can be used to query or set the map's geographical
centerpoint.
Its value is an array of two numbers representing longitude and latitude, in that order.
Note that this value is only accurate outside of transitioning effects.
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.
zoom
¶
The zoom
property can be used to query or set the map's zoom level.
Its value is a number.
Note that this value is only accurate outside of transitioning effects.
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.
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.
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.
setFilterItemType(itemType)
¶
Set the item type to be used for filtering.
Parameters¶
itemType
¶
The itemType
parameter is either a string or null
.
If it is a string, then it represents the item type to be used for filtering.
If it is null
, then no filtering based on item type will be performed.
Available item types are
- "schema.org/AdministrativeArea"
- "schema.org/CivicStructure"
- "schema.org/Condition"
- "schema.org/Event"
- "schema.org/FoodEstablishment"
- "schema.org/LocalBusiness"
- "schema.org/LodgingBusiness"
- "schema.org/Place"
- "schema.org/SkiResort"
- "schema.org/Tour"
- "schema.org/Webcam"
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.
triggerGeolocateControl()
¶
The triggerGeolocateControl()
method is used to trigger a geolocation event
via mapbox's geolocate control. This method has no effect if no geolocate
control is configured, i.e. when mapbox.controls.geolocate
is set to null
(default).
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.
"filterItemType"
¶
A "filterItemType"
event will be emitted whenever the filter item type
changes, either bcause the user has interacted with the element, or because a
call to the setFilterItemType()
method has succeeded.
If it is a string, then it represents the item type to be used for filtering.
If it is null
, then no filtering based on item type will be performed.
For available category identifiers, see
the description of setFilterItemType()
's itemType
parameter.
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.
"geolocate"
¶
A "geolocate"
event will be emitted for each successful Geolocation API
position update.
The event conveys a
GeolocationPosition
object in its detail
property.
"infoboxItem"
¶
An "infoboxItem"
event will be emitted whenever the event link in the
infobox gets clicked.
The event conveys a string in its detail
property.
The string represents the identifier of the item shown in the infobox.
For information about the event link, see the mapbox.infobox.eventLink
properties.
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.
"visibleItems"
¶
A "visibleItems"
event will be emitted whenever the set of visible items on
the map changes.
The event conveys a list of strings in its detail
property.
The strings in the list represent the identifiers of the items show on the map.