Skip to main content
English (United States) Nederlands

Creating an external plug-in for Assets Server

Updated

External plug-ins are used for extending the functionality of Assets Server. As the name suggests, external plug-ins are hosted on an external system — such as Netlify, Amazon S3 with Cloudfront, or Surge — and linked to one or more Assets Server installations.

External plug-ins can act as an action plug-in or a panel plug-in.

In this article, the creation of an external plug-in is described by creating a sample plug-in for Assets with which users can assign a status to all files in a selected folder.

Tools

Creating a new external plug-in is done by making use of the Assets Client SDK which is hosted on NPM. Refer to the README of the SDK for installation and usage of the library.

For this project, we will also make use of TypeScript and Webpack tools.

Steps

The project consists ofthe following steps:

  1. Installing Node.js
  2. Creating a new project
  3. Installing TypeScript
  4. Installing Webpack
  5. Installing the Assets Client SDK
  6. Creating a config.js file
  7. Creating an index.ts file
  8. Creating a style.css file
  9. Creating an index.html file
  10. Building the project
  11. Setting up an external Action plug-in in Assets Server
  12. Testing the plug-in

Info: Use the filter to only show information for one step:

1. Installing Node.js

In this project, TypeScript is used. Making use of TypeScript requires Node.js to be installed using npm.

Step 1. Check if Node.js and npm are installed, and if so, which version, by running the following commands:

npm -v

node -v

Step 2. Do one of the following:

  • When a new installation is needed, download the Long Term Support (LTS) version from nodejs.org and install it.
  • When an installation already exists, check what the latest version is by visiting nodejs.org and download and install the latest version when needed.

2. Creating a new project

In this step. a new project for the plug-in is created, named 'assets-set-folder-status'.

Step 1. Create a directory for the project:

mkdir assets-set-folder-status

Step 2. Open the directory:

cd assets-set-folder-status

Step 3. Initialize it as an npm package project with default settings:

npm init -y

A new package.json file is created containing the data shown below. The settings can be updated later when needed.

{
  "name": "assets-set-folder-status",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

3. Installing TypeScript

With the npm project successfully initialized, TypeScript can now be installed and set up.

Step 1. Within the project directory, run the following command:

npm install typescript --save-dev

Step 2. Create a tsconfig.json file by running the following command within the project directory:

nano tsconfig.json

Step 3. Open the created file and paste the following:

{
  "compilerOptions": {
      "downlevelIteration": true,
      "module": "commonjs",
      "strictNullChecks": false,
      "noImplicitAny": false,
      "noUnusedParameters": true,
      "noUnusedLocals": true,
      "removeComments": true,
      "target": "es6",
      "lib": ["dom","es2015"],
      "esModuleInterop": true,
  },
}

Note: For more information about the parameters used, see the TypeScript documentation: Intro to the TSConfig Reference.

4. Installing Webpack

We will use Webpack to compile the JavaScript modules. This requires that the Webpack and other related modules (webpack-cli, webpack-config, webpack-dev-server, and ts-loader) need to be installed in the project.

Step 1. Install the Webpack modules by running the following command:

npm install webpack webpack-cli webpack-config webpack-dev-server ts-loader --save-dev

Step 2. Install the useful Webpack plug-in modules html-webpack-plugin, mini-css-extract-plugin, and css-loader:

npm install html-webpack-plugin mini-css-extract-plugin css-loader --save-dev

Step 3. With Webpack now installed, create the webpack.config.js file:

nano webpack.config.js

Step 4. Open the file and paste the following:

const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
    output: {
        path: path.resolve(__dirname, 'dist'),
    },
    entry: './src/index.ts',
    plugins: [
        new HtmlWebpackPlugin({
            filename: 'index.html',
            template: 'src/index.html'
        }),
        new MiniCssExtractPlugin()
    ],
    module: {
        rules: [
            {
                test: /\.tsx?$/,
                use: ['ts-loader'],
            },
            {
                test: /\.s?css$/,
                use: [MiniCssExtractPlugin.loader, 'css-loader'],
            }
        ]
    },
    devServer: {
        port: 4002,
    },
    resolve: {
        extensions: ['.ts', '.js'],
    }
};

Step 5. Edit the package.json file:

nano package.json

Step 6. Replace the scripts key element with the following:

"scripts": {
  "dev": "webpack-dev-server --mode development --config webpack.config.js",
  "build": "webpack --mode production --config webpack.config.js"
},

5. Installing the Assets Client SDK

Creating a new external plug-in is done by making use of the Assets Client SDK. It contains a plug-in context service for UI plug-ins and a client for the Assets Server API.

Install the SDK by running the following command:

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

6. Creating a config.js file

In this step, a configuration file config.js is created within the project directory. The configuration will be used later in the plug-in script.

Step 1. Create the file by running the following command:

nano config.js

Step 2. Open the file and paste the following:

module.exports = {
    CLIENT_URL_WHITELIST: ['http://localhost:50'],
    NEW_STATUS: ['Send To Cold Storage', 'Restore from Cold Storage']
};

7. Creating an index.ts file

In this step, an index.ts script developed in TypeScript is created that uses the Assets Client SDK for building the integration with Assets Server.

