For utviklere

Widget

To måter å få Hva skjer i Midtre Gauldal? sine arrangementer inn på et annet nettsted: den ferdige JavaScript-widgeten, eller din egen visning bygget på API-et.

JavaScript-widgeten

Tre egendefinerte elementer: <hsk-event-list> viser et filtrerbart, paginert rutenett med denne kalenderens kommende arrangementer, <hsk-event-details> ett enkelt arrangement, og <hsk-favorites-list> arrangementene en besøkende har lagret. De henter kalenderens data selv.

Denne siden dokumenterer versjon 2. Versjon 1, skriptet på /embed/hsk.js, serveres fortsatt og virker som før; å flytte fra den er én linje og ett attributt, og siden får utseendet til versjon 2 (alt nedenfor).

Skaff en nøkkel

Lag en under Nøkler og legg den i koden. Widgeten virker uten, men nøkkelen er måten et varsel om en endring som påvirker siden din når deg før endringen kommer; uten den vet vi hvilket nettsted, ikke hvem vi skal skrive til. Nøkkelen står i sidens HTML, så den identifiserer integrasjonen din; den er ikke en hemmelighet.

Legg til skriptet og elementet

Legg til skriptet én gang per side, i <head> eller før </body>:

<script src="https://hsk-widget.web.app/embed/v2/hsk.js"></script>

Plasser så elementet der arrangementene skal vises, med en lenke inni:

<hsk-event-list
  license="hva-skjer-i-midtre-gauldal"
  apikey="<your-api-key>"
  lan="nb"
  accentcolor="365899"
  pagesize="10"
  showmoreevents="true"
  navigationstrategy="license"
  alleventsurl="https://hvaskjerimidtregauldal.no"
  columns="3"
>
  <a href="https://hvaskjerimidtregauldal.no">Alle arrangementer på Hva skjer i Midtre Gauldal?</a>
</hsk-event-list>

Det du legger mellom taggene vises til widgeten er lastet, og blir stående om den aldri lastes (skriptet blokkert, JavaScript av). Ta det alltid med.

• Uten apikey viser widgeten seg akkurat likt, og én linje i nettleserkonsollen nevner denne portalen. Med en nøkkel som er ukjent eller trukket tilbake vises den også. Et problem med en nøkkel er noe vi skriver til deg om; det blanker aldri siden din.

Byggeren på https://hvaskjerimidtregauldal.no/feed forhåndsviser valgene på den ekte widgeten og skriver denne koden for deg, med reservelenken.

Attributter

Attributter som utelates får widgetens standardverdier. Ethvert annet attributt en versjon 1-kode av din bærer (de andre fargene og skriftene, usefavorite, layout og resten) virker i versjon 2 under samme navn, med samme resultat.

Timefilteret er for et kveldsprogram. Ordet bærer vinduet sitt: filteringoptions="search,hours;start:2026-09-11T15:00:00;end:2026-09-11T23:00:00" gir en nedtrekksmeny med ett valg per time i det vinduet. Som standard viser en time arrangementene som fortsatt pågår da; med hoursfilter="start" viser den arrangementene som starter da eller senere.

For å velge et arrangement bruker widgeten id-er og slugs, aldri navn, og den viser alltid i Europe/Oslo. Det er to av de tre reglene, og de gjelder din egen visning også.

Å åpne et arrangement

navigationstrategy bestemmer hvor et kort tar den besøkende:

Legg til detailsmode="modal", og arrangementet åpnes i et vindu over siden din, uansett strategi: den besøkende forlater den aldri, og adressen får fortsatt ?event=<slug>, så det går an å lenke til arrangementet. Byggeren tilbyr tre av disse: kalenderen (license), vinduet og billettene.

Utseendet

Avrundede kort med myk skygge, bilder i fotografiets proporsjoner, én skriftskala i alle bredder og pilleknapper. Med dateinpicture står datoen på bildet, og linjen under tittelen viser bare klokkeslettet. Et arrangement med tre eller flere ulike priser viser dem som et spenn. Versjon 2 har dette ene utseendet; versjon 1 beholder sitt eget.

Filtrene er ett panel: søkelinjen og, under den, rader med brikker for når (i dag, i morgen, denne helgen, denne uken, eller datoer den besøkende velger selv), hva (kategoriene med flest arrangementer) og hvor (stedene med flest). Et trykk slår en brikke på, et nytt slår den av, og «Flere» åpner hele listen. På en telefon er hver rad en linje som ruller sidelengs. Hvilke rader som finnes, er fortsatt filteringoptions; ingenting i en kodesnutt endres.

Aksentfargen maler ikoner, kanter og toninger, aldri tekst, så ingen aksentfarge kan gjøre et kort vanskelig å lese; titlene tar titlefontcolor og resten av teksten bodyfontcolor. En mørk tilebackgroundcolor med en lys bodyfontcolor gir mørke kort, mørke filtre og mørke menyer.

Utseendet er en liten fil for seg, som lastes sammen med arrangementene. Kan den ikke lastes, viser widgeten arrangementene likevel, i en enklere utforming.

To attributter du kan ha fått

