Septima Widget API

Brug Septima Widget som API når du har brug for et kort i din applikation. Her er det f.eks. muligt at tilføje data, lytte på events og meget mere. Dette kan du læse mere om herunder.

Kom igang

Ved simpel brug, tilføjes Septima Widget til hjemmesiden med f.eks.:

<div data-widget-url="https://widget.cdn.septima.dk/3.6.6/config/layer.json"></div>
<script src="https://widget.cdn.septima.dk/3.6.6/widgetconfig.js"></script>

Men hvis man gerne vil have adgang til Septima Widget som et API, kan det gøres på flere måder.

WidgetAPI fra NPM pakke

Installer npm pakke med:

npm install septima-widget

Importer WidgetAPI i din applikation:

import WidgetAPI from 'septima-widget'
 
const widget = new WidgetAPI('#map', {
  map: {
    view: {
      zoomLevel: 10,
      x: 724413,
      y: 6175985,
    },
    layer: [
      {
        namedlayer: '#dk_standard'
      }
    ]
  }
})

Modul fra CDN

Du kan importere WidgetAPI som et modul direkte fra vores CDN ind i din HTML-side:

const { default: WidgetAPI } = await import('https://widget.cdn.septima.dk/3.6.6/widgetapi.mjs')

Dine filer kan se ud på denne måde:

index.html

<div id="map"></div>
<script type="module" src="index.js"></script>

index.js

const { default: WidgetAPI } = await import('https://widget.cdn.septima.dk/3.6.6/widgetapi.mjs')
const widget = new WidgetAPI('#map', 'https://widget.cdn.septima.dk/3.6.6/config/layer.json')

Typen på script tag'et skal være module da javascripten bliver importeret som et modul. Som det ses, er endelsen på filen her .mjs og ikke js.

Eksempler

Simpelt live eksempel på brugen af modul fra CDN

Klassisk script fra CDN

Det er også muligt at benytte et klassisk script, hvor WidgetAPI kommer ind globalt:

<script src="https://widget.cdn.septima.dk/3.6.6/widgetapi.js"></script>

Dine filer kan se ud på denne måde:

index.html

<div id="map"></div>
<script src="https://widget.cdn.septima.dk/3.6.6/widgetapi.js"></script>
<script type="module" src="index.js"></script>

index.js

const widget = new WidgetAPI('#map', 'https://widget.cdn.septima.dk/3.6.6/config/layer.json')

Bemærk at det er .js, der benyttes her og .mjs.

Eksempler

Simpelt live eksempel på brugen af klassisk script

new WidgetAPI (target [, config, options])

Opret en ny Widget instans. Herved returneres et objekt. Nedenfor er objektets metoder beskrevet.

target

• Type: string

En seletor for de element, som denne Widget skal indsættes i. Det kan f.eks. være #myElement eller .map. Det er også muligt at angive et DOM element eller et jQuery element.

config

• Type: object | string

Optionel. Konfigurationen til Septima Widget. Kan være et objekt med en konfiguration eller en URL til en konfiguration. Se hvilke muligheder der er i konfigurationen her eller se de mange eksempler her.

options

• Type: Object

Optionel. Indeholder diverse parametre herunder "params". Flere funktioner i Septima Widget benytter sig af parametre, der kommer udefra, enten som URL-parametre eller parametre sat på elementet. Ved at angive de tilsvarende parametre under "params", er det muligt at få adgang til præcist værdien gennem API'et.

Eksempler

Simpelt Eksempel

Brug af params

Properties

På Widget instansen findes følgende oplysninger.

VERSION

• Type: string

Versionsnummer for den Septima Widget, der benyttes.

isReady

• Type: boolean

Indeholder status på Widget instansen. Den kan bruges til at tjekke om en Widget er klar.

Bemærk

isReady er ikke reaktiv. Det betyder at man ikke får oplysninger om at den skifter. Brug i stedet widget.on('ready') til at lytte på om Widget er klar.

Funktioner

