vSphere HTML Client SDK - Javascript API for local plug-ins

  1. Overview
  2. Client Application APIs
  3. Event APIs
  4. Modal APIs

1. Overview

The vSphere HTML Client SDK offers a set of JavaScript APIs which facilitate the building of HTML Client-only plugins, fully compatible with the HTML-based vSphere Client. These JavaScript APIs are documented here as if they have TypeScript signatures, but they run as pure JavaScript, and all complex types are plain old Javascript objects. The JavaScript APIs may be used by the plugin to communicate with the HTML Client and to execute a number of operations. Each plugin will have access to the JavaScript APIs within its own iframe which eliminates the possibility of plugin conflicts. Please refer to the Plug-in Architecture Diagram in the online vSphere Client SDK documentation.
WARNING: Do not access the window.parent (the Client window), as this is unsupported and if your plugin relies on this it might break in a future release of the vSphere Client.

API Namespaces

The JavaScript APIs are organized in several domains depending on their functionality. This improves readability and communicates clearly the API functionality scope:

API Accessibility

The JavaScript APIs can be accessed by getting the API object directly from the extension's iframe, such as: window.frameElement.htmlClientSdk

Note: For practical examples on how to use the JS APIs for local plugins, see the "html-sample" plugin. In order to make the following examples more readable, we will use a shortcut for the JS API object, namely "htmlClientSdk" which will be equal to "window.frameElement.htmlClientSdk".

2. Client Application APIs

The client application APIs are related to the HTML Client application. The client application APIs can be accessed with the htmlClientSdk.app.{API}

APIsDescriptionExample usage
getContextObjects() => any[] Returns current context objects:
  • In global views the result is empty because global views are not associated with any vSphere object.
  • In views that are associated with a particular vSphere object the result contains a JavaScript object with a field named 'id' - the ID of the selected vSphere object.
  • In modals opened through a SDK call to htmlClientSdk.modal.open(configObj) the result is the value of configObj.contextObjects or an empty array if configObj.contextObjects is undefined.
  • In modals opened through actions defined in the plugin.xml file the result is an array of context objects representing the targets of the invoked action. Each context object is a JavaScript object that contains a field named 'id' which is the id of the corresponding target object.
    Note: the result will be an empty array if there are no target objects.
htmlClientSdk.app.getContextObjects();

 for example: [ { id: "urn:vmomi:Datacenter:datacenter-1" } ]
navigateTo(configObj: NavigationOptions) => void Navigates to a specified view with an optional custom data which will be passed to the view. If just objectId is passed, then the default object view will be displayed.
The configuration object should contain the following information:

interface NavigationOptions {
 targetViewId?: string;
 objectId?: string;
 customData?: any;
}

Where:
  • targetViewId - ID of the destination view.
  • objectId - ID of any object associated with the view. (For a global view, this field is not required.)
  • customData - A custom data structure passed to the view.

When navigating to a global view, the "objectId" property can be skipped. 		htmlClientSdk.app.navigateTo({
 targetViewId: "acme-plugin-monitor-view",
 objectId: "urn:vmomi:Datacenter:datacenter-1",
 customData: {name: "test", filter: true}
});
navigateToRemotePluginView(configObj: RemotePluginViewNavigationOptions) => void Navigates to the specified view defined by a remote plugin with an optional custom data which will be passed to the view. The valid values for the targetViewId parameter are the ones returned by the htmlClientSdk.app.getRemotePluginNavigationMap() call for the given plugin.
The configuration object should contain the following information:

interface RemotePluginViewNavigationOptions {
 pluginId: string;
 targetViewId: string;
 vcGuid: string;
 objectId?: string;
 customData?: any;
}

Where:
  • pluginId - the ID of the plugin that contains the destination view.
  • targetViewId - the navigation ID of the destination view.
  • vcGuid - the GUID of the vCenter Server in the context of which the target view is to be shown. Determines the specific plugin server instance from which to load the destination view. If the objectId field is specified then the object it refers to should be managed by the vCenter server specified by the vcGuid field value.
  • objectId - ID of any object associated with the view. (For a global view, this field is not required.)
  • customData - A custom data structure passed to the view.

Note: When navigating to a global view, the objectId property should be skipped. 		htmlClientSdk.app.navigateToRemotePluginView({
 pluginId: "acme-plugin",
 targetViewId: "acme-plugin-monitor-view",
 vcGuid: "vc-guid-0",
 objectId: "urn:vmomi:Datacenter:datacenter-1:vc-guid-0",
 customData: {name: "test", filter: true}
});
getNavigationData() => any Retrieves the navigation data passed to the current view by the navigateTo() API.
If the following is called:

htmlClientSdk.app.navigateTo({
 targetViewId: "acme-plugin-monitor-view",
 objectId: "urn:vmomi:Datacenter:datacenter-1",
 customData: {name: "test", filter: true}
});

Then, any call to:
htmlClientSdk.app.getNavigationData();

will return: {name: "test", filter: true}
getClientInfo() => ClientInfo Returns information about the current vSphere Client, such as "version", "type" etc.

