Assets Client SDK

The Assets Client SDK can be used to build (externally hosted) integrations with Assets and contains a plugin context service for UI plugins and a client for the Assets Server API. The library is exported as a UMD bundle, meaning that it can both be imported in projects with code bundlers and legacy applications that simply include dependencies manually. When opting for the latter, the library is exposed as AssetsClientSdk on the window object. Full typings are available which should show up automatically in your IDE. Please note that support for external plugins was introduced in Assets Server 6.59 and as such, the plugin context service will only work on Assets Server 6.59 and up. References to legacy, 'previously' and so on in this README indicate Assets Server versions below 6.59.

Installation

npm install --save @woodwing/assets-client-sdk

Now you can either start importing the classes from the library in your Typescript/ES6 project:

import { AssetsApiClient } from '@woodwing/assets-client-sdk';

Or if you include the assets-client-sdk.min.js file manually in an older codebase:

window.AssetsClientSdk.AssetsApiClient;

Loading from CDN

It's also possible to load the SDK directly from a CDN using a script tag. The example below always loads the latest version. Downloading the dependency with NPM is the most reliable option. Alternatively the CDN option can be used, but this service is hosted by a 3rd party where we don't have control over the SLA.

<script src="https://cdn.jsdelivr.net/npm/@woodwing/assets-client-sdk"></script>

Assets Plugin Context Service

The AssetsPluginContext service can be used to allow for communication between your externally hosted Assets plugin and the Assets client. Previously, an elvisContext object was available through the parent frame. However, since externally hosted plugins will be on another domain, it's impossible to access the parent frame because of cross-origin restrictions.

Usage

To initialize communication, use the static AssetsPluginContext.get function. If needed, supply an array of whitelisted urls to Assets clients that should be allowed to embed your plugin. This makes sure communication to and from the AssetsPluginContext can only occur with the whitelisted urls.

// with optional array of whitelisted urls
const contextService = await AssetsPluginContext.get(['https://my-assets.url']);

You can access the current context data at any point.

const context = contextService.context;

You can subscribe to context data changes with the subscribe method.

contextService.subscribe(data => console.log(data));

Please note that reusing the existing user session for calls to the Assets API is no longer possible when hosting the plugin on another domain. Instead, using the AssetsPluginContext.fetch method, you can proxy calls to the Assets server through the client window. This fetch method is also used under the hood in the Assets API Client described below which provides convenience functions for some of the most used server calls.

const searchResults = await contextService.fetch('/services/search', {
    method: 'POST',
    body: {
        // your query here
    }
});

The following methods are available to interact with the client interface

contextService.pinCollections(['1', '2', '3']);
contextService.cancelCheckout(['1', '2', '3']);
contextService.checkin(['1', '2', '3']);
contextService.checkout(['1', '2', '3']);
contextService.close();
const hasFilteredSelection = contextService.hasFilteredSelection();
const hasSelection = contextService.hasSelection();
const isSingleItem = contextService.isSingleItem();
await contextService.login();
contextService.openAssets(['1', '2', '3']);
contextService.openBrowse('/my/path');
contextService.openCollections(['1', '2', '3']);
contextService.openSearch('id:1 OR id:2');

Assets API Client

The AssetsApiClient class can be used for communication between your plugin or standalone app and the Assets server. The Assets API Client can either be used standalone or in combination with the AssetsPluginContext. The latter option is intended for UI plugins embedded in the Assets client. When used standalone, a user session is needed in the current window. Authentication functionality is provided and if the session should expire, any failed calls will be retried. When using the API client in combination with the AssetsPluginContext, the requests to the Assets server are proxied through the Assets client window. This means the user session from the Assets client window is reused.

Usage

To initialize the AssetsApiClient class, two static methods are available to preconfigure the instance according to your needs.

// For standalone usage:
const apiClient = AssetsApiClient.standalone('http://your.server.url', 'username', 'password', 'your-client-type');

// Alternatively, for plugin usage initialize an instance of the AssetsPluginContext first and:
const apiClient = AssetsApiClient.fromPluginContext(pluginContext);

The standalone function will setup the API client to use the configured username and password when authenticating. If the credentials should be changed dynamically, use the useAutoLogin function to update the username and password.

apiClient.useAutoLogin('updated-username', 'updated-password', 'your-client-type');

When initializing with the fromPluginContext function, the login prompt in the Assets client will be shown when the session has expired.

If you need a custom handler for authentication, use the useLoginHandler function.

apiClient.useLoginHandler(yourAuthenticationProvider.login);

For details on the available server calls please refer to the accompanying automatically generated documentation.

Additionally, two helper functions are exported to help with generating queries for Assets or Folders.

import { queryForSelection, queryForFolderSelection } from "@woodwing/assets-client-sdk";

// generates a query string which can be used to retrieve the given assets with a search call
const query = queryForSelection(myAssets);

// generates a query string which can be used to specify the given folders
const query = queryForFolderSelection(myFolders);

Documentation

If you are writing your plugin in Typescript, your IDE should automatically recognize the types that the library exports.

If this is not the case however (or if you just want a human-readable overview), you can open the documentation in your favorite browser.

Backwards compatibility

Legacy elvisContext

For a backwards compatible version of the plugin context object which imitates the old elvisContext behaviour, you can instantiate the LegacyElvisContextWrapper class using the AssetsClientSdk.legacyElvisContext() function. Please note that this is only meant as a temporary fix for existing plugins. No new features will be added to this class.

Also note that the function returns a promise, so you can't use the elvisContext unless you await for it.

(async () => {

    const elvisContext = await AssetsClientSdk.legacyElvisContext();

})();

Legacy ElvisAPI

For a backwards compatible version of the AssetsApiClient which imitates the old ElvisAPI behaviour, you can instantiate the LegacyElvisApiWrapper class using the AssetsClientSdk.legacyElvisAPI() function. Please note that this is only meant as a temporary fix for existing plugins. No new features will be added to this class.

Also note that the function returns a promise, so you can't use the elvisContext unless you await for it.

(async () => {

    const elvisApi = await AssetsClientSdk.legacyElvisAPI();

})();

For the backwards compatible version of the ElvisPlugin, you can use the LegacyElvisPlugin object. This object only implements the two query generating functions. The other two functions are no longer available and will throw an error when used.

const query = LegacyElvisPlugin.queryForSelection(assets);
const query = LegacyElvisPlugin.queryForFolderSelection(folders);

// throws an error
LegacyElvisPlugin.resolveElvisContext();
LegacyElvisPlugin.resolveQueryString();

To view a sample of how to convert an existing plugin, see this commit in the elvis_metadata_stamper.