Finesse

Container Services

Class finesse.containerservices.ContainerServices

Provides container level services for gadget developers. Gadgets can utilize the container dialogs and event handling to add or remove a service.

Example

Code Snippet

Copyvar containerServices = finesse.containerservices.ContainerServices.init();
containerServices.addHandler(
    finesse.containerservices.ContainerServices.Topics.ACTIVE_TAB,
    function() {
        clientLogs.log("Gadget is now visible"); // log to Finesse logger
        // automatically adjust the height of the gadget to show the html
        gadgets.window.adjustHeight();
    }
);
containerServices.makeActiveTabReq();

Methods

activateMyTab()

Activates the tab in the container in which the gadget is present.

Example

Code Snippet

Copyfinesse.containerservices.ContainerServices.activateMyTab();

activateTab(tabId)

Activates a particular tab in the container.

Example

Code Snippet

Copyfinesse.containerservices.ContainerServices.activateTab(tabId);

Parameters


Name	Type	Description	Required
tabId	String	The Id (not the label text) of the tab is activated. If the Id is invalid, no action occurs.	Yes

addHandler(topic, callback)

Adds a handler for the specific Container Services topic. For more information on topics, see Container Services Topics.

Example

Code Snippet

Copyfinesse.containerservices.ContainerServices.addHandler(finesse.containerservices.ContainerServices.Topics.
TIMER_TICK_EVENT,callback);

Parameters


Name	Type	Description	Required
topic	String	Hub topic that the gadget wants to listen to. For more information on topics, see Container Services Topics.	Yes
callback	Function	An asynchronous callback function that is invoked when the hub topic is notified.	Yes

collapseMyGadget()

Collapses the gadget by hiding its contents for gadgets that are collapsible. In the collapsed state, only the gadget header is displayed.

Example

Code Snippet

Copyfinesse.containerservices.ContainerServices.collapseMyGadget();

To make the gadget collapsible, add <Optional feature="collapsible" /> in to the ModulePrefs inside the gadget XML.

Example: Enable Collapse Feature

Code Snippet

Copy<ModulePrefs title="Sample Gadget" description="Sample Gadget">
    <Optional feature="collapsible" />
</ModulePrefs>

Note	Ensure that the gadget height is set using `gadgets.window.adjustHeight` before making a call to `finesse.containerservices.ContainerServices.collapseMyGadget`.

enableTitleBar()

Displays the title bar for a page-level gadget which is not visible by default. This is not applicable for a tab-level gadget and can be used within a gadget.

Example

Code Snippet

Copy
containerServices = finesse.containerservices.ContainerServices.init();
containerServices.enableTitleBar();

expandMyGadget()

Expands the gadget which is collapsed to display its contents.

Example

Code Snippet

Copyfinesse.containerservices.ContainerServices.expandMyGadget();

Note	Ensure that the gadget height is set using `gadgets.window.adjustHeight` before making a call to `finesse.containerservices.ContainerServices.expandMyGadget`.

getMyGadgetId()

Retrieves the Id of the gadget.

Example

Code Snippet

Copyfinesse.containerservices.ContainerServices.getMyGadgetId();

Returns

{Number} Id of the gadget

getMyGadgetView()

Returns the current view details of the gadget. To identify if the gadget is in canvas (maximized) or default (restored) state, you must use this at the gadget inital load time. In all the other scenarios, gadget can use finesse.containerservices.ContainerServices.Topics.GADGET_VIEW_CHANGED_EVENT to get to the gadget view change events.

Example

Code Snippet

Copy
containerServices = finesse.containerservices.ContainerServices.init();
var viewConfig = containerServices.getMyGadgetView();
var newgadgetHeight = viewConfig.maxAvailableHeight;

Returns

{Object} The gadget details that include the following:

gadgetId—The Finesse gadget ID
tabId—The tab ID of the container or the gadget
maxAvailableHeight—Maximum available height that can be used by the gadget iframe
view—'canvas' or 'default', where canvas is maximized and default is restored state of a gadget

getMyTabId()

Retrieves the tabId of the container or gadget.

Example

Code Snippet

