What is a Plugin?

COGS Plugins can be loaded into COGS to integrate with other systems, or can even be used to display custom web content on a COGS Media Master.

Contents of a COGS Plugin

A COGS plugin is a folder in the plugins or client_content directory of a COGS Project. The plugin directory name is the ID of the plugin (e.g. dog.clockwork.http) and contains:

• A cogs-plugin-manifest.js manifest file
• An HTML page with the content of your plugin, usually index.html
• Some Javascript, loaded by the HTML page, that uses @clockworkdog/cogs-client-lib to communicate with COGS.

You can use the @clockworkdog/cogs-client-react-lib React library to create your plugin content with React or, better yet, use the @clockworkdog/cogs-client Create React App template to get up and running quickly.

Tips

We recommend that you do not rely on loading content over the internet for maximum reliability. This means your content will load correctly and quickly even when internet connectivity at your venue is not perfect. You should include all CSS, fonts, Javascript, etc in your plugin.

How to use with frontend tools

Create React App

1. Create a project with create-react-app as usual
   e.g.

   yarn create react-app my-react-plugin --template typescript
   

2. Set homepage to ./ in package.json so the content can be hosted at in a subfolder:
   e.g.

   {
     "homepage": "./",
     ...
   }
   

3. Add a cogs-plugin-manifest.js file to the src folder as described above
4. Symlink public/cogs-plugin-manifest.js to src/cogs-plugin-manifest.json so that it is included in the build output:

   # macOS / Linux
   ln -s ../src/cogs-plugin-manifest.json public/cogs-plugin-manifest.js
   # Windows
   mklink /H public\cogs-plugin-manifest.js src\cogs-plugin-manifest.js
   

5. If you are using React, remove <React.StrictMode> from your top-level component to avoid issues with multiple websockets during development.
6. Follow the instructions to add @clockworkdog/cogs-client-react to your project.

Vite

1. Create a project with Vite as usual
   e.g.

   yarn create vite my-vite-plugin --template vanilla-ts
   // OR
   yarn create vite my-vite-plugin --template react-ts
   

2. Add a polyfill for global by adding the following to index.html.

   <script>
     if (global === undefined) {
       var global = window;
     }
     if (module === undefined) {
       var module = {};
     }
   </script>
   

3. Set base to ./ in vite.config.ts so the content can be hosted at in a subfolder:
   e.g.

   import { defineConfig } from "vite";
   
   export default defineConfig({
     base: "./",
     ...
   });
   

4. If using Typescript, add the following options to tsconfig.js to support importing cogs-plugin-manifest.js:

   {
     "compilerOptions": {
       "checkJs": true
     }
   }
   

5. Add a cogs-plugin-manifest.js file to the src folder as described above

6. Symlink public/cogs-plugin-manifest.js to src/cogs-plugin-manifest.json so that it is included in the build output:

   # macOS / Linux
   ln -s ../src/cogs-plugin-manifest.js public/cogs-plugin-manifest.js
   # Windows
   mklink /H public\cogs-plugin-manifest.js src\cogs-plugin-manifest.js
   

7. If you are using React, remove <React.StrictMode> from your top-level component to avoid issues with multiple websockets during development.

8. Follow the instructions to add @clockworkdog/cogs-client or the instructions to add @clockworkdog/cogs-client-react to your project.

In your source code be sure to import your manifest file with a wildcard import as follows:

import * as manifest from './cogs-plugin-manifest.js';