Sunstone Plugin Reference 3.6
This document is intended to provide a detailed description for sunstone.js
configuration objects and methods regarding the creation and use of plugins.
For information on how to write a plugin for Sunstone please read the Sunstone Plugin Guide
{ key: value }
Configuration objects are used to setup elements and capabilities of the Sunstone user interface. They are added, updated and removed from Sunstone via the Sunstone plugin interface.
Action objects are used to define actions. The keys callback
, error
, element
are optional depending on the action type
. The keys notify
and condition
are optional in all cases.
Action object | ||
---|---|---|
Key | Value type | Description |
type | string | create , list , single , multiple , custom . Types are explained below. |
call | function | The function that will be executed when the action is run. |
callback | function | Callback function for create , single and multiple action types. Will be set as the success calback function for the Ajax calls made through opennebula.js . |
error | function | Callback function for create , single and multiple action types. Will be set as the error callback function for the Ajax calls made through opennebula.js |
elements | function | A function returning an array of elements on which multiple actions will be run. Only useful for actions of type multiple , which are run from an action button. |
notify | boolean | If set to true , user will be notified when the action is run. Defaults to false. |
condition | function | Function must return true or false . If present, condition function is run right before calling the call function. If the result is false, the call function is not run. If notify is set to true the user will be notified if the condition is not met. |
There are five action types which define several particular ways of running their call
function. Action types are intended to ease the use of opennebula.js
methods. opennebula.js
offers an interface to interact with the sever side of Sunstone (that is, with OpenNebula). Actions not willing to do so or not fully adapting to the pre-defined types should be declared as type “custom”
.
Sunstone.runAction(action_name,parameter,extra_parameter)
.
Here is a detailed description of every type:
“custom”
Custom actions simply execute the call
function defined in the configuration object. If a parameter
is passed to the Sunstone.runAction()
method, it is passed directly to the call
function. Same applies for extra_parameters
. Normally, Sunstone.runAction(“myAction”,A,B)
would end up running:
call(A,B); //call is extracted from "myAction" configuration object.
“create”
, “register”
This type of actions perform a “create” or “register” operation on OpenNebula via opennebula.js
. They must have a callback
and an error
function defined in their configuration object and they must include a data_argument
when run. sunstone.js
runs this action as:
call({data:data_argument, success: callback, error:err});
therefore it uses the notation needed to call methods such Image.register
or VM.create
from opennebula.js
.
“single”
This type of actions use an opennebula.js
method run on a single element (host, VM, user…). They must have a callback
and an error
function defined in their configuration and they must include the OpenNebula ID of the affected element as data_argument
when run. sunstone.js
runs this action as:
call({data:{id:data_argument}, success: callback,error:err});
therefore it uses the notation needed to call methods such Host.enable
or User.delete
from opennebula.js
.
“multiple”
This type of actions use a opennebula.js
method afecting a single element repeteadly for each element of an array passed as data_argument
. They must have a callback
and an error
functions defined in their configuration. The data_argument
array contains the OpenNebula IDs of the elements on which the action should be run. sunstone.js
runs this action for each ID as:
call({data:{id:this}, success: callback, error:err});
If an optional extra_parameter
the action is performed as:
call({data:{id:this,extra_param:extra_param}, success: callback, error: err});
A multiple
action is equivalent to calling a single
action repeatedly on different elements.
“list”
This type of actions use a opennebula.js
list
method, which retrieves a pool of OpenNebula elements in JSON format (hosts, VMs, users…). They must have a callback
and an error
functions defined in their configuration. sunstone.js
runs this action as:
call({success: callback, error:err});
Sunstone accepts objects containing 1 or several actions in the following form. This way, action names are associated to their configuration objects.
{ "myAction1" : action_object1, "myAction2" : action_object2, "myAction3" : action_object3, ... }
Here is an example of an object containing several actions:
{ "Host.create" : { type: "create", call : OpenNebula.Host.create, callback : addHostElement, error : onError, notify: true }, "Host.show" : { type: "single", call: OpenNebula.Host.show, callback: updateHostElement, error: onError }, "Host.showinfo" : { type: "single", call: OpenNebula.Host.show, callback: updateHostInfo, error: onError }, "Host.enable" : { type: "multiple", call : OpenNebula.Host.enable, callback : function (req) { Sunstone.runAction("Host.show",req.request.data[0]); }, elements: function() { return getSelectedNodes(dataTable_hosts); }, error : onError, notify: true }, //This "list" action doesn't adapt to the "list" type as we want to //make two calls. Therefore we use a "custom" action and do the //and Cluster.list manually "Host.list" : { type: "custom", call : function() { OpenNebula.Host.list({success: updateHostsView, error: onError}); OpenNebula.Cluster.list({success: updateClustersView, error: onError}); } }, "Cluster.list" : { type: "list", call: OpenNebula.Cluster.list, callback: updateClustersView, error: onError, }, }
Button objects define a clickable element associated to an action. Button objects are planed inside button-set objects, which are part of main tabs.
Buttons are automatically generated and included in a special div (of class “action_blocks” in the content of the main tab of which they are part of. Buttons allow users to perform actions.
Each button object, part of a button-set, can be described as follows:
Button Object | ||
---|---|---|
Key | Value type | Description |
type | string | action , image , confirm , confirm_with_select or select . The button type defines the class which will be added to the button HTML: action_button , confirm_button … and so on. if a custom string is included a button with custom_string_button class will be generated. Standard types are handled differently by Sunstone and explained below. |
text | string | |
condition | function | A optional function that returns true or false . The function is run before adding the button HTML to the DOM. If it returns false , the button is skipped. |
img | string | Image path for image type buttons. |
tip | string | For confirm and confirm_with_select type buttons, this is the text that will be shown as a tip in the confirmation dialog for the action. |
alwaysActive | Boolean | Adds the class “alwaysActive” to the button, meaning the button will not be deactivated when no elements of a dataTable are selected. Useful for “New +” buttons in the standard plugins. |
select | HTML string | This is the select input which is shown in the confirm_with_select buttons' confirmation dialog. It allows the user to select an element. This element's ID will be passed as extra_parameter to the associated action. |
actions | button-set object | For buttons of type select . Actions is another button-set. This button-set object will be turned into the options of a select input field (see explanation below). |
Button's type
generally defines a class to be added to the button HTML generated code, apart from other things. There are five special types. According to their type/class, buttons produce different effects. select
buttons are special, as they produce a select input field. Find here a detailed description of each type:
“action”
Buttons of this type are standard buttons which run their associated action directly when clicked (the associated action is the button name).
“image”
Buttons of this type are turned into image links. For the rest, they act like action
buttons. Please include a img
path pointing to the image for the button.
“confirm”
Buttons of this type show a standard confirmation dialog before running their associated action. Please define an explanatory tip
along so it can give further hints to the user.
“confirm_with_select”
Buttons of this type show a standard confirmation dialog which contains a select input field before running their associated action. For example, “Add several hosts to one cluster” shows a confirmation dialog allowing the user to select a cluster. The option ID is passed as extra_parameter
to Sunstone.runAction(). Please define an explanatory tip
along so it can give further hints to the user and provide a select
function returning a well formed HTML code for the select input field.
“select”
Select buttons define a select input field containing several options. These options are defined as a second button-set which is the value of the actions
field of the button. These buttons can be of type action
, confirm
and confirm_with_select
. The rest of options remain the same as for normal buttons. Let's illustrate this type of button with a select button object:
{ //Special select button type: "select", actions: { "Cluster.addhost": { type: "confirm_with_select", text: "Add host to cluster", select: function(){return clusters_select;}, tip: "Select the cluster in which you would like to place the hosts", condition: True }, "Cluster.removehost" : { type: "action", text: "Remove host from cluster", condition: True }}, condition : True }
Button objects are grouped in button-set objects in the following way:
{ "action1": button_obj1, "action2": button_obj2, ... }
select
can have any name though.
Find here some examples on how a button-set object formed by buttons looks like:
{ "Host.refresh" : { type: "image", text: "Refresh list", img: "/images/Refresh-icon.png", condition: True }, "Host.enable" : { type: "action", text: "Enable", condition : True }, "Cluster.delete" : { type: "confirm_with_select", text: "Delete cluster", select: function(){return clusters_select}, tip: "Select the cluster you want to remove", condition : True }, "VM.hold" : { type: "confirm", text: "Hold", tip: "This will hold selected pending VMs from being deployed", condition: True } }
Main tab objects define a main tab, that is a element of the left-side menu which shows certain content in the main window when it is clicked. This is their detailed description:
Main tab objects | ||
---|---|---|
Key | Value type | Desctiption |
title | string | The name of the left-side menu link. |
content | HTML string | The HTML content shown when clicking on this tab. |
buttons | button-set object | An optional button-set object (as explained above), associated to this tab. |
condition | function | A function returning true or false . If present, condition is called before adding the tab. If it returns false the tab will not be added. |
showOnTopMenu | boolean | Shows this menu item in a menu in the top bar. Currently not used in Sunstone but implemented nevertheless |
class | string | The string will be added as class attribute to the menu element. By default, 'topTab' is used if no class is defined. Use “subTab” if menu item is part of a submenu. You can use “topTab subTab” when the menu item is part of a submenu, but also has other menu items hanging from it. |
parentTab | string | When the menu item is part of a submenu, this indicates the id of the parent node. |
Here is an example of a main tab object:
var clusters_tab = { title: tr("Clusters"), //allows translation of the title content: clusters_tab_content, //html code for the view buttons: cluster_buttons, //buttons to place as top action showOnTopMenu: false, //show tap on a top menu bar, on the top panel tabClass: "topTab subTab", //this tab is a submenu, and has itself submenus parentTab: "infra_tab", //parent menu is the infraestructure dashboard tab };
Info panels are the panels that pop up from the button of the Sunstone interface, for example, when clicking on a host element in the Host & Clusters main tab. Info panels are formed by one or several tabs.
Each tab is an object defined as follows:
Info panel tab objects | ||
---|---|---|
Key | Value type | Desctiption |
title | string | Title of the tab. |
content | HTML string | Contents of the tab. |
This is an info panel object:
{ "vm_info_tab" : { title: "Virtual Machine information", content: "This is the info tab" }, "vm_template_tab" : { title: "VM template", content: "This is the template tab" }, "vm_log_tab" : { title: "VM log", content: "This is the log tab" } }
Sunstone.updateInfoPanelTab()
.
Sunstone.popUpInfoPanel(panel_name)
method that will a) Create the HTML code for the panel on the fly b) Pop it up. That way, you only have to worry about maintaining your info panel tabs updated and you will always get a nice looking panel popping up from the button.
Sunstone offers several functions to add, update, and remove configuration objects, along with some other features. These functions are meant to be used by the plugins. Here is a detailed description of each one of them and their purpose.
Sunstone.addAction(action_name,action_obj)
Adds an action object to the Sunstone configuration.
Parameter | Type | Mandatory | Description |
---|---|---|---|
action_name | String | Yes | Name of this action. |
action_obj | Object | Yes | Action object as defined above. |
Sunstone.updateAction(action_name,action_obj)
Updates an action object in the Sunstone configuration.
Parameter | Type | Mandatory | Description |
---|---|---|---|
action_name | String | Yes | Name of this action. |
action_obj | Object | Yes | Action object as defined above. |
Sunstone.removeAction(action_name)
Removes an action object from the Sunstone configuration.
Parameter | Type | Mandatory | Description |
---|---|---|---|
action_name | String | Yes | Name of this action. |
Sunstone.addActions(actions)
Adds several actions to the configuration. See Objects for actions.
Parameter | Type | Mandatory | Description |
---|---|---|---|
actions | Object | Yes | An object containing several actions. |
Sunstone.addMainTab(tab_id,tab_obj,[refresh])
Adds a main tab to the configuration. Optionally, refreshes the DOM (if the tab is added after initialization).
Parameter | Type | Mandatory | Description |
---|---|---|---|
tab_id | String | Yes | id for this tab. |
tab_obj | Object | Yes | Main tab object as defined above. |
refresh | boolean | No | Refresh the DOM to add the new tab. |
Sunstone.updateMainTabContent(tab_id,content_arg,[refresh])
Updates the contents of an existing main tab. Optionally refreshes it in the DOM.
Parameter | Type | Mandatory | Description |
---|---|---|---|
tab_id | String | Yes | id of the updated tab |
content_arg | String | Yes | New HTML contents. |
refresh | boolean | No | Refresh the DOM with the new content. |
Sunstone.updateMainTabButtons(tab_id,buttons_arg,[refresh])
Updates the buttons of an existing main tab. Optionally regenerates them it in the DOM.
Parameter | Type | Mandatory | Description |
---|---|---|---|
tab_id | String | Yes | id of the updated tab |
buttons_arg | Object | Yes | The new button-set object containing buttons as defined above. |
refresh | boolean | No | Refresh the DOM with the new buttons. |
Sunstone.removeMainTab(tab_id,[refresh])
Removes a main tab from the configuration. Optionally, refreshes the DOM to remove the tab link and contents from it.
Parameter | Type | Mandatory | Description |
---|---|---|---|
tab_id | String | Yes | id of the tab. |
refresh | boolean | No | Refresh the DOM to remove the tab. |
Sunstone.addInfoPanel(panel_name,panel_obj)
Adds an info panel to the configuration. From this point, the panel is ready to be popped up.
Parameter | Type | Mandatory | Description |
---|---|---|---|
panel_name | String | Yes | name for this panel. |
panel_obj | Object | Yes | An info panel object as described above. |
Sunstone.updateInfoPanel(panel_name,panel_obj)
Replaces an info panel.
Parameter | Type | Mandatory | Description |
---|---|---|---|
panel_name | String | Yes | name of the panel. |
panel_obj | Object | Yes | An info panel object as described above. |
Sunstone.removeInfoPanel(panel_name)
Deletes an info panel from the configuration.
Parameter | Type | Mandatory | Description |
---|---|---|---|
panel_name | String | Yes | name of the panel. |
Sunstone.popUpInfoPanel(panel_name,[selected_tab])
Pops up an info panel from the bottom of the interface. Optionally, you can indicate which tab should be selected when it does.
Parameter | Type | Mandatory | Description |
---|---|---|---|
panel_name | String | Yes | name for this panel. |
selected_tab | Integer | No | Number of initially selected tab (>0). Defaults to 0. |
Sunstone.getInfoPanelHTML(panel_name,[selected_tab])
Returns an HTML string containing with the HTML of the desired info panel. Useful if wanting to do things with it, like putting the information on a dialog.
Parameter | Type | Mandatory | Description |
---|---|---|---|
panel_name | String | Yes | name for this panel. |
selected_tab | Integer | No | Number of initially selected tab (>0). Defaults to 0. |
Sunstone.addInfoPanelTab(panel_name,panel_tab_id,panel_tab_obj)
Adds an new tab in an existing info panel.
Parameter | Type | Mandatory | Description |
---|---|---|---|
panel_name | String | Yes | name for this panel. |
panel_tab_id | Object | Yes | The id of the info panel tab. |
panel_tab_obj | Object | Yes | A info panel tab object as described above. |
Sunstone.updateInfoPanelTab(panel_name,panel_tab_id,panel_tab_obj,[refresh])
Updates an info panel tab. Also useful for refreshing its content. If refresh
is set it will try to refresh the contents directly if they are in the DOM.
Parameter | Type | Mandatory | Description |
---|---|---|---|
panel_name | String | Yes | name for this panel. |
panel_tab_id | Object | Yes | The id of the info panel tab. |
panel_tab_obj | Object | Yes | A info panel tab object as described above. |
refresh | boolean | No | Tries to refresh the tab content if it is somewhere in the DOM. |
Sunstone.removeInfoPanelTab(panel_name,panel_tab_id)
Removes a tab from an info panel.
Parameter | Type | Mandatory | Description |
---|---|---|---|
panel_name | String | Yes | name for this panel. |
panel_tab_id | Object | Yes | The id of the info panel tab to be removed. |
Sunstone.runAction(action, [data_arg], [extra_param])
Runs the predifined call
of an action. Handles checking if condition
is met and makes sure to pop if a notication dialog if notify
is set to true
. All this parameters are extracted from the action object indicated by the action
parameter. There are different types of actions producing different effects.
Parameter | Type | Mandatory | Description |
---|---|---|---|
action | String | Yes | Name of the action that will be run. |
data_arg | Any/Array of any | No | data argument. It can be an array for multiple actions. |
extra_param | Any | No | Extra parameter. |