Jump to: navigation, search

OpenDaylight dlux:Create and add a module

Introduction

This section describes how to create a new javascript module for OpenDaylight DLUX. Each JS module is written using angularJS and requireJS and packaged as a jar using maven. A sample module project structure will look as below -


<module-name>-resources
-- src
---- main
------resources
-------- <module-name>
----------- <module_name>.module.js 
----------- <module_name>.controller.js  
----------- <module_name>.services.js  
----------- <module_name>.directives.js  
----------- <module_name>.filter.js
----------- index.tpl.html
----------- <a_stylesheet>.css
-- pom.xml
 

All of your module code will reside under resources of your maven project.

Define the module

Create an empty file with the module name such as topology.module.js. Below is the sample content for any module.js file -

define(['angularAMD','app/routingConfig', 'angular-ui-router','app/core/core.services'], function(ng) {
    var module = angular.module('app.a_module', ['ui.router.state', 'app.core']);
    
    // module configuration
    module.config(function() {
        [...]
    });

   return module;
});

In above sample code, we surround angularJS module with a define function. This allows requireJS to see our module.js files. The first argument of define function is an array which contain all the module dependencies. The second is a callback function whose body contain the angularJS module code. The function parameters correspond with the order of dependencies. Each dependences is injected into a parameter, if it is provided. Finally, we return the angular module to be able to inject it as a parameter in our others modules.

For each new module, you must have at least these two dependencies :

  • angularAMD : It is a wrapper around angularJS to provide an AMD support(Asynchronous Module Definition). Which is used by requireJS. For more information click here.
  • app/core/core.services : This one is mandatory if you want to add content in the navigation menu, the left bar or the top bar.

The following are not mandatory, but very often used.

  • angular-ui-router : A library to provide url routing
  • routingConfig : To set the level access to a page


Set the register function

If your module is required by the main application, you will need to register your angular components because the parent DLUX app will be already bootstraped. Without the following code, DLUX won't see your components on the runtime.

Note : If your module is only use by an other module, you don't have to do this step.

  module.config(function($compileProvider, $controllerProvider, $provide) {
    module.register = {
      controller : $controllerProvider.register,
      directive : $compileProvider.directive,
      factory : $provide.factory,
      service : $provide.service
   
    };

Set the route

The next step is to set up the route for our module. This part is also done in the configuration method of the module. We have to add $stateProvider as a parameter.

module.config(function($stateProvider) {
    var access = routingConfig.accessLevels;
    $stateProvider.state('main.module', {
      url: 'module',
      views : {
        'content' : {
          templateUrl: 'src/app/module/module.tpl.html',
          controller: 'ModuleCtrl'
        }
      }
    });
});

Adding element to the navigation menu

To be able to add item to the navigation menu, the module requires the NavHelperProvider parameter in the configuration method. This helper has a method to easily append contain into the menu. The first parameter is an id who refer as the level of your menu and the second is a object.

var module = angular.module('app.a_module', ['app.core']);
module.config(function(NavMenuHelper) {
    NavMenuHelper.addToMenu('myFirstModule', {
        "link" : "#/module/index",
        "active" : "module",
        "title" : "My First Module",
        "icon" : "icon-sitemap",
        "page" : {
            "title" : "My First Module",
            "description" : "My first module"
        }
    });
});

The ID parameter support, for now, two level of depth. So if your ID look like 'rootNode.chilNode', the helper will look for a node named 'rootNode' and it will append the 'childNode' to it. If the root node doesn't exist, it will create it.

Link the controller file

To include the controller file, we will use the NavHelperProvider. It contain a method who will load the given file.

    [...]
    NavHelperProvider.addControllerUrl('<path_to_module_folder>/<module_name>.controller');

The module.js file is now complete

Create the Controllers, factory, directive, etc

Creating the controller and other components are similar to the module.

  • First, add the define method
  • Second, add the relative path to the module definition
  • Last, create your methods as you usually do it with angularJs
define(['<relative_path_to_module>/<module_name>.module'], function(module) {
    module.register.controller('ModuleCtrl', function($rootScope, $scope) {
    });
});

Note : Don't forget, if your module only refer to an other module you don't need the register.

To deploy your application, you have to create your application bundle that Karaf can understand. Checkout this wiki for add a new application bundle .

Editing POM.xml files

Note: If you are writing an application outside DLUX repository, you don't have to do the following steps.

The last thing you need to do is, modify the POM.xml files inside the main dlux directory (dlux/), modules directory (dlux/modules/) and dlux-web directory (dlux/dlux-web/). Edit the POM.xml files as the following

POM.xml file inside dlux/

<properties>
      <nexus.repository.release>opendaylight.release</nexus.repository.release>
      <nexus.repository.snapshot>opendaylight.snapshot</nexus.repository.snapshot>
      <{app_name}.resources.version><<Version>></{app_name}.resources.version>
      ...........
<properties>

POM.xml file inside dlux/modules/

   <modules>
       <module>{name of the app directory}</module> //For example "grouppolicy-resources" or "loader-resources"
       .......
   </modules>

POM.xml file inside dlux/dlux-web/

    <dependencies>
        <dependency>
           <groupId>org.opendaylight.dlux</groupId>
           <artifactId>dlux.{app Name}.resources</artifactId>
           <version>${{app name}.resources.version}</version>
        </dependency>
    </dependencies>
      ......
    <includeArtifactIds>    //Line 183
        dlux.{app name}.resources      //for example "dlux.grouppolicy.resources" or "dlux.topology.resources"
        .....
    </includeArtifactIds>