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.

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”.

Remember actions are run via
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'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
}

Note that Sunstone replaces these select input fields with nice-looking dropdown lists of actions attached to a “run last action” button. This is done automatically during the first initialization of the interface. So far, this improvement is not done after a refresh of the button-set at any other moment, so then the initial select input field will be shown.

Button objects are grouped in button-set objects in the following way:

{
   "action1": button_obj1,
   "action2": button_obj2,
   ...
}

The name of the button must be the name of the action it is associated to. Buttons of type 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:

Here is an example of a main tab object:

{
    title: "Virtual Machines",
    content: vms_tab_content,
    buttons: vm_buttons,
    condition: True
}

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:

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"
    }
}

Where are the real contents of the tabs? Sometimes, you do not know the content of the info panel tabs if it is not completely static. It can be added later via Sunstone.updateInfoPanelTab().

How do these panels work? There can be many info panels which can be shown in very different moments. Sunstone offers a 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.

Sunstone.updateAction(action_name,action_obj)

Updates an action object in the Sunstone configuration.

Sunstone.removeAction(action_name)

Removes an action object from the Sunstone configuration.

Sunstone.addActions(actions)

Adds several actions to the configuration. See Objects for 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).

Sunstone.updateMainTabContent(tab_id,content_arg,[refresh])

Updates the contents of an existing main tab. Optionally refreshes it in the DOM.

Sunstone.updateMainTabButtons(tab_id,buttons_arg,[refresh])

Updates the buttons of an existing main tab. Optionally regenerates them it in the DOM.

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.

Sunstone.addInfoPanel(panel_name,panel_obj)

Adds an info panel to the configuration. From this point, the panel is ready to be popped up.

Sunstone.updateInfoPanel(panel_name,panel_obj)

Replaces an info panel.

Sunstone.removeInfoPanel(panel_name)

Deletes an info panel from the configuration.

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.

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.

Sunstone.addInfoPanelTab(panel_name,panel_tab_id,panel_tab_obj)

Adds an new tab in an existing info panel.

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.

Sunstone.removeInfoPanelTab(panel_name,panel_tab_id)

Removes a tab from an info panel.

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.