veracity-custom-ui v0.0.2

Veracity Custom UI Plugin Scaffold

The purpose of this project is to provide a starting template for custom UI plugin authors. Please download the folder where this project resides instead of cloning the repository. Then run npm install to install the packages required for building.

How custom UI plugins are executed in the browser

The custom UI plugin system enables the safe execution of untrusted JavaScript code in the browser. The system bundles the JavaScript interpreter quickjs as a WebAssembly, and executes JavaScript code inside a sandbox which offers only a subset of functionality than would normally be available in a browser environment. Severe limitations are imposed on DOM manipulation (nothing can be accessed outside of the scope of the plugin's own DOM). It is up to the host environment to define parameters such as max execution time, which HTTP requests are allowed, etc. Please also consult the documentation for your host environment to get an overview of what is available to you.

File and folder structure

Inside the src folder is a file called plugin.tsx. This is the entry point of your plugin. This project uses Webpack to compile the plugin source code into a single file. The output directory is build/\<ENVIRONMENT NAME>. Several Webpack coniguration files exists for different environments, i.e. webpack.dev.ts, webpack.test.ts, webpack.stag.ts, webpack.prod.ts. If your plugin should look and behave identical across environments, you may delete webpack.test.ts and webpack.stag.ts and remove references to these files in the scripts section in package.json.

Compiling the plugin code

Although you are free to use as many files as you want in your source dode, the code must be compiled into a single file. Thus, you must avoid using asynchronous import statements or anything else which causes code splitting to occur.

To start developing, execute:

npm run start

This will start Webpack and watch for file changes (watch mode).

Previewing the compiled plugin code

As you are writing your code, you may want to preview your plugin to see how it works without having to deploy it. You can do this by installing a Visual Studio Code Extension called Veracity Custom Plugin Preview. Hit Ctrl+Shift+X and search for 'veracity':

After installing the extension, you can right-click on a compiled plugin file, e.g. build/dev/template.js, and select Veracity Custom Plugin Preview: Show Preview:

, after which a preview will appear. Note that the synchronization between the preview and the .js file might not function optimally, and you may need to click the refresh button.

JSX

Inside your template, you can use JSX to define your user interface. Note that JSX does not imply React. Instead of React, the custom plugin system uses a custom JSX rendering and state system. Consider the following statement:

const mySimpleUserInterface = <p>Hello, World!</p>; // This variable now contains an object of type CustomUINode

setUI(mySimpleUserInterface); // Sets or replaces the plugin's current user interface

When using intrinsic elements such as <p>, <div>, etc., an object of type CustomUINode is generated. This type of object wraps an HTMLElement internally (i.e. what e.g. document.createElement("p") would return). Thus, a fundamental difference between React and the custom plugin's JSX system is that the latter generates actual DOM nodes; whereas React would generate so-called virtual DOM elements and use those objects to perform diffing against the actual DOM. The custom plugin's JSX system does not perform diffing.

For security reasons, the CustomUINode provides only a subset of the functionality that the the Node/HTMLElement provides.

Elements such as <img>, <svg>, <script>, <style> and <link> (there are more) are prohibited. Generally speaking, anything that would allow the execution of arbitrary JavaScript code outside of the sandbox, has been disabled. E.g. <img> has been disabled because it is possible to reference an SVG; inside of which CSS can be embedded; inside of which JavaScript can be embedded.

Styles can be applied on a per-property basis, e.g. <div style={{ backgroundColor: "pink" }}>Hello, World!</div>, however properties related to images, such as e.g. backgroundImage, are not available, for the same reasons as stated above.