# Widget

Two ways to put Tysnes Kalender's events on another website: the ready-made JavaScript widget,
or your own rendering on top of the [API](/utviklere/api).

## The JavaScript widget

A custom element, `<hsk-event-list>`, served from `https://hsk-widget.web.app/embed/hsk.js`. It
renders a filterable, paginated grid of this calendar's upcoming events, reads the API itself and
needs no key. A configurator with live preview is at [https://hvaskjer-staging.web.app/feed](https://hvaskjer-staging.web.app/feed).

Add the script once, in `<head>` or before `</body>`:

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

Then place the element where the events should appear:

```html
<hsk-event-list
  license="hvaskjer-staging"
  lan="nb"
  accentcolor="365899"
  pagesize="10"
  showmoreevents="true"
  navigationstrategy="details_url"
  detailsurl="https://hvaskjer-staging.web.app/arrangement/$event_slug"
  alleventsurl="https://hvaskjer-staging.web.app"
  columns="3"
></hsk-event-list>
```

### Attributes

| Attribute | Values | Meaning |
|---|---|---|
| `license` | `hvaskjer-staging` | Which calendar to show. Fixed for this calendar. |
| `lan` | `nb`, `en`, `auto` | Language of the labels and of the titles picked; `auto` follows the visitor's browser. |
| `accentcolor` | hex without `#` | Colour of buttons and highlights. |
| `pagesize` | 1–50 | Events per page. |
| `showmoreevents` | `true`/`false` | A "load more" button after the first page. |
| `navigationstrategy` | `details_url`, `query_parameters` | Open an event on its own page (`detailsurl`), or in place, keyed by query parameters. |
| `detailsurl` | URL with `$event_slug` | Where an event opens; `$event_slug` is replaced. Keep the value above to open the event on Tysnes Kalender. |
| `moreinfolinkdestination` | `moreinfo`, `organizer`, `facebook`, `link`, `license` | What the "more info" link points at. |
| `alleventsurl` | URL | Target of the "all events" link. |
| `showbuttonallevents` | `true` | Show that link. |
| `onlyfeatured` | `true` | Only events the organiser marked as featured. |
| `columns` | `auto`, `3`, `4`, `5` | Grid columns. |
| `rows` | `auto`, `1` | One row (a strip) or as many as the page size needs. |
| `filteringoptions` | comma list of `search`, `category`, `dates`, `venue` | Which filters the visitor gets. Omit for none. The tokens are singular. |
| `showfiltersalways` | `true` | Keep the filters open rather than behind a button. |
| `dateinpicture` | `true` | Print the date on the image instead of under it. |
| `showmapalternative` | `true` | Offer a map view next to the grid. |

Attributes that are omitted take the widget's defaults. The widget identifies itself to the API
with `X-Client-Id`; you do not send anything.

### WordPress and other CMSs

Paste both snippets into an HTML block (Gutenberg "Custom HTML", or the theme's footer scripts
for the `<script>` tag). Page builders that strip custom elements need the script tag in the
theme and the element in a raw-HTML widget.

## An iframe

Any page of https://hvaskjer-staging.web.app can be framed — the front page, a search (`/search/<term>`), a category
(`/category/<slug_nb>`, the slug from `categories`), a venue or an organizer page:

```html
<iframe src="https://hvaskjer-staging.web.app/" width="100%" height="900" style="border:0" loading="lazy" title="Tysnes Kalender"></iframe>
```

It is the full site inside a box, header and footer included, and it does not resize itself.
Use it for a quick page; use the widget for anything that should look like part of yours.

## Your own rendering

Everything the widget shows comes from the [API](/utviklere/api). Fetch it from the browser
(CORS is open) or from your server, and send `X-Page-Url` with the page's address when the call
is made from a browser embed, so a change notice can name the page it affects. Mind the
[three rules](/utviklere#the-three-rules): ids, offsets, numbers.
