Indlejring (embed)

Forfatter: Martin Høgh, Lars Lindenborg Jensen, Henrik Brændskov Larsen

Hvad er indlejring?

Med embed kan du vise et Vidi-kort direkte på en anden hjemmeside. Det er nyttigt, når du vil vise et fokuseret kort uden hele den almindelige Vidi-brugerflade.

Et embed består typisk af tre dele: embed.js, et div-element med data-attributter og et token, som peger på et gemt projekt eller en bestemt opsætning.

I praksis bruges embed ofte sammen med en særlig konfiguration, så du kan styre hvilke funktioner, lag og brugergrænseflade-elementer der skal vises i det indlejrede kort.

Kom hurtigt i gang

Den hurtigste måde at komme i gang er:

Indlæs embed.js fra den Vidi-installation, som kortet skal hentes fra
Indsæt et div-element med et token
Angiv bredde og højde på kortet, f.eks. i % eller px

Et minimalt eksempel ser sådan ud:

<script src="https://example.com/js/embed.js"></script>

<div
  data-vidi-token="eyJ0aXRsZSI..."
  data-vidi-width="100%"
  data-vidi-height="600px"
></div>

Scriptet kan ligge både i <head> og i bunden af siden.

Hvornår bruges embed?

Embed bruges typisk, når kortet skal indgå som en del af en anden løsning, og hvor oplevelsen skal være enklere end den fulde Vidi-applikation.

Det kan f.eks. være, når du vil:

vise et kort på en ekstern hjemmeside eller portal
starte kortet i en bestemt konfiguration eller visning
skjule dele af standard-menuen og kun vise det vigtigste
aktivere udvalgte funktioner som søgning, info eller koordinater
styre baggrundskort, tabeller og splash-skærme via en særskilt konfiguration

Sådan hænger det sammen

Et embed består typisk af tre dele:

embed.js, som indlæser det indlejrede kort
et projekt-token, som peger på den gemte kortopsætning
en konfigurationsfil, som styrer funktioner, lag og brugeroplevelse

I praksis er arbejdsdelingen ofte sådan:

HTML bestemmer hvor og hvor stort kortet vises
tokenet peger på projektet og evt. den tilknyttede konfiguration
konfigurationsfilen styrer lag, søgning, baggrundskort, templates og øvrige funktioner

Hvis du arbejder med projekter og tokens som grundlag for embed, er det relevant at kende projekter i Vidi.

Grundlæggende data-attributter

Nedenfor er de vigtigste data-attributter til den grundlæggende embed-opsætning. Attributter til at vise og skjule funktioner er samlet i et særskilt afsnit længere nede.

Obligatoriske attributter

data-vidi-token
Projektets token med oplysninger om fx state-id, host og database.

Størrelse og visning

data-vidi-width – bredde på kortet (standard: 100%). Kan angives f.eks. som 100% eller 800px
data-vidi-height – højde på kortet (standard: 100%). Kan angives f.eks. som 600px eller 100%
data-vidi-title – sætter title på den genererede iframe
data-vidi-frame-name – navn på kortet (skal bruges, hvis du vil bruge Embed API)
data-vidi-tmpl – vælger template (typisk embed.tmpl)

Konfiguration og overrides

data-vidi-use-config="true" – bruger config fra token (hvis den findes)
data-vidi-use-schema="true" – bruger schema fra token (hvis det findes)
data-vidi-host="https://example.com" – overskriver host fra token
data-vidi-schemata="..." – filtrerer hvilke lag (schemata) der hentes
data-vidi-no-tracking="true" – undgår tracking-cookie

Konfigurationsfilen i praksis

Konfigurationsfilen er det sted, hvor du typisk tilpasser selve embed-oplevelsen. Det er her, du begrænser lag, styrer søgning, vælger baggrundskort og bestemmer hvilke funktioner der skal være aktive.

Når embed’et indlæses med data-vidi-use-config="true", bruges den tilknyttede konfiguration som grundlag for kortet.

Et minimalt eksempel på en embed-konfiguration kan se sådan ud:

