Adapters

Adapters connect the Anura front-end components to an upstream source, usually a DAM. At least one is required.

bynder celum

pixx.io sharedien

anura-adapter

All adapters have to extend the anura-adapter in order to inherit some utility functions, namely:

  • Translations
    • translate(key, args) - labels translated into the current locale. Supports arbitrary arguments, e.g. the key pageX is translated as Page {page}, expecting {page: 5} in the args. So translate('pageX', {page: 5}) results in Page 5
    • setTranslation(multiMap) - overload the built-in translations, e.g. setTranslation({en: {myKey: 'new value'}, de: {myKey: 'neuer Wert'}})
  • States - stored in the URL as query parameters inside window.location.hash (so you can copy-paste stateful links). Prefix is an arbitrary prefix to your key in order to support multiple instances of the same component on one page.
    • hasState(prefix, key) - test if a given key is present
    • getState(prefix, key, fallback) - get the value of a given key, or your fallback value if not present
    • getStates() - get all states
    • setState(prefix, key, value) - set a value for a given key
    • setStates(array) - set multiple states at once. Note that you must deal with prefix yourself.
    • removeState(prefix, key) - removes the value for a given key (including the key itself)
    • removeStates(prefix, fragment) - remove multiple values whose key starts with fragment

When implementing your own adapter, be sure to inform super() in attributeChangedCallback and connectedCallback.

Common Attributes

license

required: yes (except on localhost), default: -

The license (delivered by brix) enabling you to use the adapter (yeah... gotta eat..). This is based either on the hostname presenting the content, or the source thereof.

for ease of development, localhost is enabled without a license.

<some-adapter license="askus"></some-adapter>

locale

required: no, default: the page's language (en if not declared)

ISO 639-1 code for the language you'd like to use. Defaults to <html lang=...> if present or en otherwise. Defaults to en when the requested string is not present in a given language. Note that translation files are loaded asynchronously and relative to the adapter's location.

Supported languages: bg, cz, de, en, es, fr, hu, it, ro, sk and sl. Contributions are welcome :-)

<some-adapter locale="de"></some-adapter>

facets

required: no, live: on-load, default: true

Set this to false to disable faceted search for all downstream components. Some adapters will do this automatically when that DAM doesn't support faceted search.

<some-adapter facets="false"></some-adapter>

state

required: no, live: no, default: true

