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:

Your Name » System management » Plugins » Diagnostics

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.