Embedding search components

Embed the footage.one search as web components on your website.

Overview

footage.one provides web components that let you embed a media search directly in your own website. The components connect to your footage.one account and display the media from a distribution.

Want to try the components before integrating them? Open https://ork.footage.one/demo, paste the token of a "Public search" distribution, and the search runs against your own data.

Embedding

Load the script into your HTML page:

<script src="https://ork.footage.one/asset-search/main.js"></script>

Configuration

Configure the connection to your footage.one account. You need the host and a JWT token. You obtain the token by creating a Distribution of type "Public search" — the JWT token is shown in the distribution settings.

Via HTML element

<foc-config host="https://ork.footage.one" token="your-jwt-token" language="en"></foc-config>

Via JavaScript

FoComponents.configure('https://ork.footage.one', 'your-jwt-token', 'en');

Available components

foc-result — Search results

Displays the current results list:

<foc-result link-format="/detail/%SKU%/%SLUG%"></foc-result>

The link-format defines the URL pattern for detail pages. Available placeholders:

Placeholder Value
%SKU% The asset SKU when it has the canonical form — three letters followed by digits — otherwise the UID
%SLUG% The descriptive URL slug in the request's language, supplied by the backend
%UID% The asset's internal UID

The slug is descriptive, not unique and not permanent. It is derived from the asset name in the request's language, so it changes with the language and with every rename, and different names reduce to the same string. Always identify an asset by %SKU% or %UID%: /detail/%SLUG% on its own will collide. Your detail page loads the asset by its SKU and accepts a different slug or redirects to the current one.

Use %SLUG% instead of building a slug yourself. That keeps the result list and the detail page in agreement for the same language. If an integration derives its own, the same asset ends up with different URLs.

Detail overlay instead of navigation

By default, clicking a tile follows its href. To open an overlay instead, set link-navigate="false":

<foc-result link-format="/detail/%SKU%/%SLUG%" link-navigate="false"></foc-result>

The tile keeps its real href in the markup, but the click is intercepted and only the foc:item-click event fires. Ctrl/Cmd/Shift/Alt clicks are left alone, so "open in new tab" and "save link as" keep working.

Handle that event to open your overlay. Note that the asset is on event.data, not event.detail:

document.addEventListener('foc:item-click', (event) => {
  openOverlay(event.data); // the full asset: uid, sku, slug, name, thumbnailUrl, …
});

Never set link-format="javascript:void(0)". It used to be the only way to get an overlay, but it leaves a result list without a single followable link — search engines then find none of your assets. link-navigate="false" solves the same problem without sacrificing the links.

foc-details — Asset detail view

Displays a single asset. Without the sku attribute, the SKU is read from the URL parameter sku:

<foc-details sku="DWT000342"></foc-details>

foc-facets — Filters

Displays available filter options (facets):

<foc-facets format-counter sort-by-label="codec_norm_s,resolution_ss"></foc-facets>

foc-active-facets — Active filters

Displays currently active filters with the option to remove them:

<foc-active-facets></foc-active-facets>

foc-pagination — Page navigation

<foc-pagination>
  <span slot="first">First</span>
  <span slot="previous">Previous</span>
  <span slot="next">Next</span>
  <span slot="last">Last</span>
</foc-pagination>

foc-pagesize — Results per page

<foc-pagesize sizes="8,16,32,64" default-size="16"></foc-pagesize>

foc-result-count — Result count

<foc-result-count format>
  <span slot="before-count">Total </span>
  <span slot="after-count"> results</span>
  <span slot="no-result">No results found</span>
</foc-result-count>

foc-asset-keywords — Asset keywords

Displays keywords for an asset (must be inside foc-details):

<foc-details sku="DWT000342">
  <foc-asset-keywords mode="keywords"></foc-asset-keywords>
</foc-details>

Modes: keywords, parentKeyword, freewords.

foc-asset-image — Asset image

<foc-asset-image sku="DWT000342"></foc-asset-image>

JavaScript API

Configuration can be changed at runtime:

FoComponents.changeToken('new-token');
FoComponents.changeHost('https://other-host.footage.one');
FoComponents.changeLanguage('en');
FoComponents.addFilter('aspect_norm_s', '16x9');
FoComponents.removeFilter('aspect_norm_s', '16x9');

Events

All events can be listened for on document. Their payload is on event.data, not event.detail:

Event Description
foc:result Current results list
foc:result-count Number of results
foc:facet-add A filter was added
foc:facet-remove A filter was removed
foc:facet-changed List of active filters
foc:search-start Search started
foc:search-end Search completed
foc:item-click A result tile was clicked (payload: the asset)
TeamsOverview