Migration To The New JavaScript API

  1. Overview
  2. Methods Migration
  3. Unsupported Methods
  4. Migration Tool

1. Overview

The new JavaScript API, first released in 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 depraceted at some point.

2. 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 APIJavaScript 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.modal.setOptions({
 title: "New Modal Title"
}));
getObjectId()

Example:

WEB_PLATFORM.getObjectId(); 		getContextObjects() => any[]

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

2.2 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:

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

4. 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_PLATFORM object.
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:

The Migration Tool supports two migration modes: