~~NOTOC~~

<html><div><p class="bigheader">Sunstone Operations Center Plugin Guide 3.0</p></div></html>


Sunstone client-side has a plugin-oriented structure that allows users to select which features are active and to develop their own extensions and easily include them in the web interface. Plugins can use the Sunstone interface to run and modify common OpenNebula actions, show custom information panels and offer extended capabilities for Sunstone.

This guide will explain how to configure existing plugins, how plugins work and what can be achieved with them. A full reference of the plugin API can be found [[.:sunstone_plugin_reference|here]].

======Configuring Sunstone Plugins======

===== sunstone-plugins.yaml =====

Sunstone plugins configuration file states which Sunstone base plugin files should be loaded after the user successfully logs in the Sunstone interface. 

It can be found at ''/etc/one/sunstone-plugins.yaml''.

In practice, the Sunstone base plugins are equivalent the main menu tabs in the Sunstone interface:

{{ :documentation:rel3.0:sunstone:menu.png |}}

This configuration file uses the YAML format, and allows to indicate for which users or groups certain plugin files will load. This is done through the following procedure:

  * First check: is there a rule enabling/disabling the plugin for the user?
  * Second check: is there a rule enabling/disabling the plugin for the user group?
  * Third check: is there a rule enabling/disabling the plugin for all users?

The configuration file uses de following syntax:

<code>
- plugin/file/path.js:
    :ALL: true|false        # Should this file be loaded for everyone?
    :users:                 # List of users
       user1: true|false    # Enable/disable file for this user
       user2: true|false    # Enable/disable file for this user
    :groups:
       group1: true|false   # Enable/disable file for users in this group
</code>

**Example**: the admin dashboard plugin file is disabled for all users, and loaded only for users belonging to the ''oneadmin'' group. The user dashboard is enabled for all users, but disabled for users belonging to the ''oneadmin'' group:

<code>
- plugins/dashboard-tab.js:
    :ALL: false
    :user:
    :group:
        oneadmin: true
- plugins/dashboard-users-tab.js:
    :ALL: true
    :user:
    :group:
        oneadmin: false
</code>


=====User Plugins=====

User plugins should be dropped in the ''public/js/user-plugins'' folder in the Suntone base directory. These plugins will be loaded automatically after successful user login, following alphabetic order of their filename, and after the base plugins are loaded.


======Customizable elements in Sunstone======

=====Actions=====

Actions are configurable objects which allow Sunstone to run common and custom methods. Plugins can easily:
  * Customize the actions (change behaviour, complete it, tweak it)
  * Add conditions to the actions (allow execution only if certain conditions are met).
  * Use opennebula.js methods. ''Sunstone.runAction()'', A wrapper for the opennebula.js methods (containing ajax communication with the server side of Sunstone for actions on OpenNebula), is provided to ease the utilization of them.
  * Pop-up custom information dialogs when actions are executed or fail.

<html><div class="imp"></html>
:?:  **Why using actions?** Actions have an associated function (''call'') which is defined by a configuration object which must be added to Sunstone. Then ''Suntone.runAction()'' is used to execute their associated function ([[#2. Sunstone options setup|see instructions below]]). You may be wondering why so much hassle when you can simply use the action ''call'' directly from your code and get things going.

When you define an action, you are not only taking advantage of the ''opennebula.js'' wrapper, the built-in ''notify'' option to inform the user or the ''condition'' check before running your function. You can take care of all this manually without many problems. The real added value of actions is that they can be changed, tweaked and replaced by any other plugins willing to do so. So by defining an action you are implicitly accepting that someone else may come and change it's behaviour, disable it or simply re-use it very easily in exact the terms you defined in the action object.
<html></div></html>

=====Main tabs=====

Main tabs are the elements on the left-side menu. When clicking on the menu items, the content of the clicked //main tab// is shown on the main window. Sunstone allows to add/remove/modify these tabs.

=====Set of action buttons=====

Action buttons are a set of clickable elements associated with an action that can be added, customized. rearranged very easily. Buttons are contained within the main tabs, generated automaticly from an configuration object and included in their content. They offer as well the possibility to use standard confirmation dialogs before running their associated action.

=====Extended information panels=====

Information panels pop-up from the bottom of the GUI to offer extended informations about a particular element (like a Virtual Machine). They are composed by tabs. Sunstone plugins can easily create and modify their own information panels, tabs and contents. Sunstone provides an easy method to pop-up the panels when needed.

======Writing a plugin for Sunstone======

=====Files=====

Sunstone plugins need to be written in Javascript. There are two main files in Sunstone (public/js folder) related to the development of plugins and 9 standard plugins:
  * ''sunstone.js'' offers a full interface for plugins to manage the customizable capabilities of the interface (see the [[.:sunstone_plugin_reference| Sunstone Plugin Reference]]).
  * ''sunstone-util.js'' contains multiple helper functions to ease common tasks of the base Sunstone plugins.
  * ''dashboard-tab.js'', ''dashboard-users-tab.js'', ''hosts-tab.js'', ''vms-tab.js'', ''users-tab.js'', ''vnets-tab.js'', ''templates-tab.js'', ''images-tab.js'', ''groups-tab.js'', ''acls-tab.js'' can be found under the plugins/ folder. They are the standard plugins for Sunstone corresponding to each of the main tabs of the GUI. They can be inspiring when writing new plugins or customizing its current features.

For user contributed plugins, they should be placed under the ''public/js/user-plugins'' folder.

=====Structure=====

We have used the following structure when writing a plugin, though it is as flexible as the Javascript language allows:

==== 1. Variable declaration - static contents ====

Declare first the global variables and static contents that your plugin will be using.

  * //Example//: ''users-tab.js'' plugin

Users plugin declares the tab content (HTML for the user list table inside a form -as it as buttons, also the HTML content for the user creation dialog and two variables to store the user list in JSON format and the JQuery dataTable.

<code>
var users_tab_content = 
 '<form id="user_form" action="" action="javascript:alert(\'js error!\');">\
    <div class="action_blocks">\
    </div>\
    <table id="datatable_users" class="display">\
    ...
  </form>';

var create_user_tmpl =
  '<form id="create_user_form" action="">\
    <fieldset>\
    ...
    </fieldset>\
  </form>';

var dataTable_users;

</code>

==== 2. Sunstone options setup =====

Second step is to create the objects that will be used to customize Sunstone. This configuration understood as an initialization step, before the DOM is ready. Handling dynamic changes to the configuration and responding to user actions comes later.

This step is the perfect place to define the objects describing:

  * **Custom actions**

An action object is a Javascript object defining several parametres of an action such as the ''type'', the ''call'' (function that will be called when it is executed), the ''notify'' (shall Sunstone notify the user when the action is run?) and the condition (a function returning true/fase to check if the action can be executed before running the ''call''). 

Defining actions allows using the ''Sunstone.runAction(action_name,parametre,[extra_parameter])'' function. This function offers a wrapper to ease the use of opennebula.js functions but it has many other uses. For example, it takes care of checking if the ''condition'' to run the action is met, it shows an info box if ''notify'' is ''true'', and allows as well to run custom actions. Custom actions are very useful if we want to define buttons that execute them and let Sunstone take care of the generation of the HTML code to do so.

Note that when working with ''opennebula.js'' methods, a ''callback'' function, an ''error'' and an ''elements'' function (for actions of type ''multiple'') must be provided.

It is advised to define an object containing all the action objects needed. You can check the [[.:sunstone_plugin_reference | Sunstone plugin reference]] to obtain detailed information about these objects and the types of actions. Let's see some examples on how they look like:

  * //Example//: ''vnets-tab.js'' plugin

An object "vnet_actions" will store all the actions related to this plugin:

<code>
var vnet_actions = {

//Here's an action that allows to get a fresh list of virtual networks.
//The name of the action is totally custom and has 
//no relation with the parameters inside.

    "Network.list" : {
        type: "list",
        call: OpenNebula.Network.list,
        callback: updateVNetworksView,
        error: onError
    },

</code>

The Network.refresh is defined so it runs a custom piece of code that turns the virtual network datatable elements into "waiting" state and that then refreshes the list:

<code>

   "Network.refresh" : {
        type: "custom",
        call: function(){
            waitingNodes(dataTable_vNetworks);
            Sunstone.runAction("Network.list");
        }
    },
</code>

The Network.delete action is meant to be run on multiple elements. Therefore we include an action of type "multiple":

<code>
    "Network.delete" : {
        type: "multiple",
        call: OpenNebula.Network.delete,
        callback: deleteVNetworkElement,
        elements: function() { return getSelectedNodes(dataTable_vNetworks); },
        error: onError,
        notify: true
    }
}
</code>

  * **Custom main tabs**

A tab is a Javascript object with 2 mandatory keys: ''title'' and ''content''. Optionally ''condition'' function and a ''buttons'' object can be included. The ''condition'' function must return ''true'' or ''false''. If the condition is not met at the time of adding the tab in Sunstone, it will not be added.

At his point, ''buttons'' objects are used to easily include a set of clickable elements in the ''.action_blocks'' div present in the tab content. There are 5 types of buttons: ''image'', ''action'', ''confirm'', ''confirm_with_select'' and ''select''. The name (key) for each button object should be the name of the action to be run when they are clicked.

Extended information about each of the type of buttons and its purpose can be found in the [[.:sunstone_plugin_reference#button_objects | Sunstone reference]].

Let's see a typical example of a tab:

  * //Example//: ''vms-tab.js'' plugin

The Virtual Machine plugin defines some buttons to perform basic actions: "VM.refresh", "VM.create_dialog" and "VM.shutdown". This actions have been defined before in the ''vms_actions'' object:

<code>
var vm_buttons = {
    "VM.refresh" : {
        type: "image",
        text: "Refresh list",
        img: "/images/Refresh-icon.png",
        condition: True
    },
    
    "VM.create_dialog" : {
        type: "create_dialog",
        text: "+ New",
        condition: True
    },
    
    "VM.shutdown" : {
        type: "confirm",
        text: "Shutdown",
        tip: "This will initiate the shutdown process in the selected VMs",
        condition: True
    }
...
}
</code>

With these buttons we can create the tab object for VMs:

<code>
var vms_tab = {
    title: "Virtual Machines",
    content: vms_tab_content,
    buttons: vm_buttons
}
</code>

  * **Custom information panels**

Sunstone information panels can also be customized. They are completely independent from the rest of the contents and are defined through a info panel object. Info panels are simply composed by one or several tabs. Each tab has a ''title'' and a ''content''.

After creating them, panels can be poped up using ''Sunstone.popUpInfoPanel(panel_name)''. Sunstone will generate on the fly all the neccesary HTML to make this panel look nice (with Jquery tabs) when you pop it up. Let's see an example:

  * //Example//: ''vms-tab.js'' plugin

This plugin defines one panel with three tabs. The tabs from this panel will be updated when needed, so for now their content is empty.

<code>
var vm_info_panel = {
    "vm_info_tab" : {
        title: "Virtual Machine information",
        content: ""
    },
    "vm_template_tab" : {
        title: "VM template",
        content: ""
    },
    "vm_log_tab" : {
        title: "VM log",
        content: ""
    }
}
</code>

==== 3. Add options to Sunstone ====

After defining the objects containing the desired actions, main tab, and info panels you can simply do:

<code>
Sunstone.addActions(actions_object);
Sunstone.addMainTab(tab_name_string,tab_object);
Sunstone.addInfoPanel(info_panel_name_string,info_panel_object);
</code>

and Sunstone will introduce your tab, with your content and buttons, and a link to it in the left-side menu. The info panel is stored ready to be poped-up when needed.


==== 4. DOM-dependant initializations interaction management====

All the previous steps will leave Sunstone ready to use your plugin as soon as it initializes. However you may want to still do some things as soon as the DOM is ready (like enhacing some HTML code with Javascript or adding custom listeners in order to respond to events produced on elements of the DOM). 

We can use the ''JQuery.ready()'' function to achieve it:

<code>
$(document).ready(function(){
//initialize datatables
//preload datatables
//initialize listeners
//initialize autorefresh
})
</code>

Standard plugins use the ''ready()'' function to setup the datatables, preload their contents, set some listeners and enhace some visual parts of the code.

Typical uses include setting a listener to pop up an extended information panel which has been previously defined. 

=====Extended features=====

[[.:sunstone_plugin_reference#sunstone_plugin_interface|sunstone.js]] offers a wide range of functions not only to add custom tabs, actions etc. but also to modify and refresh them in the DOM once the application is running. Therefore, a tab can be removed, a button effect changed and and info panel tab added anytime.

This functions allow the plugin developpers to have full flexibility in order to design and deploy not only their own independent plugins, but also plugins affecting other plugins (like the standard ones). 

A good example would be to write a plugin that allows users to have a custom dashboard. Changing the dashboard content at any point could be easily achieved by running:

<code>
Sunstone.updateMainTabContent("dashboard_tab", "<div>My new content</div>",true)
</code>

The true argument tells Sunstone that the content needs to be refreshed in the DOM.


======Sunstone Dummy plugin======

This plugin uses basic functionality to illustrate some of the capacities of sunstone by adding a new tab with some functionalities. You can have a look to it in the [[.:sunstone_dummy_plugin|Sunstone Dummy Plugin page]].