{
  "schemata": ["public", "tag:embedMap"],
  "template": "default.tmpl",
  "startupModalSupressionTemplates": ["embed.tmpl"],
  "brandName": "Demo af et embed kort",
  "enabledSearch": "danish",
  "activateMainTab": "info",
  "enabledExtensions": ["embed", "coordinates"],
  "vectorTable": {
    "position": "bottom",
    "width": "100%",
    "height": "250px"
  },
  "baselayerDrawer": true,
  "baseLayers": [
    {
      "type": "wms",
      "url": "/api/dataforsyningen/forvaltning2",
      "layers": ["Basis_kort", "Stednavne_basiskort", "Vejnavne_basiskort", "Husnummer"],
      "id": "ForvaltningskortDF",
      "name": "Forvaltningskort",
      "maxZoom": 22,
      "maxNativeZoom": 20,
      "inDrawer": true,
      "thumbnail": "https://static.geopartner.dk/images/drawer_forvaltning_sag.png"
    }
  ]
}

De vigtigste felter i eksemplet er typisk:

schemata: afgør hvilke lag der stilles til rådighed i løsningen
template: angiver udgangspunktet for visningen
startupModalSupressionTemplates: bruges til at undgå splash-skærme i embed-visningen
enabledExtensions: aktiverer de udvidelser embed’et skal bruge
vectorTable: styrer placering og størrelse på attributtabellen
baseLayers: angiver hvilke baggrundskort der skal være tilgængelige
inDrawer: true: viser baggrundskortet i listen over valgbare baggrundskort
thumbnail: angiver preview-billedet til baggrundskortet

I praksis bruges schemata ofte til at begrænse embed-løsningen til få udvalgte lag. Et almindeligt mønster er at vise lag fra public samt lag, der er mærket med et særligt tag som f.eks. embedMap.

template sættes ofte til default.tmpl i selve konfigurationsfilen, selv om HTML’en senere bruger data-vidi-tmpl="embed.tmpl". Det gør det muligt at genbruge samme konfiguration som udgangspunkt og først skifte til egentlig embed-visning i HTML-koden.

Hvis du vil se en mere komplet konfiguration med flere baggrundskort, søgeopsætning, splash-skærm og øvrige indstillinger, kan du bruge config-filen på GitHub.

Lag og opsætning i GC2

Lagene til et embed sættes som udgangspunkt op i GC2 på samme måde som andre lag, men i praksis vil man ofte begrænse løsningen mere end i den normale Vidi-visning.

Det gøres typisk ved at:

lade schemata i konfigurationen pege på få udvalgte schemaer eller tags
mærke relevante lag med et tag som f.eks. embedMap
sikre at lagenes authentication passer til en offentlig løsning, ofte None eller Write

Hvis laget skal vises med attributter i en tabel, kræver det typisk både en indstilling i GC2 og en indstilling i konfigurationen.

I GC2 skal du først aktivere tabelvisning for laget under Meta. Hvis oplysningerne primært skal vises i tabellen, er det ofte også en god idé at slå almindelig feature info fra for laget.

Opsætning af tabelvisning under Meta for et lag i GC2 — Aktivér tabelvisning for laget under Meta i GC2.

Opsætning af Disable feature info for et lag i GC2 — Overvej at slå almindelig feature info fra, hvis oplysninger i stedet skal vises i tabellen.

I konfigurationsfilen kan du derefter styre, hvordan tabellen vises i embed’et. Et typisk eksempel ser sådan ud:

"vectorTable": {
  "position": "bottom",
  "width": "100%",
  "height": "250px"
}

Her betyder det, at attributtabellen placeres nederst i kortet, fylder hele bredden og får en fast højde på 250px.

Det er ofte en praktisk opsætning i embed-løsninger, fordi tabellen bliver let at læse uden at overtage hele visningen. Samtidig giver det en mere rolig brugeroplevelse, når information enten vises i tabellen eller direkte på kortet, men ikke begge steder på samme tid.

Opsætning af projekt i Vidi

Den sidste del af opsætningen sker normalt i selve Vidi:

Start kortet med den relevante konfiguration.
Tænd de lag, der skal være synlige i embed’et.
Sæt eventuelle filtre, vælg baggrundskort og zoom til det ønskede område.
Gem opsætningen som et projekt under Bruger gemte projekter .
Kopiér projektets token med knappen Token og brug det i data-vidi-token.

Det er denne arbejdsgang, der binder konfigurationen og den konkrete kortvisning sammen i et brugbart embed.

Vis/skjul-attributter for funktioner

Ud over de grundlæggende data-attributter kan du styre, hvilke funktioner der er synlige i den indlejrede visning. Det bruges ofte til at gøre embed-løsningen mere enkel end den almindelige Vidi-visning.

Som udgangspunkt synlige (skjules med `="none"`)

data-vidi-brand
data-vidi-search
data-vidi-history
data-vidi-legend
data-vidi-layer
data-vidi-background
data-vidi-fullscreen
data-vidi-about
data-vidi-location
data-vidi-signin
data-vidi-toggler

