Skip to content

Commit a7eac6c

Browse files
bryankenneallybryankenneally
committed
Create documentation for installing modeler plugins
Signed-off-by: Bryan Kenneally <Bryan.Kenneally@fmr.com>
1 parent 0d9017b commit a7eac6c

2 files changed

Lines changed: 237 additions & 23 deletions

File tree

‎README.md‎

Lines changed: 21 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -2,50 +2,48 @@
22

33
# Fluxnova Modeler Plugins
44

5-
Short blurb about what your project does.
5+
This repository contains installable plugins, plugin source code, and supporting resources for extending Fluxnova Modeler.
66

7-
## Installation
7+
## Installing Plugins
88

9-
OS X & Linux:
9+
The complete install guide lives in [docs/installing-plugins.md](docs/installing-plugins.md).
1010

11-
```sh
12-
npm install my-crazy-module --save
13-
```
11+
Use that guide for:
12+
13+
- Platform-specific installation steps for macOS, Windows, and Linux
14+
- CI artifact and release download guidance
15+
- Local build instructions for plugins that are not produced by CI
16+
- Verification and troubleshooting steps
1417

15-
Windows:
18+
Quick path for local testing of `code-editor-plugin`:
1619

1720
```sh
18-
edit autoexec.bat
21+
cd plugins/code-editor-plugin
22+
npm install
23+
npm run build
1924
```
2025

