SCM-Manager v2 Plugin Development

Build and testing

The plugin can be compiled and packaged with the normal maven lifecycle:

compile - mvn compile - compiles Java code and creates the ui bundle
test - mvn test - executes test for Java and JavaScript
package - mvn package - creates the final plugin bundle (smp package) in the target folder
install - mvn install - installs the plugin (smp and jar) in the local maven repository
deploy - mvn deploy - deploys the plugin (smp and jar) to the configured remote repository
clean - mvn clean - removes the target directory

For the development and testing the serve lifecycle of the plugin can be used:

run - mvn run - starts scm-manager with the plugin pre installed.

If the plugin was started with mvn run, the default browser of the os should be automatically opened. If the browser does not start automatically, start it manually and go to http://localhost:8081/scm.

In this mode each change to web files (src/main/js or src/main/webapp), should trigger a reload of the browser with the made changes. If you compile a class (e.g.: with your íde from src/main/java to target/classes), the SCM-Manager context will restart automatically. So you can see your changes without restarting the server.

Directory/File structure

Directories

src/main/java (contains the Java code)
src/main/resources (contains the the classpath resources)
src/main/webapp (contains static files, which are accessible by the web ui)
src/main/js (contains the JavaScript code for the web ui, inclusive unit tests: suffixed with .test.js)
src/test/java (contains the Java unit tests)
src/test/resources (containers classpath resources for unit tests)
target (build directory)

Files

pom.xml (Maven configuration)
package.json (ui dependency/build configuration)
yarn.lock (ui dependency configuration)
.eslintrc (ui linter configuration)
.flowconfig (ui typecheck configuration)
.babelrc (ui javascript language level configuration)
src/main/resource/locale/(de|en)/plugins.json (i18n configuration, see i18n for plugins)
META-INF/scm/plugin.xml (plugin descriptor)

UI Extensions

Plugins are able to extend or modify the ui of SCM-Manager. In order to extend the ui the plugin requires a package.json in the project root e.g:

{
  "name": "@scm-manager/scm-readme-plugin",
  "main": "src/main/js/index.js",
  "scripts": {
    "build": "ui-bundler plugin"
  },
  "dependencies": {
    "@scm-manager/ui-extensions": "^0.0.6"
  },
  "devDependencies": {
    "@scm-manager/ui-bundler": "^0.0.3"
  }
}

The main field of the package.json describes the main entry point of the plugin. The file specified at main should use the binder from the @scm-manager/ui-extensions in oder to bind its extensions. For more information of extensions, binder and extension points, please have a look at the readme of @scm-manager/ui-extensions.

If the plugins gets build (mvn package or mvn install), the buildfrontend-maven-plugin, will call the build script of package.json. The build script triggers the plugin command of the @scm-manager/ui-bundler. The ui-bundler will do the following steps:

traverses the import statements of the script specified at main
transpiles flow/es@next to es5
creates a single bundle
registers the bundle in the plugin.xml
stores the bundle in the final scmp package

At runtime the plugins are loaded by PluginLoader. The PluginLoader is a React component, which does the following steps:

fetches plugin metadata (name and registered bundles) from the rest service
fetches each bundle of every plugin
executes each bundle
starts the rest of the application

Static web resources

A plugin can also store static files in the src/main/webapp directory. All files of the webapp directory can be resolved relative to the root of the application e.g. the file src/main/webapp/images/logo.jpg of a plugin can be resolved at http://localhost:8081/scm/images/logo.jpg assuming SCM-Manager is running at http://localhost:8081/scm.

4.4 KiB Raw Blame History