Set this to false to disable states in all downstream components (state persists a component's state in the URL, e.g. for sharing deep-links).

order-key

required: no, live: on-load, default: -

Metadata key on which to forbid a direct download and force the user to use asset-order instead. Note that this is not particularly secure, as advanced users can simply fiddle with this - so if your backend supports such granular permissions, use those instead. Currently this is only implemented for Sharedien (and is not necessary for CELUM).

When used, you MUST set an order-value as well, which defines what value should be expected that forbids a download, i.e.

<some-adapter asset-order="https://asset.order/instance" order-key="copyrighted" order-value="true"></some-adapter>

asset-order

required: only then using order-key, live: on-load, default: -

Depending on your DAM, it may not feature an asset ordering process, so you need to define where an external (brix) asset order server lives.

<some-adapter asset-order="https://some.order.url"></some-adapter>

Events

load

A regular load-event, can be used to set translations, e.g.

<some-adapter locale="de" onload="this.setTranslation({en: {loadMore: 'gimme more'}})"></celum-adapter>

adapter-reloading

{detail: {name: name, oldValue: oldValue, newValue: newValue}}

Fired when any attribute has been changed, indicating that components hooked up to this adapter may want to reload themselves, e.g. because the locale has changed (leading edge).

adapter-reloaded

{detail: {name: name, oldValue: oldValue, newValue: newValue}}

Fired after the adapter has reloaded itself, indicating that components hooked up to this adapter may want to reload themselves, e.g. because the locale has changed (trailing edge).

bynder-adapter

Connects to any Bynder server using their v4-API.

<bynder-adapter url="https://some-instance.bynder.com" token="xxx"></bynder-adapter>

Attributes

url

required: yes, default: -

The URL where the back-end endpoint is located, e.g. https://some-sandbox.bynder.com

token

required: yes, default: -

API-Token to use, see Advanced Settings > Portal Settings > Permanent Tokens. We'd recommend creating a separate user for it, as this will basically be public information for anyone looking at the source.

video-previews

required: no, default: -

Whether to display video previews instead of showing a large thumbnail.

Note that public video URLs are not available by default -> ask Bynder about "video CDN" first.

<bynder-adapter video-previews></bynder-adapter>

pdf-previews

required: no, default: -

Whether to display PDF previews instead of showing a large thumbnail.

This currently triggers an original file download, because Bynder doesn't deliver PDF preview links.

<bynder-adapter pdf-previews></bynder-adapter>

zip-service

required: no, default: zippy.brix.ch

Because Bynder's API provides no mechanism for downloading more than one file at once (as of 2023-04), an external service is used to assemble a ZIP file for basket downloads. By default our own zippy service is used - ask as about zippy if you want to host your own.

<bynder-adapter zip-service="https://some.zip.url"></bynder-adapter>

celum-adapter

Connects Anura to a CELUM DAM, provided that the instance has the backend-plugin installed.

<celum-adapter url="https://my.celum.server/anura/example" locale="en"></celum-adapter>

Attributes

url

required: yes, default: -

The URL where the back-end endpoint is located, e.g. https://my.celum.server/anura/example

token

required: maybe, default: -

  • API-Token to use, only required when the back-end is protected by one.
  • Alternatively, when CELUM Authentication should be triggered, set this to login to trigger a redirect (required backend >= 2.9.31)

document-previews

required: no, default: true

Whether to display PDF previews instead of showing a large thumbnail (depending on availability/file format).

<celum-adapter document-previews="false"></celum-adapter>

video-previews

required: no, default: true

Whether to display video previews instead of showing a large thumbnail.

<celum-adapter video-previews="false"></celum-adapter>

extended

required: no, default: false

Whether to fetch more asset attributes in list requests (such as file size, see API)

<celum-adapter extended="true"></celum-adapter>

infofields

required: no, default: -

A comma-separated list of information field IDs that should be loaded in every list requests (see API)

<celum-adapter infofields="123,456,789"></celum-adapter>

alt-name

required: no, default: -

An information field ID to use instead of the asset's name (because that can't be localized). The asset's name will be used as a fallback if the information field is empty.

<celum-adapter alt-name="123"></celum-adapter>

pixxio-adapter

Connects to any pixx.io instance using their API.

<pixxio-adapter url="https://some-instance.px.media" token="xxx"></pixxio-adapter>

The ID of metadata fields is not visible in the UI, so the adapter will print a list of available metadata to the console on startup.

Note that the keywords field has a weird behavior where only a subset of all used keywords are returned (only those in Settings > Keyword Management), but assets may still have custom keywords which are not listed elsewhere, which may lead to an inconsistent navigation experience when using an <anura-select> (you can alternatively use anura-text for this reason).

Attributes

url

required: yes, default: -

The URL where the back-end endpoint is located, e.g. https://some-instance.px.media

token

required: yes, default: -

Go to "Settings > API > API-Key" and create one.

Only administrators can create API-keys, but you should never publicly use an admin-key (for obvious reasons). Workaround: Elevate your anura user to admin privileges, log in with that user, create an API-key, switch back to your account and remove his admin privileges again.

facets

Will automatically be set to false, because unfortunately they don't support faceted search at the moment.

thumb-width

type: pixel, required: no, live: on-load, default: 400

Width of the thumbnails, tweakable for very large layouts.

sharedien-adapter

Connects to any Sharedien server using their API (API-first 🥳)

<sharedien-adapter url="https://some-instance.sharedien.com" token="xxx"></sharedien-adapter>

Sharedien does not support arbitrary pagination, you must operate the paginator in auto-mode

Attributes

url

required: yes, default: -

The URL where the back-end endpoint is located, e.g. https://some-instance.sharedien.com

token

required: yes, default: -

Go to "Admin > Security > Access Token" and create a token (that lasts long enough ^^)

browser

required: no, default: -

Set the browser identifier to use, which is basically an additional search filter defined in the backend of Sharedien (see Administration > Browsers).

<sharedien-adapter browser="some-browser"></sharedien-adapter>

load-properties

required: no, default: -

Which additional metadata properties should be loaded in every list request, useful for additional information or bullets.

<sharedien-adapter load-properties="some-prop,some-other-prop"></sharedien-adapter>

fallback-locale

required: no, default: -

Fallback locale to use for metadata fields that are empty in the requested locale

<sharedien-adapter fallback-locale="de"></sharedien-adapter>