[MINITOC] Adapters connect the Anura front-end components to an upstream source, usually a DAM. At least one is required. | | | | | ------------------------------------------ | --------------------------------------- | --------------------------------------------------- | | [![bynder](./bynder.png)](#bynder-adapter) | [![celum](./celum.png)](#celum-adapter) | [![sharedien](./sharedien.png)](#sharedien-adapter) | ## 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. #### locale > required: no, default: the page's language (or en) ISO 639-1 code for the language you'd like to use. Defaults to `` if present or `en` otherwise. Defaults to `en` when the requested string is not present in a given language. Supported languages: `bg`, `cz`, `de`, `en`, `es`, `fr`, `hu`, `it`, `ro`, `sk` and `sl`. Contributions are welcome :-) #### theme > required: no, live: yes, default: the browser's `prefers-color-scheme` setting Default theming of fullscreen components (`light` or `dark`), defaults to the users `prefers-color-scheme` setting. Set this to `light` in order to suppress dark mode despite users requesting it. #### facets > required: no, live: on-load, default: true Set this to `false` to disable faceted search for all downstream components. #### 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. ```html ``` #### asset-order > required: only then using `order-key`, live: on-load, default: - Depending on your DAM, it may not feature an asset ordering process, you you need to define where an external asset order server lives. ### Events #### load A regular load-event, can be used to set translations, e.g. ```html ``` #### 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](https://bynder.docs.apiary.io). ```html ``` ### 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: false 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. #### 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. ## celum-adapter Connects Anura to a CELUM DAM, provided that the instance has the [backend-plugin](/anura/backend) installed. ```html ``` ### 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](/anura/backend#anura-1-token-verifier) 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). #### video-previews > required: no, default: true Whether to display video previews instead of showing a large thumbnail. #### extended > required: no, default: false Whether to fetch more asset attributes in list requests (such as file size, see [API](/anura/api#result-controls)) #### infofields > required: no, default: - A comma-separated list of information field IDs that should be loaded in list requests (see [API](/anura/api#result-controls)) #### 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. ## sharedien-adapter Connects to any Sharedien server using their [API](https://sharedien.com/headless) (API-first 🥳) ```html ``` > > > Sharedien does not support arbitrary pagination, you **must** operate the paginator in [auto-mode](../components/paginator#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). #### load-properties > required: no, default: - Which additional metadata properties should be loaded in list requests, useful for additional information or bullets.