Copyfinesse.containerservices.ContainerServices.getMyTabId();

Returns

{String} The tabId of the container or gadget.

hideCertificateBanner(id)

Hides the Certificate Banner. The banner is hidden when all the gadgets that invoked showCertificateBanner have made a corresponding invocation to hideCertificateBanner, or when the user closes the banner manually.

Example

Code Snippet

Copy
// For Gadgets
containerServices = finesse.containerservices.ContainerServices.init();
containerServices.hideCertificateBanner();

// For non gadget Client
containerServices.hideCertificateBanner(id);

Parameters


Name	Type	Description	Required
id	String	System generated unique ID to identify a banner. This `id` parameter is used by the desktop when the banner has to be invoked by a non-gadget client. Gadgets do not send this parameter.	Yes, when invoked by a non-gadget client

hideDialog()

Hides the user interface modal dialog.

Example

Code Snippet

Copyvar containerServices = finesse.containerservices.ContainerServices.init();
containerServices.hideDialog();

hideMyGadget()

Makes the current gadget inaccessible by hiding it from the Multi-Tab gadget header.

Note	This operation has no effect and does not cause any errors when the gadget is not hosted within a Multi-Tab gadget.

Example

Code Snippet

Copyfinesse.containerservices.ContainerServices.hideMyGadget();

hideMyGadgetNotification()

Removes the current gadget's notifications from the Multi-Tab gadget header.

Note	This operation has no effect and does not cause any errors when the gadget is not hosted within a Multi-Tab gadget.

Example

Code Snippet

Copyfinesse.containerservices.ContainerServices.hideMyGadgetNotification();

init()

Initiates the ContainerServices module.

Note	The init method must be called before using the ContainerServices object for invoking any other functionality.

Example

Code Snippet

Copyfinessse.containerServices.ContainerServices.init();

Returns

{finesse.containerServices.ContainerServices} The initiated finesse.containerServices.ContainerServices reference.

isTabbedGadget()

Checks if the gadget is configured inside a multi-tab gadget.

Example

Code Snippet

Copy
containerServices = finesse.containerservices.ContainerServices.init();
containerServices.isTabbedGadget();

Returns

{Boolean} True if the gadget is hosted inside a multi-tab gadget.

makeActiveTabReq()

Requests to activate the tab in which the gadget is present.

Example

Code Snippet

Copyfinesse.containerservices.ContainerServices.makeActiveTabReq();

publish(topic, data)

Publishes data to the specified topic on the OpenAjax hub. Since gadgets reside in different iFrames, message publication is the only way to communicate with each other. This method gives a mechanism for the gadgets to have their data published through custom topics, which in turn can be used by other gadgets by subscribing to the same topic.

For example, OnClick is an element in one gadget which triggers an action in another gadget that is achieved by using this method.

Example

Code Snippet

Copyfinesse.containerservices.ContainerServices.publish('CUSTOMTOPIC', data);
finesse.containerservices.ContainerServices.addHandler("CUSTOMTOPIC", function(data) {
    // Perform the logic
});

Parameters


Name	Type	Description	Required
topic	String	Hub topic that the gadget wants to listen to. For more information on topics, see Container Services Topics.	Yes
data	Object	The data to be published for the specified topic on the OpenAjax hub.	Yes

reloadMyGadget()

Reloads the current gadget. This method is useful when the gadget encounters an error.

Example

Code Snippet

Copyvar containerServices = finesse.containerservices.ContainerServices.init();
containerServices.reloadMyGadget();

reloadMyGadgetFromUrl(url)

Updates the URL for this gadget and reloads the gadget. This method allows the gadget to be reloaded from a different URL which can be useful for third-party gadgets implementing a failover mechanism.

Example

Code Snippet

Copyvar containerServices = finesse.containerservices.ContainerServices.init();
containerServices.reloadMyGadgetFromUrl(url);

Parameters


Name	Type	Description	Required
url	String	The URL that the gadget should reload from.	Yes

removeHandler(topic, callback)

Removes previously added handler for the specified Container Services topic.

Example

Code Snippet

Copyfinesse.containerservices.ContainerServices.removeHandler(finesse.containerservices.ContainerServices.Topics.
TIMER_TICK_EVENT,callback);

