How to...

Glue42 Enable Your App

JavaScript

Using the JavaScript Library

Glue42 Enterprise provides several options for Glue42 enabling your applications. You can either auto inject (and optionally auto initialize) the Glue42 JavaScript library in your applications, or reference it (either as an npm module, or as a standalone JavaScript file) and then initialize it. Both approaches have their respective advantages and disadvantages. Usually, our clients choose a global approach for all their Glue42 enabled applications (in some cases, there may be hundreds of Glue42 enabled applications in use) based on what best suits their needs and requirements.

Auto injecting the library is the way to go if you need all your Glue42 enabled applications to use the same version of the library and have the option to be easily updated to the latest version of Glue42 JavaScript. Updating the library in all applications can be accomplished simply by redeploying Glue42 Enterprise - all Glue42 enabled applications will be automatically injected with the new version of the library, saving you the effort to update them one by one. Another option is to use a REST service providing the latest versions of Glue42 JavaScript. Apps with auto injected Glue42, however, will not be Glue42 enabled in the browser, which is something to consider if you need to use them in a browser. Auto injection may not work well for you in some other cases as well, depending on your production and deployment model.

Using the Glue42 JavaScript library as a standalone file or as an npm package has its advantages too - your applications can use a different version of the library, if that is necessary, for example. Also, your applications can be Glue42 enabled in a browser. This, of course, means that updating the library can be a tedious and slow process, especially if you have many Glue42 enabled applications, the majority of which need to use a different version of the library.

Below you can explore both options for using the Glue42 JavaScript library.

Referencing the Library

From a JavaScript File

Glue42 JavaScript is a library available as a single JavaScript file, which you can include into your web applications using a <script> tag. If you are using a Glue42 installer, you can find the .js files in %LOCALAPPDATA%\Tick42\GlueSDK\GlueJS\js\web.

<script type="text/javascript" src="tick42-glue-4.0.0.js"></script>

Because the API evolves, we have chosen the following semantic version model:

BreakingChangesVersion.FeatureVersion.FixVersion

When deploying your application in production, we recommend that you always reference a specific minified version:

<script type="text/javascript" src="tick42-glue-4.0.0-min.js"></script>

Using the Glue42 CDN

You can alternatively point to Glue42 JavaScript npm packages and files via the Glue42 CDN by using URLs in the format:

https://cdn.glue42.com/:package@:version/:file
  • Using the latest version: https://cdn.glue42.com/desktop@latest;
  • Using a fixed version: https://cdn.glue42.com/desktop@4.6.3
  • Using a specific file different from the one defined in the package.json: https://cdn.glue42.com/browse/desktop@4.6.3/dist/web/@glue42/desktop.min.js
  • To see all available versions and files, append / to the URL: https://cdn.glue42.com/desktop/

From an NPM Module

The Glue42 JavaScript library is also available as npm packages, which you can include as dependencies in your project and import in your code. The currently available packages are @glue42/core and @glue42/desktop. The Core package is a subset of the Desktop package and offers basic functionalities for sharing data between applications (Interop, Shared Contexts, Pub/Sub, Metrics), while the Desktop package offers additional options for sharing data between apps (Activities, Channels), as well as advanced window management functionalities (App Management, Layouts, Window Management, Hotkeys).

To include any of our packages as a dependency in your project, navigate to the root directory of your project and run:

npm install @glue42/desktop

Your package.json file now should have an entry similar to this:

{
    "dependencies": {
        "@glue42/desktop": "^4.4.4"
    }
}

Initializing the Library

When included, the JavaScript library will register a global factory function called Glue(). It should be invoked with an optional configuration object to initialize the library. The factory function returns a Promise which will resolve with the initialized API reference.

Initialization in a Glue42 window:

import Glue from "@glue42/desktop"

// You don't need to specify any configuration.
const initializeGlue42 = async () => {
    window.glue = await Glue();
};

initializeGlue42().catch(console.error);

Initialization in a browser:

<script type="text/javascript" src="tick42-glue-4.0.0-min.js"></script>

<script type="text/javascript">
    const initializeGlue42 = async () => {
        const config = {
            application: "MyWebApplication",
            gateway: {
                protocolVersion: 3,
                ws: "<GATEWAY_URL>"
            },
            auth: {
                username: "<YOUR_USERNAME>",
                password: "<YOUR_PASSWORD>"
            }
        };
        window.glue = await Glue(config);
    };

    initializeGlue42().catch(console.error);
</script>

You can customize the Glue42 configuration object by specifying which Glue42 libraries your application needs, and what level of features your app requires from these libraries. See the Glue42 Enterprise Reference documentation for details.

Auto Injecting the Library

Auto injection can be configured on a system level and can be overridden on an application level (with some limitations). You can also optionally specify whether you want to auto initialize the library after injection.

System Level Auto Injection

To enable auto injection on a system level, edit the autoInjectAPI property under the windows top-level key in the system.json file of Glue42 Enterprise, located in %LocalAppData%\Tick42\GlueDesktop\config:

"windows": {
    "autoInjectAPI":{
        "enabled": true,
        "version": "4.6.2",
        "autoInit": false
    }
}
  • enabled - Required. Whether to enable auto injecting the library;
  • version - Required. Specify a version of the library to inject. It is recommended to use a specific version and avoid wildcard versions (e.g., 4.6.* or 4.*.*)
  • autoInit - Optional. Whether to initialize the library or not. Can accept either a boolean value or a Config object with which to initialize the library.

You can see what versions of the Glue42 JavaScript library are available for auto injection in the %LocalAppData%\Tick42\GlueDesktop\assets\glue42 folder. If you specify a version which is not available, Glue42 Enterprise will continue working normally without injecting a library in the applications running in it.

If the library is injected but not auto initialized, you can use the injected Glue() factory function in the window object to initialize it. You can pass a custom Config object to it, if needed:

const initializeGlue42 = async () => {
    // Enabling the Channels API.
    const config = { channels: true };

    window.glue = await Glue(config);

    console.log(`Glue42 JS version ${glue.version} has been successfully initialized!`);
    console.log(`Channels are ${glue.channels ? "enabled" : "disabled"}.`);
};

initializeGlue42().catch(console.error);

If the library is injected and auto initialized, you should use the injected gluePromise in the window object to wait for the Glue42 API:

await gluePromise.catch(console.error);

// The returned `glue` object is assigned to the global `window` object.
if (window.glue) {  
    console.log(`Glue42 JS version ${glue.version} has been successfully initialized!`);

    // Channels are disabled by default. If you have not specified a custom initialization object that enables
    // the Channels API in the `autoInit` property under `autoInjectAPI` (e.g., "autoInit": { "channels": true }),
    // then the check below will return `false`.
    console.log(`Channels are ${glue.channels ? "enabled" : "disabled"}.`);
};

Auto Injection Filtering

You can whitelist and blacklist applications on a system level to control which applications should be auto injected with the library and which should use their own version of the library instead.

  • whitelisted applications: all whitelisted applications will be auto injected with the library, all other applications will not be auto injected;
"windows": {
    "autoInjectAPI":{
        "enabled": true,
        "version": "4.6.2",
        "autoInit": false,
        "whitelist": ["clientlist"]
    }
}
  • blacklisted applications: no blacklisted applications will be auto injected with the library, all other applications will be auto injected;
"windows": {
    "autoInjectAPI":{
        "enabled": true,
        "version": "4.6.2",
        "autoInit": false,
        "blacklist": ["clientlist"]
    }
}

If an application is both in the whitelist and the blacklist, it will be auto injected with the library.

Application Level Auto Injection

If auto injection of the library is disabled on a system level, it cannot be enabled on an application level. If auto injection is enabled on a system level, then each application can opt out of it. Applications can specify whether the auto injected library to be auto initialized or not, but cannot specify which version of the library to be auto injected - this is possible only on a system level. If an application needs to use a different version of the library than the auto injected one, you should disable auto injection in the application configuration and reference a version of the desktop.js library file in your app instead.

To configure auto injection on an application level, edit (or add) the autoInjectAPI property under the details top-level key of the application configuration file.

See Application Configuration below or the Configuration section for more details on how to create an application definition and where the application configuration files should be stored.

Below is an example configuration for auto injection on an application level:

"details": {
    ...
    "autoInjectAPI":{
        "enabled": true,
        "autoInit": false
    }   
}
  • enabled - Required. Whether to enable or disable auto injection.
  • autoInit - Optional. Whether to initialize the library or not. Can accept either a boolean value or a Config object with which to initialize the library.

Auto Initialization

Auto initialization of the injected library can be specified globally in the system.json file, or can be overridden on an application level in the application configuration file. To enable or disable auto initialization of the library, set the autoInit property under autoInjectAPI to true or false respectively.

If you want to auto initialize your app with a custom initialization Config object, simply specify the initialization options object instead of assigning a boolean value to autoInit.

Below is an example configuration that will auto initialize an application with Channels enabled:

"autoInjectAPI":{
    "enabled": true,
    "autoInit": {
        "channels": true
    }
}   

Application Configuration

To show your app in the Glue42 Enterprise App Manager dropdown menu, you need to create an application configuration .json file. You should place this file in the %LocalAppData%\Tick42\UserData\<ENV-REG>\apps folder. <ENV-REG> in the link should be replaced with the region and environment folder name used for the deployment of your Glue42 Enterprise - e.g., T42-DEMO.

Below you can see how to create a quick and simple application definition:

{
    "name": "my-app",   // required
    "title": "My App",
    "type": "window",   // required
    "details": {        // required
        "url": "http://localhost:3333/my-app.html", //required
        "mode": "tab",
        "width": 500,
        "height": 400
    }
}

See the Application Configuration section for more information.

You can also check out our JavaScript examples at GitHub, demonstrating the various Glue42 Enterprise features.

Reference

Reference