JavaScript API Migration Guide

Overview

The new JavaScript API, first released in vSphere 6.5 Update 2, is easier to use than the existing HTML Bridge API and can achieve better flexibility. Considering that the JavaScript API methods are extensible, impact on plug-ins during vSphere Client upgrades is minimal. Have in mind that new functionality will be added only to the new JavaScript APIs which are compatible with the new Remote Plugin Architecture. In addition the HTML Bridge APIs are going to be deprecated at some point.

Methods Migration

The following table represent the methods transition from Bridge API to JavaScript API. Many methods used in the HTML Bridge API have a close equivalent in the new JavaScript API. The methods in this section can generally be converted by using the Migration Tool. See Unsupported Methods for an advice about how to convert methods without an equivalent in the new JavaScript API.

Bridge API	JavaScript API
`openModalDialog(title, url, width, height, objectId)` Example: `WEB_PLATFORM.openModalDialog("Modal Title", "resources/modal.html", 400, 350, "object-id")`	`open(configObj: ModalConfig) => void` Example: `htmlClientSdk.modal.open({ url: "resources/modal.html", title: "Modal Title", size: { width: 400, height: 350}, contextObjects: ["object-i"] });`
`closeDialog()` Example: `WEB_PLATFORM.closeDialog();`	`close(data?: any) => void` Example: `htmlClientSdk.modal.close();`
`setDialogSize(width, height)` Example: `WEB_PLATFORM.setDialogSize(500, 300);`	`setOptions(configObj: DynamicModalConfig) => void` Example: `htmlClientSdk.modal.setOptions({ height: 300 }));`
`setDialogTitle(title)` Example: `WEB_PLATFORM.setDialogTitle("New Modal Title")`	`setOptions(configObj: DynamicModalConfig) => void` Example: `htmlClientSdk.app.getContextObjects()[0].id;`
`sendNavigationRequest(extensionId, objectId)` Example: `WEB_PLATFORM.sendNavigationRequest("target-view-id", "object-id");`	`navigateTo(configObj: NavigationOptions) => void` Example: `htmlClientSdk.app.navigateTo({ targetViewId: "target-view-id", objectId: "object-id" });`
`getClientType()` Example: `WEB_PLATFORM.getClientType();`	`getClientInfo() => ClientInfo` Example: `htmlClientSdk.app.getClientInfo().type;`
`getClientVersion()` Example: `WEB_PLATFORM.getClientVersion();`	`getClientInfo() => ClientInfo` Example: `htmlClientSdk.app.getClientInfo().version;`
`getLocale()` Example: `WEB_PLATFORM.getLocale();`	`getClientLocale() => string` Example: `htmlClientSdk.app.getClientLocale();`
`getActionTargets()` Example: `WEB_PLATFORM.getActionTargets();`	`getContextObjects() => any[]` Example: `htmlClientSdk.app.getContextObjects() .map((obj) => { return obj.id; });`
`setGlobalRefreshHandler(callback)` Example: `WEB_PLATFORM.setGlobalRefreshHandler(() => { console.log("vSphere Rocks") });`	`onGlobalRefresh(callback: () => void) => void` Example: `htmlClientSdk.event.onGlobalRefresh(() => { console.log("vSphere Rocks") });`

Bridge API

JavaScript API

openModalDialog(title, url, width, height, objectId)

Example:

WEB_PLATFORM.openModalDialog("Modal Title",     "resources/modal.html", 400, 350, "object-id")

open(configObj: ModalConfig) => void

Example:

htmlClientSdk.modal.open({           
    url: "resources/modal.html",              title: "Modal Title", 
   size: { 
      width: 400,
      height: 350}, 
   contextObjects: ["object-i"]          });

closeDialog()

Example:

WEB_PLATFORM.closeDialog();

close(data?: any) => void

Example:

htmlClientSdk.modal.close();

setDialogSize(width, height)

Example:

WEB_PLATFORM.setDialogSize(500, 300);

setOptions(configObj: DynamicModalConfig) => void

Example:

htmlClientSdk.modal.setOptions({
 height: 300
}));

setDialogTitle(title)

Example:

WEB_PLATFORM.setDialogTitle("New Modal Title")

setOptions(configObj: DynamicModalConfig) => void

Example:

