How to...

Glue42 Enable Your App

JavaScript

Using the JavaScript Library

Glue42 Desktop provides several options for Glue42 enabling your applications. You can either autoinject (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 Desktop - 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>

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/core

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

{
  "dependencies": {
    "@glue42/core": "^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
Glue()
    .then((glue) => {
        window.glue = glue;
        // this is a good place to render your application, e.g.:
        ReactDOM.render(<App />, document.getElementById("root"));
    })
    .catch(console.error);

Initialization in a browser:

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

<script type="text/javascript">
var config = {
    application: "MyWebApplication",
    gateway: {
        protocolVersion: 3,
        ws: "<GATEWAY_URL>"
    },
    auth: {
        username: "<YOUR_USERNAME>",
        password: "<YOUR_PASSWORD>"
    }
}
Glue(config)
    .then((glue) => {
        window.glue = glue;
    })
    .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 Desktop 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 Configuration

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 Desktop, 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 Desktop 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:

Glue({
    "channels": true    // enabling the Channels API
}).then(glue => {
    window.glue = glue;

    console.log(`Glue42 JS version ${glue.version} has been successfully initialized!`)

    glue.channels ? console.log("Channels are enabled.") : console.log("Channels are disabled.")
}).catch(err => console.log(err));

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

gluePromise.then(glue => {
    if (window.glue) {  // `glue` is added to the `window` object

        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 enabling
        // the Channels API in the `autoInit` property under `autoInjectAPI` (e.g., { "channels": true }),
        // then this will return `false`
        glue.channels ? console.log("Channels are enabled.") : console.log("Channels are disabled.")
    }  
}).catch(err => console.log(err));

Application Configuration

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 Desktop App Manager dropdown menu, you need to create an application configuration .json file. You should place this file in the %LocalAppData%\Tick42\UserData\<REG-ENV>\apps folder. <REG-ENV> in the link should be replaced with the region and environment folder name used for the deployment of your Glue42 Desktop - 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 Desktop features.

Reference

Reference