vSphere HTML Client SDK - Javascript API

  1. Overview
  2. Modal APIs
  3. Client Application APIs
  4. Event 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

Local Plugins

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 "htmlSdk" which will be equal to "window.frameElement.htmlClientSdk".

Remote Plugins

Remote plugins keep for the most part the frontend APIs that were shipped in the previous release.
In order to isolate plugins a new asynchronous way for communicating with the parent window was introduced, namely the plugin communicates with the vSphere Client with a window.postMessage mechanism.
Client Library was introduced to abstract plugin writers from this new mechanism. The Client Library exposes the Frontend APIs in a standard manner, and hides the complexity associated with asynchronious programming.
The Client Library is not bundled with plugins and is dynamically loaded through a well known location. This approach allows for transparent bug fixes and new APIs to be delivered in future vSphere Client releases.

WARNING: Do not reverse engineer the Client Library and do not use anything not provided by the APIs. Doing this might break your plugin in future vSphere Client releases.

The JavaScript APIs can be accessed by including the "/api/ui/htmlClientSdk.js" source. For example: <script src="/api/ui/htmlClientSdk.js"/>.
Once the htmlClientSdk.js source is included, the htmlClientSdk object is created in the iframe's window which has two functions:


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

2. 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 htmlSdk.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;
 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.
  • 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",
 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]}
 };

htmlSdk.modal.open(config);
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;
htmlSdk.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;
 height?: number;
}

Where:
  • title - Dialog title.
  • height - Dialog height. Specified in pixels.
 htmlSdk.modal.setOptions({
 title: "New 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. htmlSdk.modal.getCustomData();

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

3. Client Application APIs

The client application APIs are related to the HTML Client application. The client application APIs can be accessed with the htmlSdk.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 htmlSdk.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.
htmlSdk.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.
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.

Note: For Remote plugins the navigateTo API can be called with the targetViewId parameter only if the view is defined by the plugin itself, otherwise only the objectId parameter can be used to navigate to a specific object. This means that the the navigation to a cluster monitor view will not work if the view is not defined in the plugin.json of the plugin. 		htmlSdk.app.navigateTo({
 targetViewId: "acme-plugin-monitor-view",
 objectId: "urn:vmomi:Datacenter:datacenter-1",
 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:

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

Then, any call to:
htmlSdk.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.
 htmlSdk.app.getClientInfo();

 for example: {type: "HTML", version: "6.5.1"}
getClientLocale() => string Returns the current locale of the vSphere Client. htmlSdk.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"
} 		htmlSdk.app.getTheme();

 for example: { name: "dark" }
getSessionInfo(callback: (info: SessionInfo) => void) => void

(*) 		Retrieves information about the current session.
Where the info object has the following type:

interface SessionInfo {
 sessionToken: string;
}

Where:
  • sessionToken - The dedicated plugin session identifier, which can be used for vCenter Server authentication.
 htmlSdk.app.getSessionInfo(
 (sessionInfo) => {
  console.log(sessionInfo.sessionToken);
 })

 for example: "8df9ac8f-7a3c-46d0-ab8d-89f9bf2918d9"

getApiEndpoints() => ApiEndpoints

(*) 		Returns an object containing the base locations of vSphere Client plugin related APIs.
The returned object is of type ApiEndpoints, where:

interface ApiEndpoints {
 uiApiEndpoint: UiApiEndpoint;
}

interface UiApiEndpoint {
 origin: string;
 pathname: string;
 queryParams: Array<QueryParam>;
 fullUrl: string;
}

Where:
  • origin - Protocol, hostname and port number of the APIs host URL. The format is <protocol>://<hostname>:<port> for example: http://localhost:1111 .
  • pathname - Path to the APIs.
  • queryParams - Additional parameters are included.
  • fullUrl - Composition of the previous as: <origin><pathname>(?<serializedQueryParams>).

interface QueryParam {  
 name: string;  
 value: string;
} 		htmlSdk.app.getApiEndpoints();

 for example:
 {
   uiApiEndpoint: {
    origin: "https://hostname",
    pathname: "apiPath",
    queryParams: [{ name: "percentage?", value: "100%" }, { name: "color", value: "blue" }],
    fullUrl: "https://hostname/apiPath?percentage%3F=100%25&color=blue"
   }
 }


(*) Note: These APIs are applicable only for remote plugins

4. Event APIs

The event APIs provide means for plugins to subscribe and respond to events. These APIs can be accessed via htmlSdk.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.");
}

htmlSdk.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);
}

htmlSdk.event.onThemeChanged(showCurrentThemeName);