ZLUX Plugin Definition & Structure

The ZLUX App Server zlux-server-framework is referred to as such because it enables extensiblity with Apps. But in truth, Apps are not the only form of extensibility in the server - Apps are a sub-category of the unit of extensibility in the server: a Plugin.

This page details Plugins, with a focus on Apps which are the most common type.

Locating Plugins

As mentioned in the server configuration, the server will read from a directory, pluginsDir, at startup. Within this directory are a collection of small JSON files. Each JSON file has only two attributes, which serve to locate a Plugin on disk.

• location: This is a directory path relative to the server's executable (such as zlux-app-server/bin/nodeServer.sh) at which a pluginDefinition.json is expected to be found
• identifier: This is the unique string (Commonly styled as a Java resource) of a Plugin, which must match what is in the pluginDefinition.json

The server will load valid plugins that are found by the information provided in these locating JSONs.

Plugin Definition File

pluginDefinition.json is the file which describes a plugin. It has varied attributes dependent upon its pluginType. Consider the pluginDefinition.json from sample-app:

{
  "identifier": "org.zowe.zlux.sample.angular",
  "apiVersion": "1.0.0",
  "pluginVersion": "1.0.0",
  "pluginType": "application",
  "webContent": {
    "framework": "angular2",
    "launchDefinition": {
      "pluginShortNameKey": "sampleangular",
      "pluginShortNameDefault": "Angular Sample",
      "imageSrc": "assets/icon.png"
    },
    "descriptionKey": "sampleangulardescription",
    "descriptionDefault": "Sample App Showcasing Angular Adapter",
    "isSingleWindowApp": true,
    "defaultWindowStyle": {
      "width": 850,
      "height": 450
    }
  },
  "dataServices": [
    {
      "type": "router",
      "name": "hello",
      "filename": "helloWorld.js",
      "routerFactory": "helloWorldRouter",
      "dependenciesIncluded": true,
      "initializerLookupMethod": "external"
    }
  ],
  "configurationData": {
    "resources": {
      "requests": {
        "aggregationPolicy": "override",
        "subResources": {
          "app": {
            "aggregationPolicy": "override"
          }
        }
      }
    }
  }
}

The attributes can be broken down into categories:

General Attributes

• identifier: Every Plugin must have a unique string ID which associates it with a URL space on the server.
• apiVersion: The version number for the pluginDefinition scheme and App/Dataservice requirements.
• pluginVersion: The version number of the individual plugin.
• pluginType: A string that states what type of plugin this is. Determines what other attributes are valid in the definition.
  • application: Defines the Plugin as an App. Apps are composed of either a collection of web content for presenting in the ZLUX web component (such as the virtual desktop), or a collectionof dataservices (REST & websocket), or both.
  • library: Defines the Plugin as a library which serves static content at a known URL space
  • nodeAuthentication: Authentication & Authorization handlers for the App server

Application Attributes

When a Plugin is of "pluginType": "application", the following other attributes are valid:

• webContent: An object which defines a few attributes about the content shown in a web UI
• dataServices: An array of objects describing REST or websocket dataservices
• configurationData: An object which describes the resource structure that this App uses for storing user, group and server data.

Application Web Content

An App which has the webContent attribute defined will provide content to be shown in a ZLUX web UI. The following attributes determine some of this behavior:

• framework: States what type of web framework is used, which determines what other attributes are valid in webContent.
  • angular2: Defines this App as having an Angular (2+) web framework component.
  • react: Defines this App as having a React web framework component.
  • iframe: Defines this App as being external to the native ZLUX web App environment, but instead embedded in an iframe wrapper.
• launchDefinition: An object which details some attributes for presenting the App in a web UI
  • pluginShortNameDefault: A string giving a name to the App when i18n is not present. When it is, i18n will be applied by using the pluginShortNameKey
  • descriptionDefault: A longer string for giving a description of the App within a UI. This is seen when i18n is not present. When it is, i18n will be applied by using the descriptionKey.
  • imageSrc: Is the relative path (from /web) to a small image file representing the App's icon.
• defaultWindowStyle: An object which details the placement of a default window for this App in a web UI
  • width: States the default width of this App's window, in pixels
  • height: States the default height of this App's window, in pixels

IFrame App Web Content

In addition to the general web content attributes, when stating that the framework of an App is "iframe", you must state what page is being embedded in the iframe. This is done by including the attribute startingPage within webContent. startingPage is relative to the App's /web directory.

It is recommended that startingPage be a relative path rather than an absolute one as the pluginDefinition.json file is intended to be read-only, and therefore would not work well when the hostname of a page has changed.

Within an IFrame, the App still has access to the globals that are used by ZLUX for App-to-app communication: Simply access window.parent.ZoweZLUX.

Plugin Definition Schema Revision Notes

The initial Plugin Definition Schema is version 1.0.0, since then, the following updates have been made

• 1.0.1
  • Added webContent.hasComponents which instructs the App code as to if it needs to load Zowe App Component logic from a components.js file, rather than the main.js webpack file, for non-iframe Apps.
  • Added os as an object and os.platform, and os.type as arrays of strings to be able to know if a Plugin should be loaded dependent upon the host OS.

Application Dataservices

See Dataservices

Application Configuration Data

The App server has a component for managing an App's configuration & user data, organized by scope such as user, group, and server instance. For more information, see Configuration Dataservice Documentation.