= How to Implement A New HeuristicLab WebApp Plugin =
[[PageOutline]]

In the following guide we will create a simple HeuristicLab WebApp plugin.
It is assumed that you have read [[Documentation/Howto/SetupHiveServer| Hive server setup]] and [[Documentation/Howto/SetupHiveStatistics| 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 
[[Image(/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
[[Image(/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.
[[Image(/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.

[[Image(/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:
{{{
#!javascript
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]] 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`