interface ClientInfo {
 type?: string;
 version?: string;
}

Where:
  • type - The vSphere Client type.
  • version - The vSphere Client version.
 htmlClientSdk.app.getClientInfo();

 for example: {type: "HTML", version: "6.5.1"}
getClientLocale() => string Returns the current locale of the vSphere Client. htmlClientSdk.app.getClientLocale();

 for example: "de-DE"
getTheme() => PluginTheme Returns information about the theme the plugin should use. The returned PluginTheme type is defined as follows:

interface PluginTheme {
 name: "light" | "dark"
} 		htmlClientSdk.app.getTheme();

 for example: { name: "dark" }
formatDateTime(instant: number,
  options?: PluginDateTimeFormatOptions) => string		 Formats the specified date-time instant using the provided options.
Returns a string which represents the formatted date.

The instant should be a Unix Time Stamp, an integer value that is the number of milliseconds since 1 January 1970 UTC.

PluginDateTimeFormatOptions type is defined as follows:

interface PluginDateTimeFormatOptions {
 format?: "DATE" | "TIME" | "DATE_AND_TIME";
}

Where:
  • format - Specifies the date-time format. The possible options are:
    • "DATE" - output only the date part of the date-time value in the formatted string, e.g. "05/13/2019"
    • "TIME" - output only the time part of the date-time value in the formatted string, e.g. "11:22:48 AM"
    • "DATE_AND_TIME" - output both the date and the time of the date-time value in the formatted string, e.g. "05/13/2019, 11:22:48 AM"
    If the field's value is not specified then "DATE_AND_TIME" will be used as the default value.
 htmlClientSdk.app.formatDateTime(1557735887313);
Returns: "05/13/2019, 11:24:47 AM"

htmlClientSdk.app.formatDateTime(1557735887313, {format: "DATE"});
Returns: "05/13/2019"

htmlClientSdk.app.formatDateTime(1557735887313, {format: "TIME"});
Returns: "11:24:47 AM"

htmlClientSdk.app.formatDateTime(1557735887313, {format: "DATE_AND_TIME"});
Returns: "05/13/2019, 11:24:47 AM"
getRemotePluginNavigationMap(targetPluginId: string, callback: ((navigationInfo: RemotePluginNavigationMap | null) => void)) => void Retrieves a navigation map that contains the public views' navigation IDs of the target remote plugin per vCenter Server. The result will contain information about all vCenter Servers with which an enabled version of the target remote plugin is registered.

Parameters:
  • targetPluginId - the target remote plugin ID
  • callback - a function that will be invoked with the result map after it has been retrieved. In case of an exception in the backend call, the result map will be null.


RemotePluginNavigationMap type is defined as follows:

interface RemotePluginNavigationMap {

 // A map of vCenter Server GUID to the relevant remote plugin navigation information about that vCenter Server.
 navigationInfoByVcGuid: { [vcGuid: string]: RemotePluginVcNavigationInfo };
}

RemotePluginVcNavigationInfo type is defined as follows:

interface RemotePluginVcNavigationInfo {

 // The remote plugin version registered with the particular vCenter Server.
 pluginVersion: string;

 // The particular remote plugin version views' navigation IDs.
 viewsIds: string[];
} 		Consider that a remote plugin with ID com.acme.remote has a single registration within the environment. The registration is done on vCenter with GUID vc-guid-0 for plugin instance with version 1.0.0.0. Also consider that the plugin has a single public view within Host -> Monitor with navigationId mon.

Then the following API invocation:

htmlClientSdk.app.getRemotePluginNavigationMap("com.acme.remote", function(map) {
 console.log(map);
});

would yield the following result:
{
 navigationInfoByVcGuid: {
  vc-guid-0: {
   pluginVersion: "1.0.0.0",
   viewsIds: ["mon"]
  }
 }
}

3. Event APIs

The event APIs provide means for plugins to subscribe and respond to events. These APIs can be accessed via htmlClientSdk.event.{API}

APIDescriptionExample usage
onGlobalRefresh(callback: () => void) => void Subscribes to a global refresh event and when such an event occurs, the callback function will be executed. function updateData() {
  alert("Data is updated after a global refresh.");
}

htmlClientSdk.event.onGlobalRefresh(updateData);
onThemeChanged((theme: PluginTheme) => void) => void Subscribes for plugin theme changed events. When such an event occurs, the callback argument function will be invoked with a single argument - the new plugin theme in the form of PluginTheme object.

The PluginTheme type is defined as follows:

interface PluginTheme {
 name: "light" | "dark";
}
function showCurrentThemeName(theme) {
 alert(theme.name);
}

htmlClientSdk.event.onThemeChanged(showCurrentThemeName);
onDateTimeFormatChanged(callback: () => void) => void Subscribes to date-time format change events. When the date-time format changes, the provided callback function will be invoked without arguments.
function onTimeFormatPreferencesChange() {
 alert("The time format preferences have changed.");
}