Parameters


Name	Type	Description	Required
topic	String	Hub topic that the gadget wants to listen to. For more information on topics, see Container Services Topics.	Yes
callback	Function	An asynchronous callback function to be removed for the specified Container Services topic.	No

setMyGadgetTitle(title)

Sets the title of the current gadget.

Example

Code Snippet

Copyfinesse.containerservices.ContainerServices.setMyGadgetTitle('Recent History');

Parameters


Name	Type	Description	Required
title	String	The title of the current gadget.	Yes

showCertificateBanner(callback)

Displays the Certificate Banner with the message Gadget certificates are yet to be accepted.

Example

Code Snippet

Copy
// For Gadgets 
containerServices = finesse.containerservices.ContainerServices.init();
containerServices.showCertificateBanner(function(){
    // Do something when the banner hides
});

// For non gadget Client , id is required to hide the certificate banner
// which is returned when showCertificateBanner is called
var id = containerServices.showCertificateBanner(function(){
    // Do something when the banner hides
});

Parameters


Name	Type	Description	Required
callback	Function	Callback is invoked when user closes the banner manually.	Yes

Returns

{String} id—System generated unique ID to identify a banner. This id parameter is used by the desktop when the banner has to be invoked by a non-gadget client. Gadgets do not send this parameter.

showDialog(options)

Shows the user interface modal dialog with the specified parameters. The parameters are:

Title of the modal dialog
Message inside the modal dialog
Label for the button to close the modal dialog
If the modal dialog should block other dialogs
If the modal dialog is draggable
If the modal dialog is fixed-size

Note	Custom JavaScript-based modal dialogs and alerts negatively affects the functionality of the Finesse desktop and is not recommended to be used.

Example

Code Snippet

Copyvar containerServices = finesse.containerservices.ContainerServices.init();
containerServices.showDialog({
    title: 'Error Occurred',
    message: 'Something went wrong',
    close: function() {
    }
});

Parameters


Name	Type	Description	Required
title	String	Title of the modal dialog.	Yes
options	Object	Options for the modal dialog. close—Callback function that gets invoked when the close button of the modal dialog is clicked. message—Message to be displayed in the modal dialog. isBlocking—Indicates whether the modal dialog blocks other dialogs from being shown.	Yes

Returns

{Object} The modal dialog object of the modal dialog DOM (Document Object Model) element.

showMyGadget()

If hidden, makes the tab corresponding to this gadget visible in the Multi-Tab gadget.

Note	This operation has no effect and does not cause any errors, when the gadget is not hosted within a Multi-Tab gadget.

Example

Code Snippet

Copyfinesse.containerservices.ContainerServices.showMygadget();

showMyGadgetNotification(messageDetails)

When hosted in a Multi-Tab gadget, a notification will appear on the tab corresponding to this gadget.

Note	This operation has no effect and does not cause any errors, when the gadget is not hosted within a Multi-Tab gadget.

Example

Code Snippet

Copyfinesse.containerservices.ContainerServices.showMyGadgetNotification();

With the parameter

This method shows a visual indication that some new notifications are available in the non-active gadgets. The behavior of the notifications for the non-active gadgets are as follows:


If the navigation pane is not pinned:	Popover notifications are displayed at the top-right corner of the Task window.
If the navigation pane is pinned:	Displays a red dot next to the non-active gadget in the navigation pane.
If the non-active gadget is part of a multi-tab:	A red dot is displayed on top of the non-active gadget inside the multi-tab.

Click on the notified tab or navigation bar to clear the visual indication.

Example:

Code Snippet

Copyfinesse.containerservices.ContainerServices.showMyGadgetNotification(messageDetails);

messageDetails is a method that has the following parameters:

messageFrom, message, isDismissable, timeout, icon, type, pristine

For parameter details see the Notification Popover Service section.

tabVisible()

Retrieves the visibility of the current gadget only after the initialization of the gadget.

Example

Code Snippet

Copyfinesse.containerservices.ContainerServices.tabVisible();

Returns

{Boolean} The visibility of the gadget.