Herunder kan du se de enkelte metoder samt tilhørende parametre.

on (event, listener)

Lyt på events, der findes på Widget API'et. Funktionen returnerer en reference til dette event og denne reference kan benyttes til at fjerne en event listener med off funktionen.

event

• Type: string

Navnet på det event, der skal lyttes på. Det kan være:

• mapmove når brugeren zoomer eller panorerer i kortet. Oplysninger om kortet sendes til listener funktionen.

• mapclick når brugeren klikker i kortet. Koordinaten hvor der er klikket, blive sendt til listener funktionen.

• maphover når brugeren flytter musen i kortet. Koordinaten hvor der musen er, blive sendt til listener funktionen.

• click når brugeren klikker på et objekt i kortet. Hvis selectable er sat til true på et lag, vil et array af objekter, der findes hvor der er klikket samt koordinaten, blive sendt til listener funktionen.

• hover når brugeren fører musen over et objekt kortet. Hvis selectable er sat til true på et lag, vil et array af objekter, der findes hvor der musen er samt koordinaten, blive sendt til listener funktionen.

• featureselected når brugeren vælger et objekt. GeoJSON for det valgte objekt sendes til listener funktionen.

• featureunselected når et objekt fravælges.

• featureadded når et objekt tilføjes til kortet. Det er f.eks. via søgefeltet. GeoJSON for det tilføjede objekt sendes til listener-funktionen.

• featureDraw når brugeren tegner et nyt objekt via tegnefunktionerne. GeoJSON for det tegnede objekt sendes til listener-funktionen.

• featureModified når brugeren redigere et objekt via tegnefunktionerne. GeoJSON for det ændrede objekt sendes til listener-funktionen.

• showlayer når et lag vises i kortet, f.eks. via lagvælgeren. Konfigurationen for laget sendes til listener-funktionen.

• hidelayer når et lag skjules i kortet, f.eks. via lagvælgeren. Konfigurationen for laget sendes til listener-funktionen.

• layeropacitychange når opacity ændres på et lag.

• layerloadstart når et rasterlag starter med at loade fra servicen. Konfigurationen for laget sendes til listener-funktionen.

• layerloadend når et rasterlag er færdig med at loade fra servicen. Konfigurationen for laget sendes til listener-funktionen.

• layerloaderror når et rasterlag fejler når det loades fra servicen. Hvis laget indeholder tiles, så kaldes eventet for hver tile, der fejler. Konfigurationen for laget sendes til listener-funktionen.

• geolocationchange når brugerens position skifter. Oplysninger om hastighed, retning, højde, nøjagtighed og position sendes som et objekt til listener-funktionen.

• dataready når vektordata på et lag er blevet hentet. Data samt konfigurationen for laget sendes til listener-funktionen.

• datareloaded når vektordata på et lag bliver genindlæst. Det sker f.eks. når et lag har "reloadinterval" antivet. Data samt konfigurationen for laget sendes til listener-funktionen.

• formsuccess når en formular går godt.

• formerror når en formular fejler.

• control.activate når en funktion aktiveres i kortet via en knap.

• control.deactivate når en funktion deaktiveres i kortet via en knap.

listener

• Type: function

Den funktion, der kaldes når dette event fyres af. Typisk kaldes funktionen med to eller tre argumenter som f.eks. dette:

function (eventname, scope, mapstate) {
  console.log(mapstate);
}

Det tredje argument er afhængigt af eventet. Nogle events har ikke noget tredje argument.

off (eventRef)

eventRef

• Type: object

Fjern en event listener. eventRef er returneret fra on metoden.

setConfig (config)

Sæt konfigurationen på en widget. Det kan bruges til at opdatere hele konfigurationen eller blot til at sætte den på et senere tidspunkt.

config

• Type: object | string

Konfigurationen til Septima Widget. Kan være et objekt med en konfiguration eller en URL til en konfiguration. Se hvilke muligheder der er i konfigurationen her eller se de mange eksempler her.

addData (geojson, options)