Eksempel:

<div
  data-vidi-token="eyJ0aXRsZSI..."
  data-vidi-search="none"
  data-vidi-signin="none"
  data-vidi-width="100%"
  data-vidi-height="500px"
></div>

Her skjules funktionerne ved at sætte attributten til "none". De slås altså ikke fra med false.

Denne type opsætning er nyttig, når embed-kortet primært skal bruges til visning og ikke som fuldt arbejdsredskab.

Som udgangspunkt skjulte (kan vises med `inline`)

data-vidi-measurement
data-vidi-boxzoom
data-vidi-reset
data-vidi-clear
data-vidi-screenshot

Eksempel:

<div
  data-vidi-token="eyJ0aXRsZSI..."
  data-vidi-measurement="inline"
  data-vidi-screenshot="inline"
  data-vidi-width="100%"
  data-vidi-height="600px"
></div>

Denne type opsætning er nyttig, når embed-kortet stadig skal være enkelt, men hvor brugeren skal kunne måle, tage screenshots eller rydde kortet.

Komplet HTML-eksempel

Her er et enkelt HTML-eksempel på, hvordan et embed kan indsættes på en side:

<!DOCTYPE html>
<html lang="da">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Eksempel på indlejret Vidi-kort</title>
    <script src="https://mapgovidi.geopartner.dk/js/embed.js"></script>
    <style>
      body {
        font-family: sans-serif;
        margin: 2rem;
      }

      .embed-wrapper {
        max-width: 1200px;
      }
    </style>
  </head>
  <body>
    <h1>Eksempel på indlejret kort</h1>

    <p>
      Her vises et Vidi-projekt som embed på en almindelig HTML-side.
      Kortet hentes via et token og bruger en tilknyttet konfigurationsfil.
    </p>

    <div class="embed-wrapper">
      <div
        data-vidi-token="eksempel-token-skal-erstattes"
        data-vidi-width="1200px"
        data-vidi-height="800px"
        data-vidi-tmpl="embed.tmpl"
        data-vidi-use-config="true"
        data-vidi-legend="none"
        data-vidi-layer="none"
      ></div>
    </div>
  </body>
</html>

I dette eksempel:

hentes embed.js fra den konkrete Vidi-installation
bruges et projekt-token, som også indeholder reference til en konfigurationsfil
sættes størrelse direkte i HTML med 1200px og 800px
vælges embed.tmpl, så kortet bruger embed-layoutet
bruges data-vidi-use-config="true", så den tilknyttede konfigurationsfil aktiveres
skjules signaturforklaring og lagliste direkte i embed-visningen

Det komplette eksempel ligger også som separate filer på GitHub:

Live demo

Nedenfor vises et rigtigt eksempel på et indlejret kort. Demoen henter en separat HTML-side fra dokumentationssitets public-mappe, som igen indlæser embed.js, projekt-token og konfiguration.

Embed API

Embed-scriptet udstiller et API, så du kan styre kortet fra din egen side.

De mest brugte funktioner er:

embedApi.switchLayer(layername, on, frame)
Tænder/slukker et lag.
embedApi.allOff(frame)
Slukker alle tændte lag.

Eksempler:

embedApi.switchLayer('planer.lokalplan', true, 'plankort')
embedApi.allOff('plankort')

Hvis du vil bruge Embed API, er det en god idé at sætte data-vidi-frame-name, så du entydigt kan referere til det indlejrede kort.

Callbacks (når kortet er klar)

Du kan sætte callbacks til:

Når Vidi er loaded og klar
Når projektets aktive lag er loaded

Hvis kortet er indlejret med data-vidi-frame-name="kort1", kan du gøre sådan:

embedApi.vidiReady['kort1'] = () => {
  console.log('Vidi er klar')
}

embedApi.activeLayersReady['kort1'] = () => {
  console.log('Aktive lag er klar')
}

Fejlfinding og godt at vide

Embed virker kun, hvis tokenet er gyldigt og peger på et eksisterende projekt eller en gyldig opsætning.
Hvis du bruger data-vidi-use-config="true", vil ændringer i konfigurationen slå igennem i embed-visningen.
Hvis embed.js hentes fra en anden host end den, tokenet forventer, kan embed’et fejle eller opføre sig uventet.
Hvis du vil styre kortet fra JavaScript, skal du huske at sætte data-vidi-frame-name.
Hvis indhold mangler i embed-visningen, skal du først kontrollere projekt, token og konfiguration, før du fejlsøger på selve HTML-koden.