htmlClientSdk.event.onDateTimeFormatChanged(onTimeFormatPreferencesChange);

4. Modal APIs

The modal APIs are used to perform various actions for a modal dialog such as open, close and configure. The modal APIs can be accessed with the htmlClientSdk.modal.{API}

APIDescriptionExample usage
open(configObj: ModalConfig) => void Opens a modal dialog and accepts for parameter a configuration object, which contains:

interface ModalConfig {
 url: string;
 title?: string;
 accessibilityTitle?: string;
 size?: {
  width: number,
  height: number
 };
 closable?: boolean;
 onClosed?: (result?: any) => void;
 contextObjects?: any[];
 customData?: any;
}

Where:
  • url - Location of HTML content for the dialog.
  • title - Dialog title.
  • accessibilityTitle - Dialog accessible title.
  • size - Dialog size. Specified in pixels.
  • closable - Whether the dialog displays a close button. (default=true)
  • onClosed - Function runs when the dialog closes.
  • customData - Data the calling module passes to the dialog.
  • contextObjects - IDs of relevant objects the calling module passes to the dialog.
var config = {
 url: "resources/editDatacenter.html",
 title: "Edit Datacenter",
 accessibilityTitle: "Edit Datacenter",
 size: {
  width: 490,
  height: 240
 },
 onClosed: function(id) { alert("Modal " + id + " closed."); },
 contextObjects: [{ id: "urn:vmomi:Datacenter:datacenter-1" },
    { id: "urn:vmomi:Datacenter:datacenter-2" }],
 customData: {idsRange: [1, 9]}
 };

htmlClientSdk.modal.open(config);
openConfirmationModal(configObj: ConfirmationModalConfig) => void Opens a simplified modal dialog dedicated to showing confirmation messages. The API offers:

interface ConfirmationModalConfig {
 content: string;
 buttons: ModalButton[];
 size?: ModalSize;
 alertLevel?: AlertLevel;
 title?: string;
 accessibilityTitle?: string;
 secondaryTitle?: string;
 closable?: boolean;
 onClosed?: () => void;
}

interface ModalSize {
 width: number;
}

interface ModalButton {
 label: string;
 type?: ButtonType;
 style?: ButtonStyle;
 callback?: () => void;
}

enum ButtonType {
 PRIMARY = "PRIMARY",
 SECONDARY = "SECONDARY"
}

enum ButtonStyle {
 SUCCESS = "SUCCESS",
 INFO = "INFO",
 WARNING = "WARNING",
 DANGER = "DANGER"
}

enum AlertLevel {
 SUCCESS = "SUCCESS",
 INFO = "INFO",
 WARNING = "WARNING",
 DANGER = "DANGER"
}

Where:
  • content - The message to be displayed in the modal dialog.
  • buttons - An array of buttons to be displayed in the modal footer. The limit is at least 1 button and at most 4 buttons.
  • size - Dialog size. In the current version only width is accepted. Specified in pixels.
  • alertLevel - Dialog alert level. It results in a SUCCESS, INFO, WARNING, or DANGER icons.
  • title - Dialog primary title.
  • accessibilityTitle - Dialog accessibility title.
  • secondaryTitle - Dialog secondary title. For example, it can be the name of the object
    which the action will be performed on.
  • closable - Whether the dialog displays a close button. Enabled by default.
  • onClosed - Callback to be invoked when the dialog is closed by X button, or ESC key.
var confirmationModalConfig = {
 content: "Deleting a chassis can cause failures in your environment?",
 size: {
  width: 490
 },
 alertLevel: "DANGER",
 title: "Delete chassis.",
 accessibilityTitle: "Delete chassis. Chassis-1",
 secondaryTitle: "Chassis-1",
 buttons: [{
    label: "DELETE",
    callback: () => {//some delete callback actions} },
    label: "CANCEL",
    callback: () => {//some cancel callback actions} }],
 closable: false,
 onClosed: function() {//Default onClosed handler. Invoked on ESC / X button press}
 };

htmlClientSdk.modal.openConfirmationModal(confirmationModalConfig);
close(data?: any) => void Closes the already opened modal. The modal is the one corresponding to the iframe from which this API was called from.
If data has been provided it will be passed to the onClose callback function if such was specified in the parameter of the modal.open API. 		var modalId = 2;
htmlClientSdk.modal.close(modalId);
setOptions(configObj: DynamicModalConfig) => void Changes the configuration of the modal with properties specified in the parameter object.
The configObj type is defined as follows:

interface DynamicModalConfig {
 title?: string;
 accessibilityTitle?: string;
 height?: number;
}

Where:
  • title - Dialog title.
  • accessibilityTitle - Dialog accessibility title.
  • height - Dialog height. Specified in pixels.
 htmlClientSdk.modal.setOptions({
 title: "New Title",
 accessibilityTitle: "New Accessibility Title",
 height: 450
});
getCustomData() => any Returns the custom data that was provided upon opening the modal through customData property or null if the customData property was not set. htmlClientSdk.modal.getCustomData();

 for example: {idsRange: [1, 9]}