Tilføj data til et specifikt lag. Det er muligt at angive om andre data på laget, skal fjernes inden de nye data tilføjes, samt om der skal zoomes ind på de data, der er tilføjet.

geojson

• Type: object

Data, der skal tilføjes til Widget. GeoJSON kan indeholde én eller flere features.

options

• Type: object

Indeholder hvordan data skal vises. Det kunne f.eks. være:

{
  layerID: 'septima',
  clear: false,
  zoomOptions: {
    zoomStyle: 'slow',
    minResolution: 0.8
  }
}

layerID referere til et bestemt lag i konfigurationen.

clear angives hvis indholdet af laget skal slettes når de nye data indsættes.

zoomOptions tilføjes hvis der skal zoomes ind til de nye data og hvordan det skal gøres.

Eksempler

Tilføj data

Tilføj data med en anden projektion

removeData (layerID)

Fjerner alle data fra et specifikt lag.

layerID

• Type: string

ID på det lag, som man gerne vil fjerne data fra.

setView (options)

Sæt visning for det aktulle kortudsnit.

options

• Type: object

Indeholder hvordan data skal vises. Det kunne f.eks. være:

{
  x: 724413,
  y: 6175985,
  zoom: 7,
  zoomStyle: 'slow',
  srs: 'EPSG:25832'
}

x og y Centerpunktet for det kortudsnit, som man gerne vil zoome til.

zoom Hvilket zoom-niveau, kortudsnittet skal vise.

zoomStyle angives hvis man gerne vil have at der kommer en glidende overgang til det valgte kortudsnit.

srs angives hvis x og y er i en anden projektion end kortet er.

getView (crs)

Hent oplysinger om det aktulle kortudsnit. Funktionen returnerer et objekt i stil med:

{
  "bbox": [723618.6, 6175545, 725207.4, 6176425],
  "zoom": 10,
  "resolution": 1.6,
  "center": [724413, 6175985],
  "srs": "EPSG:25832"
}

Hvis kortet ikke er klar endnu, returneres null.

crs

• Type: object

Angiv hvilken EPSG, som oplysnignerne om aktuelle kortudsnit, skal returneres i. Angiv f.eks. EPSG:4326. Default er kortets projektion.

showLayer (layerID)

Vis et specifikt lag i kortet.

layerID

• Type: string

ID på det lag, som skal vises.

hideLayer (layerID)

Skjul et specifikt lag i kortet.

layerID

• Type: string

ID på det lag, som skal skjules.

setLayerOpacity (layerID, opacity)

Skift opacity på et specifikt lag i kortet.

layerID

• Type: string

ID på det lag, som skal ændres.

opacity

• Type: number

Værdi mellem 0 og 1, hvor 0 gør laget fuldstændig gennemsigtigt mens 1 gør det modsatte.

reloadLayer (layerID)

Tving en genindlæsning af et specifikt lag i kortet. Dette kan benyttes mod WMS lag samt vektorlag, der hentes fra en service.

layerID

• Type: string

ID på det lag, som skal genindlæses.

updateLayerParams (layerID, params)

Skift parameter til et rasterlag lag (kun WMS og VectorTile). Dette kan f.eks. bruges til at skifte lagnavnet eller andre servicespecifikke URL-parametre. Kaldet til denne funktion medfører at laget genindlæses (hvis der er sket ændringer).

layerID

• Type: string

ID på det lag, som skal opdateres.

params

• Type: object

Angiv hvilke parametre, der skal ændres. Det kunne f.eks. være:

{
  LAYERS: 'nytlag',
  TIME: '2020-06-12T09:00:00+02:00/2020-06-13T00:00:00+02:00'
}

selectFeatureInLayer (layerID, [filterFunction, zoomOptions, silent])

Markér et eksisterende objekt i kortet.

layerID

• Type: string

ID på det lag, der indeholder det objekt, der skal markeres.

filterFunction

• Type: function

