HTML

specstableimplmature

HTML encoding for every supported resource.

Scope

Conformance Classes

JSON implements all requirements of conformance class HTML from OGC API - Features - Part 1: Core 1.0open in new window for the resources Landing Page, Conformance Declaration, Feature Collections, and Feature Collection.

Configuration

Customization

The HTML encoding is implemented using Mustache templatesopen in new window which can be overridden by the user. Any template may be overridden but doing so for non-empty templates is strongly discouraged since it will most certainly lead to issues on updates.

There are predefined empty templates prefixed with custom- that should cover most use cases:

  • custom-head.mustache: add something to the <head> element, e.g. CSS styles
  • custom-body-start.mustache: add something at the start of the <body> element
  • custom-body-end.mustache: add something at the end of the <body> element
  • custom-navbar-start.mustache: add something at the left side of the navbar
  • custom-navbar-end.mustache: add something at the right side of the navbar
  • custom-footer-start.mustache: add something at the start of the footer
  • custom-footer-end.mustache: add something at the end of footer
  • custom-footer-url.mustache: add a link to the list at the right of the footer

These templates have to reside in the data directory either under the relative path templates/html/{templateName}.mustache if you are still using the old layout (deprecated, will stop working in v4) or under resources/html/templates/{templateName}.mustache with the new layout.

Custom assets

It is also possible to publish any custom files, e.g. CSS files that can then be included in custom-head.mustache. The files have to reside in the data directory either under the relative path store/resources/html/assets/ if you are still using the old layout (deprecated, will stop working in v4) or under resources/html/assets/ with the new layout.

For example the CSS file resources/html/assets/my.css could be included in custom-head.mustache with <link href="{{urlPrefix}}/custom/assets/my.css" rel="stylesheet" >.

Login Provider

For APIs with restricted access using an identity provider with login capabilities, the loginProvider option can be set to enable automatic redirects to the login form of the identity provider for restricted HTML pages. The logged-in user will also be shown on all HTML pages along with a logout button.

Warning

This functionality uses cookies to retain the login information when navigating between HTML pages. The cookies are neither processed nor passed on to any third party.

In regard to the European GDPR and the German TTDSG we would deem these cookies as technically required. That means if you publish an API with this functionality, you would be required to mention these cookies in the privacy policy.
:::6

Info

If the identity provider uses https (which it should), this feature only works if the API is also published using https. The only exception is accessing an API on localhost.

Options

NameDefaultDescriptionTypeSince
buildingBlock
Always HTML.
string
v2.0
extensionType
Deprecated See buildingBlock.
string
v2.0
enabled
true
Enable the building block?
boolean
v2.0
noIndexEnabled
true
Set noIndex for all sites to prevent search engines from indexing.
boolean
v2.0
schemaOrgEnabled
true
Enable schema.orgopen in new window annotations for all sites, which are used e.g. by search engines. The annotations are embedded as JSON-LD.
boolean
v2.0
microdataEnabled
true
Deprecated See schemaOrgEnabled.
boolean
v2.0
collectionDescriptionsInOverview
false
Show collection descriptions in the HTML representation of the Feature Collections resource.
boolean
v2.0
suppressEmptyCollectionsInOverview
false
Suppress collections without items in the HTML representation of the Feature Collections resource.
boolean
v3.4
sendEtags
boolean
v2.0
legalName
Legal notice
Label for optional legal notice link on every site.
string
v2.0
legalUrl
null
URL for optional legal notice link on every site.
string
v2.0
privacyName
Privacy notice
Label for optional privacy notice link on every site.
string
v2.0
privacyUrl
null
URL for optional privacy notice link on every site.
string
v2.0
defaultStyle
NONE
A default style in the style repository that is used in maps in the HTML representation of the feature and tile resources. If NONE, a simple wireframe style will be used with OpenStreetMap as a basemap, if the map client is MapLibre; for Cesium, the default 3D Tiles styling will be used with the basemap. If the value is not NONE and the map client is MapLibre, the API landing page (or the collection page) will also contain a link to a web map with the style for the dataset (or the collection).
string
v2.0
basemapUrl
https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png
URL template for background map tiles.
string
v2.0
basemapAttribution
&copy; <a href='http://osm.org/copyright'>OpenStreetMap</a> contributors
Source attribution for background map.
string
v2.0
leafletUrl
https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png
Deprecated See basemapUrl.
string
v2.0
leafletAttribution
&copy; <a href='http://osm.org/copyright'>OpenStreetMap</a> contributors
Deprecated See basemapAttribution.
string
v2.0
openLayersUrl
https://{a-c}.tile.openstreetmap.org/{z}/{x}/{y}.png
Deprecated See basemapUrl.
string
v2.0
openLayersAttribution
&copy; <a href='http://osm.org/copyright'>OpenStreetMap</a> contributors
Deprecated See basemapAttribution
string
v2.0
footerText
null
Additional text shown in footer of every site.
string
v2.0
loginProvider
null
Option to enable automatic redirects to the login form of an identity provider. The value is the id of a provider with login capabilities in the global configuration. Also see Login Provider.
string
v2.0
additionalApis
array
v2.0

Examples

Example of the specifications in the configuration file (from the API for Topographic data in Daraa, Syriaopen in new window):


- buildingBlock: HTML
  enabled: true
  noIndexEnabled: true
  schemaOrgEnabled: true
  defaultStyle: topographic

Example of the specifications in the configuration file (from the API for Vineyards in Rhineland-Palatinate](https://demo.ldproxy.net/vineyardsopen in new window)):


- buildingBlock: HTML
  enabled: true
  noIndexEnabled: false
  schemaOrgEnabled: true
  collectionDescriptionsInOverview: true
  legalName: Legal notice
  legalUrl: https://www.interactive-instruments.de/en/about/impressum/
  privacyName: Privacy notice
  privacyUrl: https://www.interactive-instruments.de/en/about/datenschutzerklarung/
  basemapUrl: https://sg.geodatenzentrum.de/wmts_topplus_open/tile/1.0.0/web_grau/default/WEBMERCATOR/{z}/{y}/{x}.png
  basemapAttribution: '&copy;<a href="https://www.bkg.bund.de" target="_new" >Bundesamt f&uuml;r Kartographie und Geod&auml;sie</a>(2020), <a href="https://sg.geodatenzentrum.de/web_public/Datenquellen_TopPlus_Open.pdf" target="_new" >Datenquellen</a>'
  defaultStyle: default