21-
## Usage example
22-
23-
A few motivating and useful examples of how your project can be used. Spice this up with code blocks and potentially screenshots / videos ([LiceCap](https://www.cockos.com/licecap/) is great for this kind of thing).
24-
25-
_For more examples and usage, please refer to the [Wiki][wiki]._
26+
Then copy the built plugin folder contents into the appropriate `resources/plugins` directory for your Fluxnova Modeler installation.
2627

2728
## Development setup
2829

29-
Describe how to install all development dependencies and how to run an automated test-suite of some kind. Potentially do this for multiple platforms.
30+
Install dependencies and build the plugin you want to work on.
3031

3132
```sh
32-
make install
33-
npm test
33+
cd plugins/code-editor-plugin
34+
npm install
35+
npm run build
3436
```
3537

36-
## Roadmap
37-
38-
List the roadmap steps; alternatively link the Confluence Wiki page where the project roadmap is published.
39-
40-
1. Item 1
41-
2. Item 2
42-
3. ....
38+
Run tests from the relevant plugin directory as needed.
4339

4440
## Contributing
41+
4542
For any questions, bugs or feature requests please open an [issue](https://github.com/finos/fluxnova-modeler-plugins/issues)
4643
For anything else please send an email to {project mailing list}.
4744

4845
To submit a contribution:
46+
4947
1. Fork it (<https://github.com/finos/fluxnova-modeler-plugins/fork>)
5048
2. Create your feature branch (`git checkout -b feature/fooBar`)
5149
3. Read our [contribution guidelines](CONTRIBUTING.md) and [Community Code of Conduct](https://www.finos.org/code-of-conduct)

‎docs/installing-plugins.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# Installing Fluxnova Modeler Plugins
2+
3+
This guide explains how to manually install a Fluxnova Modeler plugin and verify that it loads successfully.
4+
5+
Before following the platform-specific installation steps, make sure you have a plugin build ready. See the Plugin Build Sources section for CI artifacts, releases, and local build options.
6+
7+
## Overview
8+
9+
Fluxnova Modeler discovers plugins by scanning the `resources/plugins` directory when the application starts.
10+
11+
Each plugin must:
12+
13+
- Reside in its own folder under `resources/plugins`
14+
- Contain an `index.js` entry point
15+
- Be copied into the plugin directory before the Modeler is launched
16+
17+
Expected directory structure:
18+
19+
```text
20+
resources/
21+
└── plugins/
22+
└── my-plugin/
23+
├── index.js
24+
├── package.json
25+
└── ...
26+
```
27+
28+
Example `index.js` entry point:
29+
30+
```js
31+
"use strict";
32+
33+
module.exports = {
34+
script: "./dist/client.js",
35+
style: "./dist/style.css",
36+
menu: "./dist/backend/main.js",
37+
name: "Code Editor Plugin",
38+
};
39+
```
40+
41+
In this example, `script` loads frontend behavior, `style` loads plugin CSS, `menu` loads backend/menu integration, and `name` is the display name.
42+
43+
## Prerequisites
44+
45+
Before installing a plugin:
46+
47+
- Have a plugin build ready.
48+
- Verify the plugin folder contains an `index.js` file.
49+
- Close any running instance of Fluxnova Modeler.
50+
51+
## Plugin Build Sources
52+
53+
You can obtain plugin builds from CI artifacts, GitHub Releases, or by building locally when CI coverage is unavailable.
54+
55+
Prebuilt plugin builds are published in two places:
56+
57+
- Development builds are available as artifacts from individual [CI workflow runs](https://github.com/finos/fluxnova-modeler-plugins/actions/workflows/ci.yml)
58+
- Released builds are available in [GitHub Releases](https://github.com/finos/fluxnova-modeler-plugins/releases)
59+
60+
Use CI run artifacts for short-lived validation and testing, and use GitHub Releases for stable installation targets and long-term retrieval.
61+
62+
Note: CI artifacts are ephemeral and may expire based on repository retention settings.
63+
64+
If [CI does not support automated builds](https://github.com/finos/fluxnova-modeler-plugins/issues/17) for the plugin you need, build it locally from source.
65+
66+
Example local build flow for `code-editor-plugin`:
67+
68+
```sh
69+
git clone https://github.com/finos/fluxnova-modeler-plugins.git
70+
cd fluxnova-modeler-plugins/plugins/code-editor-plugin
71+
npm install
72+
npm run build
73+
```
74+
75+
After building, plugin output is available in the `dist` directory. To install manually, create a `code-editor-plugin` folder in the Modeler plugins directory and copy:
76+
77+
- `code-editor-plugin/dist`
78+
- `code-editor-plugin/index.js`
79+
80+
Expected structure in the Modeler installation:
81+
82+
```text
83+
resources/
84+
└── plugins/
85+
└── code-editor-plugin/
86+
├── index.js
87+
└── dist/
88+
```
89+
90+
---
91+
92+
## Installation Paths
93+
94+
Use the plugin directory that matches your Fluxnova Modeler installation:
95+
96+
- macOS: `/Applications/Fluxnova Modeler.app/Contents/MacOS/resources/plugins`
97+
- Windows: `C:\Program Files\Fluxnova Modeler\resources\plugins`
98+
99+
## Install the Plugin
100+
101+
### Step 1: Locate the Plugins Directory
102+
103+
Find the appropriate `resources/plugins` directory for your platform.
104+
105+
### Step 2: Create the Plugins Directory
106+
107+
If the `plugins` directory does not already exist, create it under `resources`.
108+
109+
Expected layout:
110+
111+
```text
112+
resources/
113+
└── plugins/
114+
```
115+
116+
### Step 3: Copy the Plugin
117+
118+
Copy the plugin into the `plugins` directory so that `index.js` is a direct child of the plugin folder.
119+
120+
Example:
121+
122+
```text
123+
resources/
124+
└── plugins/
125+
└── my-plugin/
126+
└── index.js
127+
```
128+
129+
### Step 4: Restart Fluxnova Modeler
130+
131+
Close and reopen the application.
132+
133+
---
134+
135+
## Verifying Installation
136+
137+
After restarting Fluxnova Modeler, verify the plugin was loaded successfully.
138+
139+
### Verify Expected Functionality
140+
141+
Depending on the plugin, you may observe:
142+
143+
- Additional menu items
144+
- New toolbar buttons
145+
- BPMN palette extensions
146+
- Custom property panels
147+
- Validation or linting enhancements
148+
- Other UI components
149+
150+
### Verify the Plugin Directory
151+
152+
Confirm the plugin exists directly beneath the `plugins` folder:
153+
154+
```text
155+
resources/
156+
└── plugins/
157+
└── my-plugin/
158+
└── index.js
159+
```
160+
161+
Correct:
162+
163+
```text
164+
plugins/
165+
└── my-plugin/
166+
└── index.js
167+
```
168+
169+
Incorrect:
170+
171+
```text
172+
plugins/
173+
└── my-plugin-main/
174+
└── my-plugin/
175+
└── index.js
176+
```
177+
178+
The folder containing `index.js` must be a direct child of `plugins`.
179+
180+
---
181+
182+
## Troubleshooting
183+
184+
### Plugin Does Not Appear
185+
186+
Verify that:
187+
188+
- The plugin folder was copied into `resources/plugins`.
189+
- The plugin contains an `index.js` file.
190+
- The plugin directory structure is correct.
191+
- Fluxnova Modeler was restarted after installation.
192+
193+
### Plugin Causes Startup Errors
194+
195+
If the application fails to start after installing a plugin:
196+
197+
1. Remove the plugin folder from `resources/plugins`.
198+
2. Restart Fluxnova Modeler.
199+
3. Verify the application starts normally.
200+
4. Review plugin logs or console output for errors.
201+
202+
---
203+
204+
## Example Final Structure
205+
206+
```text
207+
Fluxnova Modeler/
208+
└── resources/
209+
└── plugins/
210+
├── plugin-a/
211+
│ └── index.js
212+
└── plugin-b/
213+
└── index.js
214+
```
215+
216+
On startup, Fluxnova Modeler scans the `resources/plugins` directory and loads all valid plugins that contain an `index.js` entry point.

0 commit comments

Comments
 (0)