-
Notifications
You must be signed in to change notification settings - Fork 42
Plugin package file structure
A Zowe plugin can be loaded from a filesystem accessible to the Zowe App Server, or dynamically at runtime. When accessed from a filesystem, there are important considerations for both the developer and the end-user as to where files must be placed for proper build, packaging, and operation.
At the root of an plugin's directory, the following content is found
This file describes a Plugin to the App server. A Plugin is the unit of extensibility for the App server, where an App is a Plugin of type Application, the most common and visible to the end-user.
A definition file will tell the server whether the App has server-side Dataservices, client-side web content, or both.
The attributes of this file and how it is found by the server are described in the Plugin Definition article.
Standardized structure of source code is not required for Zowe plugins, but can help you make use of Zowe development utilities, and aid with demonstration or documentation.
The following directories should not be seen on a deployed server, since the directories are not read by the server but are used to build content that is.
When an plugin has Dataservices of the type "router", these are interpreted by the App Server by attaching them as ExpressJS routers. It is strongly suggested that these be written in Typescript, as it leads to more well-structured code than Javascript. Use of Typescript results in build steps as the pre-transpilation Typescript content is not to be consumed by NodeJS. Therefore, within nodeServer, you should keep your server-side source code. At runtime, the server loads router dataservices from the lib directory.
When an plugin has the webContent attribute in its Definition, it is an App and the server will serve static content for a client. It is strongly suggested that Apps be written in Typescript (above) and packaged via Webpack in order to optimize loading of the App to the user. Use of Typescript and Webpack both result in build steps as the pre-transpilation Typescript and the pre-webpack content are not to be consumed by the browser. Therefore, the source code should be separated from the served content by placing source code within webClient.
At runtime, a different set of directories are used by the server & client rather than those described for use in the dev environment.
The lib directory is where router or service-type Dataservices are loaded by use in the App Server. If the JS files that are loaded from the lib directory require NodeJS modules which are not provided by the server base (modules zlux-server-framework requires are added to NODE_PATH at runtime), then these modules must either be included in lib/node_modules for local directory lookup or be found on the NODE_PATH environment variable. nodeServer/node_modules is not automatically accessed at runtime as it is a dev & build directory.
The web directory is where the server will serve static content for an App that has included the webContent attribute in its Definition. Typically this directory contains the output of a webpack build. Anything put in this folder can be accessed by a client, so only put content here that is intended to be consumed by clients.
Configuration 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 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.
In 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.