wiki:Documentation/Howto/ImplementAHLWebAppPlugin

How to Implement A New HeuristicLab WebApp Plugin

In the following guide we will create a simple HeuristicLab WebApp plugin. It is assumed that you have read Hive server setup and Hive statistics setup.

A new project

We will now create a new Visual Studio project which will become the WebApp plugin.

  • In Visual Studio select "File > New > Project..." or press <Ctrl+Shift+N>
  • Use the "Class Library" template
  • Use "HeuristicLab.Services.WebApp.Example" as name

/raw-attachment/wiki/Documentation/Howto/ImplementAHLWebAppPlugin/create_project_vs.PNG

Configuring the project

References

Every plugin has at least a reference to Microsoft ASP.NET Web API, which is needed to create a controller.

  • Open the NuGet Package Manager and add a reference to Microsoft ASP.NET Web API

/raw-attachment/wiki/Documentation/Howto/ImplementAHLWebAppPlugin/nuget_project_references.PNG

  • If database access is required, add project references to HeuristicLab.Services.Hive and HeuristicLabServices.DataAccess
  • Set the "Copy Local" property on these references to false. This references are provided by the WebApp and thus don't have to be deployed with every plugin.

/raw-attachment/wiki/Documentation/Howto/ImplementAHLWebAppPlugin/references.PNG

Folder structure

HeuristicLab WebApp plugins use the following folder structure, which is recommended but not mandatory. The WebApp consists of all client files whereas the WebApi contains all data controllers.

/raw-attachment/wiki/Documentation/Howto/ImplementAHLWebAppPlugin/folder_structure.PNG

Creating the Plugin configuration file

Every plugin requires a configuration file, which is used to register the views of the plugin with their associated controllers. The configuration file is also used to dynamically build the sidebar menu. The name of the plugin configuration file has to be {pluginname}.js.

The following template can be used to create a new configuration file:

var appPluginNamePlugin = app.registerPlugin('pluginname');
(function () {
    var plugin = appPluginNamePlugin;
    plugin.dependencies = ['ngResource'];
    plugin.files = [];
    plugin.view = '';
    plugin.controller = '';
    plugin.routes = [];

    var menu = app.getMenu();
    var section = menu.getSection('Menu', 1);
    section.addEntry({
        name: 'Pluginname',
        route: '#/pluginname'
    });
})();
  • plugin.dependencies specifies the required AngularJS modules
  • plugin.files specifies the files that will be dynamically loaded when a view of the plugin is accessed
  • plugin.view is the main view of the plugin
  • plugin.controller is the controller of the main view
  • plugin.routes is used to register new routes (e.g. more than one view)
  • app.getMenu() is used to add an entry in the sidebar menu

The view and controller properties are required. All other properties are optional.

Example Plugin

The https://dev.heuristiclab.com/trac.fcgi/browser/trunk/sources/HeuristicLab.Services.WebApp.Status/3.3/ plugin can be used as a good example of how to structure and configure a WebApp plugin.

Conventions

  • Controllers have to be derived from ApiController and have to end with Controller to be discovered by the WebApp
  • The plugin assembly name has to match the following HeuristicLab.Services.WebApp.{pluginname}*.dll pattern
  • The plugin configuration file has to be {pluginname}.js
Last modified 19 months ago Last modified on 10/20/15 15:23:08

Attachments (5)

Download all attachments as: .zip