Links

Server Script

The script described here provides the back-end of our plugin
The server script, script.js defines what libraries are imported and is what will get us to our end goal

Before You Start - Dev Mode

Before you start, make sure you have an exchange running in dev mode on your machine. It is important to have the exchange running in dev mode instead of a standard production CLI setup.
Dev mode exchange has live code updates and any changes in the code will get immediately applied which will make your development experience much better as a developer.

Create the Script

Looking inside the plugins/src/plugins/<YOUR_PLUGIN> you will see that the initialization created a server folder for us. This is the folder where the config.json was made.
  1. 1.
    Create a new file in this server folder called script.js
  2. 2.
    Code script.js to whatever goal you have in mind for the plugin (I recommended here looking below at the hello-exchange walkthrough to get an idea of how a script can look)
script.js is the server-side code that runs during runtime into the server's plugin container. The server script has access to many libraries available in the HollaEx Kit.
The most important library of all is the HollaEx Tools Library which has all the main features you need.
If at any point, you become unsure of the structure of either your plugin's folders or the code within the files themselves, take a look at the hello-exchange example on GitHub to see how plugin structure should be organized.

Run the Script

Ensure you have executed npm install before running the command below.
You may also need to add sudo at the beginning of the command above depending on your OS.
In addition, make sure CORS has been disabled on your browser (this can be tricky in Firefox, so Chrome may be easier to work with).command
Finally, for the run comand to work, you will need python 2 on your machine, this can be installed for Linux with sudo apt install python
To run the script on your dev mode exchange, you need to go to /plugins and run:
npm start --plugin=<PLUGIN_NAME>
Remember this will need to be done in a new terminal as dev mode will block any input on the terminal it was started on
To see if this has worked try accessing localhost:8080/config.json, and you will see the config file of the plugin
In the next section, we get into Web View and how to develop the front-end part of the plugin.

Plugin Walkthrough - 'hello-exchange' script.js

So to get started with the hello-exchange server script, first we are going to need to make the actual script that will be run:
  1. 1.
    Create a new file called script.js, in the same directory as the config.json (plugins/src/plugins/hello-exchange/server/script.js)
  2. 2.
    Fill this script.js with the code found in the box below.
hello-exchange script.js code
Easy as that, our script is done! Check the screenshot below to compare and make sure you have the file in the correct location.
Here we can see the newly added script.js in the correct folder, and filled in with the code provided
Next, we need to actually run this script.

Running 'hello-exchange'

For the plugin to run you will need to be using npm version 14, this can easily be done through the use of nvm, which allows easy switching between npm versions. Install this and then use the command nvm use 14 to switch. This will have to be done on any new terminals.
Now we have the script for hello-exchange we need to run it. This is done in the following manner.
  1. 1.
    First, ensure that you have gone through the dev mode steps. From a terminal inside hollaex-kit/server run docker-compose up and ensure that you have the output that looks like the picture below
    Successful docker-compose up command
  2. 2.
    From a new terminal, navigate to the hollaex-kit/plugins/ folder (not hollaex-kit/plugins/src/plugins)
  3. 3.
    Once in the correct folder run the following: npm start --plugin=hello-exchange, the screenshot below is what we want to see (check the note on the npm version if this displays 'exited with code 1')
    hello-exchange succesfully run! 🎉
  4. 4.
    Now, we need to do is disable CORS on our browser (best done on Chrome)
    1. 1.
      This is done by launching Chrome through the terminal with google-chrome --disable-web-security which will open a Chrome Window with CORS disabled
  5. 5.
    To check that all the steps have worked, access localhost:8080/config.json on that CORS-disabled browser, that we opened in step one, and we should see an output like the one below
    If you get to here all is well
This part is under construction 👷‍♂️
Congratulations, you've created your first plugin!
Below we go into some detail on what we have actually done.
The next page contains all supported dependencies in the plugin. You don't need to install these dependencies in your plugin prescript and so can save time and resources.
Or you can skip past the dependencies to continue adding to hello-exchange and learn how to create the front-end views.

What Did We Just Do?

The script.js file we just added is a little more complex than config.js, so again let's break it down line by line and understand what each section is doing for us.
const { publicMeta, meta } = this.configValues;
Remember the objects we made in config.json? This is
The parameters added to public_meta and meta (in config.json) are stored as publicMeta and meta in this.configValues.
We are getting our public_message parameter from publicMeta and private_message parameter from our meta.
const { app, loggerPlugin, toolsLib } = this.pluginLibraries;
const helloWorld = require("hello-world-npm");
const moment = require("moment");
We are first importing all the libraries required for this plugin.
hello-world-npm and moment are plugin-specific and default libraries, respectively. Both can be imported using require.
app, toolsLib, and loggerPlugin are preconfigured libraries that can be accessed in this.pluginLibraries.
const init = async () => {
loggerPlugin.info(
'HELLO-EXCHANGE PLUGIN initializing...'
);
if (!meta.private_message.value) {
throw new Error('Configuration value private required');
}
};
init()
.then(() => { ... }
.catch((err) => {
loggerPlugin.error(
'HELLO-EXCHANGE PLUGIN error during initialization',
err.message
);
});
The init function is first run when the plugin is enabled. For our plugin, we are checking if the value of private_message is configured (has something inside it, which ours does- "hello exchange...").
If not, the core plugin script won't run until the value is configured.
app.get('/plugins/hello-exchange/info', (req, res) => {
loggerPlugin.verbose(
req.uuid,
'GET /plugins/hello-exchange/info'
);
return res.json({
public_message: publicMeta.public_message.value,
private_message: meta.private_message.value,
library_message: helloWorld(),
moment_timestamp: moment().toISOString(),
exchange_info: toolsLib.getKitConfig().info
});
});
We are creating an endpoint GET /plugins/hello-exchange/info that returns our configuration values, the output from hello-world-npm, the current timestamp with moment, and the exchange info with toolsLib. We are also logging the request uuid with loggerPlugin.
All endpoints for plugins should be formatted as /plugins/<PLUGIN_NAME>/...
You should now be able to access the plugin endpoint on http://localhost:10012/plugins/hello-exchange/info
In dev mode port 10012 points to the plugin container.
Once we have our script for our plugin, we have to wrap it all into a string.
The following steps are not required since dev mode automatically watches and will stringify the script in your plugin script into the JSON file automatically.
Stringified Plugin Code
We also recommend minifying the script before you install your plugin. Your script will be minified after installation automatically but doing so before will ensure that the minifying process will succeed. We recommend using the library uglify-es.
Minified Code String
Once minified, add the script to the script field in your plugin JSON file.
{
...
script: "\"use strict\";const{publicMeta:publicMeta,meta:meta}=this.configValues,{app:app,loggerPlugin:loggerPlugin,toolsLib:toolsLib}=this.pluginLibraries,helloWorld=require(\"hello-world-npm\"),moment=require(\"moment\"),init=async()=>{if(loggerPlugin.info(\"HELLO-EXCHANGE PLUGIN initializing...\"),!meta.private.value)throw new Error(\"Configuration value private required\")};init().then(()=>{app.get(\"/plugins/hello-exchange/info\",(e,i)=>(loggerPlugin.verbose(e.uuid,\"GET /plugins/hello-exchange/info\"),i.json({public_message:publicMeta.public.value,private_message:meta.private.value,library_message:helloWorld(),moment_timestamp:moment().toISOString(),exchange_info:toolsLib.getKitConfig().info})))}).catch(e=>{loggerPlugin.error(\"HELLO-EXCHANGE PLUGIN error during initialization\",e.message)});",
...
}