The script function populates the index.html page and performs a bulk update on status for all assets in a selected folder.

Step 1. Create a 'source' code (src) directory under the project directory by running the following command:

mkdir src

Step 2. Open the directory:

cd src

Step 3. Create the index.ts file:

nano index.ts

Step 4. Open the file and paste the following:

import { AssetsApiClient, AssetsPluginContext } from '@woodwing/assets-client-sdk';
import './style.css';
import * as config from '../config.js';

const folderDiv = document.getElementById('folderDiv');
const statusDiv = document.getElementById('statusDiv');
const statusList = document.getElementById('status');

let apiClient: AssetsApiClient;
let contextService: AssetsPluginContext;

const loadStatus = () => {
    const folderSelection = contextService.context.activeTab.folderSelection;
    folderDiv.innerHTML = '<b>Folder</b>: ' + folderSelection[0].name;

    const newStatus:[] = config.NEW_STATUS;
    let htmlOption:string = '';
    newStatus.forEach( function (status) {
        htmlOption += '<option value="' + status +'">' + status + '</option>';
    }); 
    statusList.innerHTML = htmlOption;
    statusList.hidden = false;
    statusDiv.innerHTML = '<b>Status</b>: ' + statusDiv.innerHTML;
};

async function onUpdate() {
    const folderSelection = contextService.context.activeTab.folderSelection;
    const status = (<HTMLSelectElement>document.getElementById('status')).value;
    const query = 'ancestorPaths:"' + folderSelection[0].assetPath + '" -status:"' + status + '"';
    const metadata = { 'status': status };
    
    await apiClient.updatebulk(query, metadata);
    contextService.close();
}

(async () => {
    contextService = await AssetsPluginContext.get(config.CLIENT_URL_WHITELIST);
    apiClient = AssetsApiClient.fromPluginContext(contextService);
    apiClient = apiClient;
    document.getElementById('update').onclick = function() {onUpdate()};
    await loadStatus();
    document.getElementById("update").hidden = false;
})();

8. Creating a style.css file

In this step, a simple style.css file is created for styling and laying out the HTML page that is shown to the user as a dialog.

Step 1. In the src directory, create the style.css file by using the following command:

nano style.css

Step 2. Open the file and paste the following:

.panel {
    padding: 10px 20px;
    width: 100%;
    flex-direction: column;
}

.intro {
    padding-bottom: 20px;
}

9. Creating an index.html file

In this step, the HTML page is created that is shown to the user as a modal dialog from which the status can be chosen that needs to be assigned to the files in the selected folder.

When the Webpack is compiled, the index.html file is created in the 'distribution' code (./dist) folder with the index.js and style.css references.

Step 1. In the scr directory, create the index.html file by running the following command:

nano index.html

Step 2. Open the file and paste the following:

<html>
    <body>
        <div id="intro" class="intro">
            This action will bulk update all the assets status to send to cold storage.
        </div>
        <div></div>
        <div id="folderDiv" class="panel">
        </div>
        <div id="statusDiv" class="panel">
            <select name="status" id="status" hidden>
            </select>
        </div>
        <div class="panel">
            <button id="update" hidden>Update</button>
        </div>
    </body>
</html>

10. Building the project

The project is now ready to be built and the external plug-in can be created in the distribution code folder that can hosted externally and called by Assets.

You can build the project either in a self-run development environment or a dedicated production environment.

Development environment

For a development environment, build the project and run it in the development environment server by running the following command:

npm run dev

After execution, the external plug-in project is build, running on port 4002.

Access the external plug-in index page using the following URL:

http://your server URL or localhost:4002/index.html

Production environment

For a production environment, build the project to create a minimized and optimized output code in the 'distribution' code (./dist) folder by running the followng command:

npm run build

After execution, copy the distribution code folder(./dist), and host it externally at any production web server as 'assets-set-folder-status'.

Test it by browsing to the production Web server URL:

https://your production server URL/assets-set-folder-status/index.html

11. Setting up an external Action plug-in in Assets Server

In this step, an external Action plug-in is set up in Assets Server. It will reference and call the plug-in that is hosted externally.

Step 1. In Assets, access the Management Console > Plugins > External Action plugins page.

Step 2. Add a new plug-in and fill out the following fields. Leave all other fields set to default. When done, click Save to save the changes.

  • Name. The name of the plug-in shown in Assets in the toolbar and the folder context menu.

Example: Set status to all files in folder

  • URL: The URL to the external plug-in.

Example: https:/your hosted server URL/assets-set-folder-status/dist/index.html

  • Title: The title of the dialog in which the user can select the status.

Example: Set status to all files in folder

  • User interface: Choose Dialog.
  • Width: 480
  • Height: 240
  • Add location: Select:
  • Toolbar
  • Folder context menu
  • Action location order: Set it to 99.

12. Testing the plug-in

With everything in place, the plug-in can now be tested.

Step 1. In Assets, create a test folder and add some test files to it.

Step 2. Right-click the folder and choose 'Set status to all files in folder' (or whatever the name was that was set up for the action).

Step 3. In the dialog, choose the status to assign.

Note: It might take some time to perform the update. When the dialog is closed, the update is complete.

Step 4. Verify for any of the files in the folder that the status has changed.

Related articles

Comments

0 comments