Hvis en kode du fikk tilsendt bærer onlyfeatured eller moreinfolinkdestination, slett dem. Ingen av dem har noen gang vært implementert i widgeten: vår egen konfigurator tilbød dem ved en feil, og de gjør ingenting. For å vise bare fremhevede arrangementer, bruk filter='{"onlyFeatured": true}'.

Styling fra ditt eget stilark

I versjon 2 kan aksentfargen også komme fra din CSS, for hver widget på siden samtidig:

hsk-event-list, hsk-event-details, hsk-favorites-list { --hsk-accent: #0b6e4f; }

I CSS tar fargen sin #. Et accentcolor-attributt på et element vinner over stilarket ditt. Listen bruker sidens egen skrift med mindre bodyfontfamily setter den, eller titlefontfamily titlenes.

Widgeten legger ingenting til siden din utenfor sine egne elementer: ikke noe stilark, ingen skrift, ikke noe skript, og den lar sidens tittel være i fred.

Flere widgeter på én side

Last skriptet én gang; hvert element på siden bruker det. Ikke last versjon 1 og versjon 2 på samme side. Begge definerer de samme tre elementene, og en nettleser beholder det skriptet som definerer dem først, så hele siden kjører den versjonen, i stillhet. Flytt en sides widgeter samlet.

Hva widgeten laster og hva den sender

Den laster sitt eget skript fra hsk-widget.web.app (kartet og arrangementsvisningen som egne deler, bare når en besøkende åpner dem), arrangementene fra https://hvaskjerimidtregauldal.no, og bildene fra der kalenderen lagrer dem. Å åpne kartet laster Google Maps, og et arrangement med en YouTube- eller Vimeo-video bygger den inn.

Én gang per element og sidevisning sender den en melding til https://hvaskjerimidtregauldal.no med versjonen sin, sidens adresse og nøkkelen din hvis du satte en. Vi beholder adressen uten spørrestrengen. Den meldingen bruker verken informasjonskapsler eller lagring.

Widgeten setter ingen informasjonskapsler. To valg bruker den besøkendes egen nettleser: usefavorite beholder de lagrede arrangementene der, og restorelistposition husker hvor i listen den besøkende var resten av besøket. Kjører siden din Google Analytics, rapporteres et klikk på en billettlenke dit som en ticket_click-hendelse, som i versjon 1; kjører den ingen, sendes ingenting.

Versjoner

En låst URL kan bære Subresource Integrity, så nettleseren avviser filen hvis én byte avviker:

<script src="https://hsk-widget.web.app/embed/2.4.1/hsk.js"
        integrity="sha384-naGZXblOlFXKWhm50MfDcCevFlKdfHndxY43GeQ0xMQwuqiIjrxmXhW9PB/T50YB"
        crossorigin="anonymous"></script>

Bruk integrity bare med en låst URL: /embed/v2/hsk.js endres ved hver rettelse, og sjekken ville da blokkert widgeten. Delene skriptet laster senere kommer fra samme låste mappe.

En spørrestreng som ?v=1.2.3 velger ingenting; den omgår bare din egen cache.

Flytte fra versjon 1

1. Lag en nøkkel under Nøkler.
2. Bytt skript-URL-en fra https://hsk-widget.web.app/embed/hsk.js til https://hsk-widget.web.app/embed/v2/hsk.js.
3. Legg til apikey="<your-api-key>", med nøkkelen din, på hvert element (anbefalt), og en reservelenke inni hvis det ikke finnes noen.

Elementnavnene og attributtene er de samme. Utseendet er det ikke: versjon 2 har sitt eget, det byggeren viser, så se på siden etter endringen. Gjør det for hver widget på en side samtidig (se over).

Versjon 1

https://hsk-widget.web.app/embed/hsk.js (også på /embed/v1/hsk.js) serverer fortsatt versjon 1, som ikke trenger nøkkel. Den blir avviklet, men ikke før tolv måneder etter at en dato er kunngjort i endringsloggen, og før det skriver vi til hvert nettsted vi vet bruker den.

WordPress og andre CMS

Lim begge kodebitene inn i en HTML-blokk (Gutenberg «Egendefinert HTML», eller temaets bunntekstskript for <script>-taggen). Sidebyggere som fjerner egendefinerte elementer trenger skripttaggen i temaet og elementet i en rå-HTML-widget. Behold reservelenken inni elementet.

En iframe

Enhver side på https://hvaskjerimidtregauldal.no kan rammes inn — forsiden, et søk (/search/<ord>), en kategori (/category/<slug_nb>, sluggen fra categories), en steds- eller arrangørside:

<iframe src="https://hvaskjerimidtregauldal.no/" width="100%" height="900" style="border:0" loading="lazy" title="Hva skjer i Midtre Gauldal?"></iframe>

Det er hele nettstedet inne i en boks, topp- og bunntekst inkludert, og den endrer ikke størrelse selv. Bruk den til en rask side; bruk widgeten til alt som skal se ut som en del av din.

Din egen visning

Alt widgeten viser kommer fra API-et. Hent det fra nettleseren (CORS er åpent) eller fra tjeneren din, og send X-Page-Url med sidens adresse når kallet gjøres fra en innbygging i nettleser, så et endringsvarsel kan navngi siden det gjelder. Husk de tre reglene: id-er, forskyvninger, tall.