Septima Widget API

Brug Septima Widget som API når du har brug for et kort i din applikation

ES6

Installer npm pakke med:

npm install septima-widgetapi

Importer WidgetAPI i din applikation:

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

JavaScript

Alternativt kan du tilføj scriptet fra vores CDN direkte i din HTML side:

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

Eller brug en specifik version med:

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

Din HTML fil, der bruger din kode kan se ud på denne måde:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Septima Widget</title>
  </head>
  <body>
    <div id="map"></div>
    <script src="https://widget.cdn.septima.dk/latest/widgetapi.js"></script>
    <script src="index.js"></script>
  </body>
</html>

Tilføj din kode til filen index.js. Her er et simpelt eksempel, der giver et kort:

var widget = new WidgetAPI('#map', {
    "map": {
        "view": {
            "zoomLevel": 10,
            "x": 724413,
            "y": 6175985
        },
        "layer": [
            {
                "namedlayer": "#dk_standard",
            }
        ]
    }
});

API

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

new WidgetAPI (target [, config, options])

Herved returneres et objekt. Nedenfor er objektets metoder beskrevet.

parameter type beskrivelse
target 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 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 konfigurations dokumentationen her eller se de mange eksempler på her.
options 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

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.

parameter type beskrivelse
config 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 konfigurations dokumentationen her eller se de mange eksempler på 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.

parameter type beskrivelse
geojson Object Data, der skal tilføjes til Widget. GeoJSON kan indeholde én eller flere features.
options 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

removeData (layerID)

Fjerner alle data fra et specifikt lag.

parameter type beskrivelse
layerID String ID på det lag, som man gerne vil fjerne data fra

setView (options)

Sæt visning for det aktulle kortudsnit.

parameter type beskrivelse
options 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.

showLayer (layerID)

Vis et specifikt lag i kortet.

parameter type beskrivelse
layerID String ID på det lag, som skal vises

hideLayer (layerID)

Skjul et specifikt lag i kortet.

parameter type beskrivelse
layerID String ID på det lag, som skal skjules

setLayerOpacity (layerID, opacity)

Skift opacity på et specifikt lag i kortet.

parameter type beskrivelse
layerID String ID på det lag, som skal skjules
opacity 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.

parameter type beskrivelse
layerID 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).

parameter type beskrivelse
layerID String ID på det lag, som skal genindlæses
params 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.

parameter type beskrivelse
layerID String ID på det lag, der indeholder det objekt, der skal markeres.
filterFunction 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 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'
}

minResolution Hvor langt skal det højst zoomes ind. Angives i meter pr pixel.

buffer Hvor meget luft der mindst skal være omkring de features, der zoomes til. Buffer angives som et forhold, det vil sige at 1.2 lægger 20% til, mens 1.5 lægger 50% til.

zoomStyle angives hvis man gerne vil have at der kommer en glidende overgang til det valgte kortudsnit.
silent Boolean Skal tilføjelsen af data ske uden at aktivere events?

deselectFeature ([silent])

Fjern alle markeringer fra kortet.

parameter type beskrivelse
silent Boolean Skal det ske uden at aktivere events?

showPopup (geojson, html)

Vis en popup i kortet.

parameter type beskrivelse
geojson 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 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.

parameter type beskrivelse
options 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.

parameter type beskrivelse
options 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 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.

parameter type beskrivelse
geojson 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 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 Function

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

on (event, callback)

Events, der findes på Widget API'et.

parameter type beskrivelse
event 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 callback funktionen.

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

maphover når brugeren flytter musen i kortet. Koordinaten hvor der musen er, blive sendt til callback 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 callback 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 callback funktionen.

featureselected når brugeren vælger et objekt. GeoJSON for det valgte objekt sendes til callback 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 callback-funktionen.

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

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

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

hidelayer når et lag skjules i kortet, f.eks. via lagvælgeren. Konfigurationen for laget sendes til callback-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 callback-funktionen.

layerloadend når et rasterlag er færdig med at loade fra servicen. Konfigurationen for laget sendes til callback-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 callback-funktionen.

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

dataready når vektordata på et lag er blevet hentet. Data samt konfigurationen for laget sendes til callback-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 callback-funktionen.

formsuccess når en formular går godt.

formerror når en formular fejler.
callback 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.