Plugin development
Authorise with server
The plugin tool needs to be authorised to use your server. Start the process by running the plugin tool auth command, specifying the hostname of your application.
haplo-plugin auth app.example.com
Next, you need to open your web browser and authenticate the request. The plugin tool will have printed out a URL to visit, and on some platforms, will have automatically opened the page in your web browser.
After you have authenticated, return to the terminal and wait until the plugin tool finishes the authorisation process.
This will set the default server, which will be used for future haplo-plugin commands. You can authorise the plugin tool for multiple servers, then use the server command to switch between them. To choose a server temporarily, use the -s command line switch. You only need specify a unique substring of the server name.
The API keys used by the plugin tool are stored in a .server.json file in the current directory. Do not commit this to source control.
Creating a new plugin
To create a new plugin called test_plugin, make sure you’re in your project folder, then type:
haplo-plugin -p test_plugin new
This will create a test_plugin folder, populated with the minimum files necessary to register the plugin and respond to an HTTP request.
Developing your plugin
Typing
haplo-plugin -p test_plugin
will upload the plugin to the server, and install it. You can test the plugin by visiting the URL given in the output from the new command, replacing the hostname with the hostname of the application you’re using for development.
While it is running:
- if you make any changes to the files on the disc, the Plugin Tool will automatically upload them to the server
- if your plugin calls console.log(), the message will output by the Plugin Tool.
See working with databases for notes on how to use the relational database during development.
Errors
When developing a plugin, you may occasionally make a mistake.
Errors are reported in two ways. Firstly, within your web browser, and secondly, as output from the Plugin Tool.
The Plugin Tool also does syntax and code correctness checking with JSHint. Plugins won’t be accepted unless they pass these tests which help you avoid common mistakes.
If your plugin doesn’t work as you expect, for example a change isn’t applied, check the output of the Plugin Tool in the terminal window. It will attempt to make a beep sound when it needs your attention, but this may not work on your platform.
Tests
Where appropriate, you should write automated tests for your plugin’s key functionality. To run them, use the test command:
haplo-plugin -p test_plugin test
The test command takes an optional argument to specify a subset of the tests. If given, only the test scripts whose filenames contain the given string will be run.
Debugging
Currently debugging support is a little minimal, limited to reporting errors in the web browser and viewing the output of console.log() while the Plugin Tool is running the develop command.
You can also view the output of console.log() in System management:
A full debugger may be provided in the future.
Uninstallation
To remove a plugin under development, type
haplo-plugin -p test_plugin uninstall
Run the plugin tool again to upload and re-install the plugin.
Usage
For full command line usage information, type
haplo-plugin --help
to display the built in documentation.