Plug-ins definition and structure
Plug-ins definition and structure
The Zoweâ„¢ Application Server (zlux-app-server
) enables extensiblity with application Plugins. Application Plugins are a subcategory of the unit of extensibility in the server called a plugin.
The files that define a Plugin are located in the pluginsDir
directory.
#
pluginDefinition.jsonThis file describes an application Plugin to the Zowe Application Server. (A Plugin is the unit of extensibility for the Zowe Application Server. An application Plugin is a Plugin of the type "Application", the most common and visible type of Plugin.) A definition file informs the server whether the application Plugin has server-side dataservices, client-side web content, or both. The attributes of this file are defined within the pluginDefinition json-schema document
#
Application Plugin filesystem structureAn application Plugin can be loaded from a filesystem that is accessible to the Zowe Application Server, or it can be loaded dynamically at runtime. When accessed from a filesystem, there are important considerations for the developer and the user as to where to place the files for proper build, packaging, and operation.
#
Root files and directoriesThe root of an application Plugin directory contains the pluginDefinition.json file, and the following other files and directories.
#
Dev and source contentAside from demonstration or open source application Plugins, the following directories should not be visible on a deployed server because the directories are used to build content and are not read by the server.
#
nodeServerWhen an application Plugin has router-type dataservices, they are interpreted by the Zowe Application Server by attaching them as ExpressJS routers. It is recommended that you write application Plugins using Typescript, because it facilitates well-structured code. Use of Typescript results in build steps because the pre-transpilation Typescript content is not to be consumed by NodeJS. Therefore, keep server-side source code in the nodeServer
directory. At runtime, the server loads router dataservices from the lib directory.
#
webClientWhen an application Plugin has the webContent attribute in its definition, the server serves static content for a client. To optimize loading of the application Plugin to the user, use Typescript to write the application Plugin and then package it using Webpack. Use of Typescript and Webpack result in build steps because the pre-transpilation Typescript and the pre-webpack content are not to be consumed by the browser. Therefore, separate the source code from the served content by placing source code in the webClient
directory.
#
Runtime contentAt runtime, the following set of directories are used by the server and client.
#
libThe lib
directory is where router-type dataservices are loaded by use in the Zowe Application Server. If the JS files that are loaded from the lib
directory require NodeJS modules, which are not provided by the server base (the modules zlux-server-framework
requires are added to NODE_PATH
at runtime), then you must include these modules in lib/node_modules
for local directory lookup or ensure that they are found on the NODE_PATH
environment variable. nodeServer/node_modules
is not automatically accessed at runtime because it is a dev and build directory.
#
webThe web
directory is where the server serves static content for an application Plugin that includes the webContent attribute in its definition. Typically, this directory contains the output of a webpack build. Anything you place in this directory can be accessed by a client, so only include content that is intended to be consumed by clients.
#
Packaging applications as compressed filesApplication Plugin files can be served to browsers as compressed files in brotli (.br) or gzip (.gz) format. The file must be below the application's /web
directory, and the browser must support the compression method. If there are multiple compressed files in the /web
directory, the Zowe Application Server and browser perform runtime negotiation to decide which file to use.
#
Default user configurationConfiguration Dataservice default settings for users can be packaged within a Plugin.
This is done by putting content within the /config/storageDefaults
folder, and more on that subject can be found here
#
App-to-App CommunicationApp-to-App communication behaviors can be statically defined or dynamically created at runtime. Static definitions help as a form of documentation and to be able to depend upon them, so it is recommended that these be packaged with a Plugin if you wish other's to be able to use App-to-App communication on your App.
This page describes the subject in more detail.
In summary, App-to-App Actions and Recognizers can be stored within an App's /config/actions
and /config/recognizers
folders, respectively, where the filenames much match the identifiers of Apps.
#
DocumentationIn order for Zowe servers to pick up documentation to present to UIs, they must be in a uniform place.
The /doc folder of any Plugin can contain at its root any READMEs or documents that an administrator or developer may care about when working with a Plugin for the first time.
The /doc/swagger folder on the other hand, will be used to store .yaml extension Swagger 2.0 files that document the APIs of a Plugin's dataservices if they exist.
Other folders may exist, such as /doc/ui to document help behavior that may be shown in a UI, but is not implemented at this time.
#
Location of Plugin filesThe files that define a Plugin are located in the plugins
directory.
#
pluginsDir directoryAt startup, the server reads from the plugins
directory. The server loads the valid Plugins that are found by the information that is provided in the JSON files.
Within the pluginsDir
directory are a collection of JSON files. Each file has two attributes, which serve to locate a Plugin on disk:
location: This is a directory path that is relative to the server's executable (such as zlux-app-server/bin/start.sh
) at which a pluginDefinition.json
file is expected to be found.
identifier: The unique string (commonly styled as a Java resource) of a Plugin, which must match what is in the pluginDefinition.json
file.
#
Application DataservicesSee Dataservices
#
Application Configuration DataThe 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.