# 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](/utviklere/api).

## 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](/utviklere/keys) 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>`:

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

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

```html
<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](https://hvaskjerimidtregauldal.no/feed) forhåndsviser valgene på den ekte widgeten og
skriver denne koden for deg, med reservelenken.

### Attributter

| Attributt | Verdier | Betydning |
|---|---|---|
| `license` | `hva-skjer-i-midtre-gauldal` | Hvilken kalender som vises. Fast for denne kalenderen. |
| `apikey` | nøkkelen din | Anbefalt: uten den kan ingen varsler nå deg. Fra [Nøkler](/utviklere/keys). |
| `lan` | `nb`, `en`, `auto` | Språk for etikettene og for titlene som velges; `auto` følger nettleseren til den besøkende. |
| `accentcolor` | hex uten `#` | Farge på knapper og markeringer. Skriv `365899`, ikke `#365899`: med `#` males ingenting, i begge versjoner. |
| `pagesize` | 1–50 | Arrangementer per side. |
| `showmoreevents` | `true`/`false` | En «last flere»-knapp etter første side. |
| `navigationstrategy` | `license`, `tickets`, `organizer_more_info`, `details_url`, `query_parameters` | Hvor et kort tar den besøkende. Se [Å åpne et arrangement](#å-åpne-et-arrangement). |
| `detailsmode` | `modal` | Åpne arrangementet i et vindu over siden din i stedet. |
| `detailsurl` | URL med `$event_slug` | Med `details_url`: adressen et arrangement åpnes på; `$event_slug` byttes ut. |
| `alleventsurl` | URL | Målet for «alle arrangementer»-lenken. |
| `showbuttonallevents` | `true` | Vis den lenken. |
| `columns` | `auto`, `3`, `4` | Kolonner i rutenettet, der widgeten er bred nok til dem: smalere enn omtrent 1000 piksler viser den to i bredden, og én på en telefon. Det finnes ikke stilark for andre verdier, som faller tilbake til tre. |
| `rows` | `auto`, `1` | Én rad (en stripe) eller så mange som sidestørrelsen trenger. |
| `filteringoptions` | kommaliste av `search`, `category`, `dates`, `venue`, `hours` | Hvilke filtre den besøkende får. Utelat for ingen. Ordene er i entall. `hours` har sin egen syntaks, nedenfor. |
| `showfiltersalways` | `true` | Hold filtrene åpne i stedet for bak en knapp. |
| `dateinpicture` | `true` | Skriv datoen på bildet i stedet for under. |
| `showmapalternative` | `true` | Tilby en kartvisning ved siden av rutenettet. |

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](/utviklere#de-tre-reglene), og de gjelder
din egen visning også.

### Å åpne et arrangement

`navigationstrategy` bestemmer hvor et kort tar den besøkende:

| Verdi | Et kort åpner |
|---|---|
| `license` | Arrangementets side på Hva skjer i Midtre Gauldal?, i en ny fane. |
| `tickets` | Billettsiden, i en ny fane. Et arrangement uten billettlenke åpner sin egen nettside, deretter Facebook-arrangementet, deretter siden sin på Hva skjer i Midtre Gauldal?. |
| `organizer_more_info` | Arrangementets egen nettside, i en ny fane. Uten en slik: Facebook-arrangementet, billettsiden, deretter siden sin på Hva skjer i Midtre Gauldal?. |
| `details_url` | Adressen i `detailsurl`, i samme fane, med `$event_slug` byttet ut. For en egen detaljside. |
| `query_parameters` | Arrangementet i stedet for listen, på samme side, som `?event=<slug>` i adressen. |

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](https://hvaskjerimidtregauldal.no/feed) 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:

```css
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

| URL | Hva det er |
|---|---|
| `https://hsk-widget.web.app/embed/v2/hsk.js` | Versjon 2, gjeldende. Rettelser lander her uten at du gjør noe; nettlesere cacher den i én time. |
| `https://hsk-widget.web.app/embed/2.4.1/hsk.js` | Nøyaktig 2.4.1, endres aldri. For en endringsprosess som trenger bytes som ikke kan flytte seg. Tidligere låste versjoner (`2.0.0` til `2.4.0`) blir liggende der de er; de før 2.3.0 viser utseendet til versjon 1 med mindre elementet har `theme="modern"`. |
| `hsk.esm.js` i begge mapper | Samme kode som en JavaScript-modul, for `<script type="module">` eller en bundler. |

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

```html
<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](/utviklere/keys).
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](/utviklere/changelog), 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:

```html
<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](/utviklere/api). 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](/utviklere#de-tre-reglene): id-er, forskyvninger, tall.