Add a quick plugin development readme
Ryan Blenis committed
Nov 23, 2019 at 04:25 UTC
f61606ef9482f35efe9630b0db310c527e2c5b5b
1 file changed
+91
plugin_development.md
new
+91
@@ -0,0 +1,91 @@
1
+# Plugin Development
2
+
3
+## Overview
4
+
5
+## Anatomy of a plugin:
6
+
7
+ - plugin_name/
8
+ -- config.json
9
+ -- plugin_name.js
10
+ -- modules_meshcore/ // optional
11
+ --- plugin_name.js // optional
12
+
13
+## Plugin Configuration File
14
+A valid JSON object within a file named `config.json` in the root folder of your project. An example:
15
+
16
+ {
17
+ "name": "Plugin Name",
18
+ "shortName": "plugin_name",
19
+ "version": "0.0.0",
20
+ "author": "Author Name",
21
+ "description": "Short Description of the plugin",
22
+ "hasAdminPanel": false,
23
+ "homepage": "https://www.example.com",
24
+ "changelogUrl": "https://raw.githubusercontent.com/User/Project/master/changelog.md",
25
+ "configUrl": "https://raw.githubusercontent.com/User/Project/master/config.json",
26
+ "downloadUrl": "https://github.com/User/Project/archive/master.zip",
27
+ "repository": {
28
+ "type": "git",
29
+ "url": "https://github.com/User/Project.git"
30
+ },
31
+ "versionHistoryUrl": "https://api.github.com/repos/User/Project/tags",
32
+ "meshCentralCompat": ">0.4.3"
33
+ }
34
+
35
+## Configuration File Properties
36
+| Field | Required | Type | Description
37
+|--|--|--|--|
38
+| name | Yes | string | a human-readable name for the plugin
39
+| shortName | Yes | string | an alphanumeric, unique short identifier for the plugin (will be used to access your functions throughout the project
40
+| version | Yes | string | the current version of the plugin
41
+| author | No | string | the author's name
42
+| description | Yes | string | a short, human-readable description of what the plugin does
43
+| hasAdminPanel | Yes | boolean | `true` or `false`, indicates whether or not the plugin will offer its own administrative interface
44
+| homepage | Yes | string | the URL of the projects homepage
45
+| changelogUrl | Yes | string | the URL to the changelog of the project
46
+| configUrl | Yes | string | the URL to the config.json of the project
47
+| downloadUrl | Yes | string | the URL to a ZIP of the project (used for installation/upgrades)
48
+| repository | Yes | JSON object | contains the following attributes
49
+| repository.type | Yes | string | valid values are `git` and in the future, `npm` will also be supported in the future
50
+| repository.url | Yes | string | the URL to the project's repository
51
+| versionHistoryUrl | No | string | the URL to the project's versions/tags
52
+| meshCentralCompat | Yes | string | the semantic version string of required compatibility with the MeshCentral server
53
+
54
+## Plugin Hooks
55
+These are separated into the following categories depending on the type of functionality the plugin should offer.
56
+
57
+- Web UI, to modify the MeshCentral admin interface
58
+- Back End, to modify core functionality of the server and communicate with the Web UI layer as well as the Mesh Agent (Node) layer to send commands and data
59
+- Mesh Agent (Node), to introduce functionality to each agent
60
+
61
+### Web UI Hooks
62
+`onDeviceRefeshEnd`: called when a device is selected in the MeshCentral web interface
63
+`registerPluginTab`: called when a device is selected in the MeshCentral web interface to register a new tab for plugin data, if required
64
+`onDesktopDisconnect`: called when a remote desktop session is disconnected
65
+
66
+#### Exports
67
+Any function can be exported to the Web UI layer by adding the name of the function to an `exports` array in the plugin object.
68
+
69
+### Back End Hooks
70
+`server_startup`: called once when the server starts (or when the plugin is first installed)
71
+`hook_agentCoreIsStable`: called once when an agent initially checks in
72
+`hook_processAgentData`: called each time an agent transmits data back to the server
73
+
74
+### Mesh Agent
75
+Use of the optional file `plugin_name.js` in the optional folder `modules_meshcore` will include the file in the default meshcore file sent to each endpoint. This is useful to add functionality on each of the endpoints.
76
+
77
+## Structure
78
+Much of MeshCentral revolves around returning objects for your structures, and plugins are no different. Within your plugin you can traverse all the way up to the web server and MeshCentral Server classes to access all the functionality those layers provide. This is done by passing the current object to newly created objects, and assigning that reference to a `parent` variable within that object.
79
+
80
+
81
+## Versioning
82
+Versioning your plugin correctly and consistently is essential to ensure users of your plugin are prompted to upgrade when it is available. Semantic versioning is recommended.
83
+> Wait, but MeshCentral uses a trailing `-<alpha_char>` for it's versions!
84
+
85
+True, but we've made sure that we made special consideration for this in the `meshCentralCompat` check, so you can specify the exact version that you're compatible with.
86
+
87
+## Changelog
88
+A changelog is highly recommended so that your users know what's changed since their last version.
89
+
90
+## Sample Plugin
91
+[MeshCentral-Sample](https://github.com/ryanblenis/MeshCentral-Sample) is a simple plugin that, upon disconnecting from remote desktop, prompts the user to enter a manual event (note), pre-filled in with the date and timestamp.
\ No newline at end of file