En funktion, der kaldes for hver feature i det angivet lag. Funktionen skal returnere true hvis objektet skal markeres og false, hvis det ikke skal. Funktionen kaldes med objektets egenskaber, så man i funktionen kan bestemme om objektet skal markeres eller ej. Hvis funktionen ikke angives eller er null, så markeres alle objekter i det pågældende lag.

Det kunne f.eks. være et objekt med et bestemt id:

function (properties) {
  return properties.id === 3;
}

zoomOptions

• Type: object

Skal der zoomes til data når de tilføjes. Det kunne f.eks. være:

{
  minResolution: 0.1,
  buffer: 1.5,
  zoomStyle: 'slow'
}

Læs mere om zoomOptions her.

silent

• Type: boolean

Skal tilføjelsen af data ske uden at aktivere events?

deselectFeature ([silent])

Fjern alle markeringer fra kortet.

silent

• Type: boolean

Skal det ske uden at aktivere events?

showPopup (geojson, html)

Vis en popup i kortet.

geojson

• Type: object

Data, der indeholder den geometri, hvor popup'en skal vises. Geometrien bliver ikke vist i kortet. F.eks.

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [1399383, 7494393]
  }
}

html

• Type: string

HTML, der skal vises inde i popup'en.

hidePopup ()

Skjul popup, der er vist med showPopup.

draw (options)

Aktiverer tegnefunktionen i kortet. Brug eventet "featureDraw" og "featureModified" for at få den tegnede/redigerede geometri.

options

• Type: object

Data, der indeholder den geometri, hvor popup'en skal vises. Geometrien bliver ikke vist i kortet. F.eks.:

{
  layer: 'drawLayer',
  type: 'Polygon',
  clearOnDraw: true,
  modify: true
}

• layer ID på det lag der tegnes i. Husk at tilføje "edit": true på laget. Laget definerer også hvilken style der tegnes med.

• type Hvilken geometritype skal der tegnes med. Det er muligt at angive enten Point, Linestring eller Polygon.

• clearOnDraw Hvis true, så slettes indholdet i laget når brugeren begynder at tegne en ny geometri. Det bruges hvis man kun vil have én geometri vist ad gangen.

• modify Hvis true, så er det muligt at ændre eksisterende geometrier.

unDraw ()

Deaktiverer tegnefunktionen i kortet.

createMapImage (options, callback)

Gem det aktuelle kort som et billede. Funktionen kører asynkront og billedet returneres som argument til callback funktionen.

options

• Type: object

{
  type: 'clipboard',
  width: 1000,
  height: 1000
}

• type Kan bruges til at styre hvordan billedet skal komme ud. Som default kommer billedet ud som dataurl. Det er muligt at sætte type til clipboard. Herved gemmes billedet i enhedens udklipsholder og billedet kan efterfølgende indsættes i f.eks. en mail. Bemærk at hvis clipboard benyttes, skal det aktiveres via en knap.

• width Bredden af billedet i pixels. Default er den aktuelle kortbredde.

• height Højden af billedet i pixels. Default er den aktuelle korthøjde.

callback

• Type: function

Den funktion, der kaldes når billedet er klar.

transform (geojson, options, callback)

Transformér geojson fra en projektion til en anden. Funktionen modificere den geojson, der kaldes med og det foregår asynkront. callback funktionen kaldes når geometrien er transformeret.

geojson

• Type: object

Data, der indeholder den geometri, der skal transformeres. Det kan være en komplet GeoJSON med flere features, en enkelt GeoJSON feature eller blot en GeoJSON geometri. F.eks.:

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [1399383, 7494393]
  }
}

options

• Type: object

Angiv hvilken projektion, der skal transformeres fra og til.

{
  from: 'EPSG:25832',
  to: 'EPSG:4326'
}

• from Hvis crs er angivet direkte i geojson, benyttes denne. Ellers kan en EPSG kode angives i from.

• to Angiv hvilken EPSG, der skal transformeres til.

callback

• Type: function

Den funktion, der kaldes når transformationen er udført. Bemærk at input geojson ændres og derved indeholder resultatet.