htmlClientSdk.app.getContextObjects()[0].id;

sendNavigationRequest(extensionId, objectId)

Example:

WEB_PLATFORM.sendNavigationRequest("target-view-id", "object-id");

navigateTo(configObj: NavigationOptions) => void

Example:

htmlClientSdk.app.navigateTo({
 targetViewId: "target-view-id",
 objectId: "object-id"
});

getClientType()

Example:

WEB_PLATFORM.getClientType();

getClientInfo() => ClientInfo

Example:

htmlClientSdk.app.getClientInfo().type;

getClientVersion()

Example:

WEB_PLATFORM.getClientVersion();

getClientInfo() => ClientInfo

Example:

htmlClientSdk.app.getClientInfo().version;

getLocale()

Example:

WEB_PLATFORM.getLocale();

getClientLocale() => string

Example:

htmlClientSdk.app.getClientLocale();

getActionTargets()

Example:

WEB_PLATFORM.getActionTargets();

getContextObjects() => any[]

Example:

htmlClientSdk.app.getContextObjects()
 .map((obj) => {
  return obj.id;
 });

setGlobalRefreshHandler(callback)

Example:

WEB_PLATFORM.setGlobalRefreshHandler(() => {
  console.log("vSphere Rocks")
 });

onGlobalRefresh(callback: () => void) => void

Example:

htmlClientSdk.event.onGlobalRefresh(() => {
  console.log("vSphere Rocks")
 });

Extensions Migration

In the process of migrating to the new JavaScript API, there are also few transformations which must be done in the plugin manifest file ( plugin.xml ).The transformations are only actions related.

Each occurrence of <className>com.vmware.vsphere.client.htmlbridge.HtmlActionDelegate</className>must be replaced either with:

for modal action - <className>com.vmware.vsphere.client.HtmlPluginModalAction</className>
for headless action - <className>com.vmware.vsphere.client.HtmlPluginHeadlessAction</className>

Unsupported Methods

You need to accomplish these HTML Bridge API calls in other ways. See the alternative suggestions in the table.

Bridge API	Alternative
`getRootPath`	Use relative paths.
`getString`	Use `getClientLocale` to get the current locale and localize accordingly.
`callActionsController`	Send the get/post requests directly.
`getActionUid`	Send the get/post requests directly.
`getURLParameter`	The `getURLParameter` API is not secure. The `getLocale`, `getContextObjects` methods can be used to achieve the same result.
`buildDataUrl`	The URL can be built without using this function.
`getVcSelectorInfo`	The vCenter Selector Information can be retrieved with the vSphere Client SDK Java API.
`getUserSession`	The User Session Information can be retrieved with the vSphere Client SDK Java API.
`sendModelChangeEvent`	With the new architecture and new APIs the sendModelChangeEvent API is no longer relevant.

Migration Tool

The Migration Tool is an automated way to migrate Bridge API calls to JavaScript API equivalents.

A Bridge API call is detected by looking at the calls done on the WEB_PLATFORMobject. Each detected HTML Bridge API call is replaced with an equivalent JavaScript API if an equivalent exists. If an equivalent JavaScript API does not exist a warning is logged, these method calls need to be replaced with custom substitutions. The Migration Tool works with directories, trawling for API calls in subsequent source code files. The supported file extensions are: .ts, .js, .html, plugin.xml.

For cleaner migration the Migration Tool creates copies for the replacement, and the source files remain unmodified.

The Migration Tool and its documentation are located inside the tools directory of the vSphere Client SDK deliverable.

The Migration Tool is a TypeScript based project. The tool is command line interface and is executed using the npm command. The prerequisites for using the Migration Tool are:

node.js version >= 8.9
The Migration tool needs to be built before usage by installing dependent packages used by the tool, using npm install

The Migration Tool supports two migration modes:

AUTOMATIC. Automatically migrates your project to a new one in which all calls to the bridge APIs are replaced with calls to the new JavaScript APIs.

Note:
The plug-in manifest file structure is also migrated.
MANUAL. Generates a migration patch file where all calls to the bridge APIs are replaced with calls to the new JavaScript APIs.

This file can be manually edited to select a subset of the changes to be applied.

Apply the changes from the generated and potentially edited migration patch file.

Plugin manifest file changes are also part of the migration patch file.