This post was authored by Ina Uzunova, Product Owner of vSphere Client SDK

This blog post gives a brief overview of a new mechanism for JavaScript API bootstrapping introduced in vSphere 6.5 Update 1 and explains why you should take advantage of it.

In previous releases, the JavaScript APIs have been initialized through a custom file web-platform.js that must be included in your HTML plugin resources. Packaging the web-platform.js file in your plugin has two main disadvantages:

• It uses a single shared global object for all plugins. As a result, other plugins that have an older version of that file, and are installed on the same vSphere environment where your plugin is installed, may override the same shared global object. This may impact your plugin’s functionality.
• The file becomes part of your plugin package delivery. If you want to consume the latest bug fixes and improvements to JavaScript APIs provided in the next release, you need to update your copy of the web-platform.js to include these changes and release a new plugin version to your users.

The new JavaScript API bootstrapping mechanism is supported on vSphere 6.5 U1 and future releases. It is not supported on any previous vSphere release.

The mechanism is simple, yet powerful and easy to use. Instead of including the web-platform.js in your plugin package, you can access the same set of JS APIs by a single call:

this.webPlatform = window.parent.vSphereClientSDK.getWebPlatformApi(window);

For each call getWebPlatformApi(window) returns a unique JavaScript object, and you can access all existing JavaScript APIs through this object. For example, to close a dialog box using the new interface object:

this.webPlatform.closeDialog();

The advantages of this new bootstrapping mechanism are:

• You no longer share a global object with other plugins and they cannot impact your plugin’s functionality.
• Since you no longer need to include the web-platform.js file in your plugin package, any bug fixes and improvements to existing JavaScript APIs introduced in the next release, will be available transparently through the JavaScript interface object which you instantiated in your code. The fixes and improvements will be available at the moment the user upgrades to the vSphere release where they are introduced.

For more details please refer to the official documentation and the HTML Client SDK samples available from the \html-client-sdk\samples directory.

This blog gives a detailed overview of all existing vSphere HTML Client SDK 6.5 resources that you can use while developing an HTML plug-in.

Official SDK Release

vSphere HTML Client SDK is independent section of the vSphere Web Client SDK 6.5 deliverable. You can download the official vSphere Web Client SDK 6.5 from VMware code. It also contains references to the vSphere Web Client SDK Release Notes where you can find new vSphere HTML Client SDK features, known and resolved issues for each release.

vSphere HTML Client Documentation for 6.5 release is available in two flavors:

• Online help
• Downloadable pdf file

The vSphere Web Client SDK zip contains a /html-client-sdk/docs directory where JavaScript and Java APIs documentation resides. There you can find information about vSphere HTML Client SDK setup with IntelliJ IDEA and Eclipse IDE, technical frequently asked questions and other info related to plug-in development.

General frequently asked questions are available from here.

To facilitate your vSphere HTML Client plug-in development, VMware UX team introduces UX Design Guidelines for vSphere Client (HTML5) in addition to the already existing design guidelines for the vSphere Flex Client.

Fling SDK Release

The HTML Client SDK Fling builds upon the latest officially released SDK to provide technical preview of newly developed features and to gather and address prompt feedback. The HTML Client SDK Fling build is available from the drop-down menu on the left hand side.

Each SDK Fling release has its own overview and release notes, available from the same drop down menu on the left. In addition, the HTML Client SDK Fling comes with a detailed “Getting Started with HTML Client SDK Fling” guide available from the SDK’s docs directory.

The HTML SDK Fling Release includes also a plug-in generator tool which helps you build HTML plug-ins.

For any questions regarding official or Fling SDK features, you can post a comment at the vSphere Web Client SDK Forum or search for already existing recommendation and guideline on our dedicated HTML Client SDK blog post section.

This post was authored by Ina Uzunova, Product Owner of vSphere Client SDK.

This post was authored by Ina Uzunova, Product Owner of vSphere Client SDK

This blog gives a brief overview of the HTML Client SDK version and plug-ins compatibility. It will answer a common question among plug-in developers: “Which SDK version should I use?”

There are three major variables in the compatibility matrix you need to consider:

• vCenter Server version
• vSphere HTML Client version
• vSphere HTML Client SDK version

vSphere HTML Client is released for the first time in vSphere 6.5 release and its compatibility with vCenter server is officially documented here.

vSphere Web Client SDK 5.1 contained initially Java and Flex libraries, Extension points and tools. JavaScript APIs are released for the first time in the vSphere Web Client SDK 5.5 U1. They have been improved, extended and alongside the existing Java libraries, extension points and tools became an independent section of the vSphere Web Client SDK 6.5 called the vSphere HTML Client SDK 6.5. It lets you build plug-ins which are supported on both the vSphere Client and the Flex-based vSphere Web Client.

SDK Version used to create the HTML plug-in	vSphere Web Client 5.5 U1	vSphere Web Client 6.0	vSphere Web Client 6.5 vSphere Client 6.5
5.5 U1	Yes	Yes	Yes
6.0	No	Yes	Yes
6.5	No	Yes	Yes

Note: To ensure plug-in compatibility you must follow the instructions for upgrading your plug-in.

vSphere Web Client SDK 5.5 U1 has several known limitations and a smaller set of supported JavaScript APIs compared to the vSphere HTML Client SDK 6.5.

Unless you need to support the vSphere Web Client 5.5 U1, we recommend that you use the latest vSphere HTML Client SDK 6.5. It will ensure that your plug-in is compatible with Flex-based vSphere Web Client 6.0, Flex-based vSphere Web Client 6.5 and vSphere Client 6.5, and you can take advantage of all latest APIs, tools and improvements. The differences between vSphere Web Client SDK 6.0 and 6.5 are documented in the vSphere Web Client SDK 6.5 release notes.

For more details please refer to the official documentation.

This post was authored by Laurent Delamare, Staff Engineer at VMware.

This blog gives a brief overview of the HTML Client plugin-seed, a tool available on the vSphere Client Fling page. (Click on the drop down menu and download plugin-seed-<version>.zip, it comes with full documentation.)

In this post we assume that you are familiar with the HTML Client SDK 6.5 and its documentation. If you want to follow the instructions below you must first install the SDK on your Windows or Mac development machine, or install a newer HTML Client SDK Fling (download the file html-client-sdk-6.5.0-<build>.zip) which is a preview of things to come.

Introduction

The HTML Client plugin-seed is the best way to create vSphere Client plugins based on a modern tech stack and robust patterns. It includes a fast development process which will let you expand the initial plugin skeleton into your own version with great productivity.

• It is based on the HTML Client SDK 6.5, so the generated plugins are compatible with both the HTML Client, version 6.5, and the Web Client, versions 6.0 or 6.5 (Flash-based). Plugin-seed doesn’t add any SDK API, it uses the SDK as-is and offers utilities that are not part of the SDK.
• The UI layer is based on the Clarity Design System, a VMware open-source project which consists of UX guidelines, HTML/CSS framework, and Angular components. Using Clarity will also ensure consistency of your plugin UI with the rest of the vSphere Client.
• It uses the latest Angular framework and the Typescript language which have become industry standards for enterprise applications on the web.
• It generates plugins as Angular-CLI projects. It includes utilities and development tools that will speed up your dev cycles, help you design a good architecture, and set you up for proper testing.

Creating and running your first plugin in minutes

You create a plugin with the following command line, which will prompt you for a plugin name, a plugin directory, and a package name:

./plugin-seed/tools/generate-plugin.[bat, sh]

For instance, if you use the default name myplugin, the script creates two directories, myplugin-ui and myplugin-service, containing the UI component (which runs in the browser) and service component (which runs in the Virgo server).

The UI component, myplugin-ui, is a web app that you can instantaneously run in “dev mode” in your browser:

1. As a prerequisite, you need to install the following tools:
   • Node.js version 6.9 or higher
   • Angular-CLI (npm install -g @angular/cli)
   • Json-server (npm install -g json-server)
2. Go to myplugin-ui root directory:
   cd myplugin-ui
3. Install the Javascript dependencies (one time operation):
   npm install
4. Start json-server in a separate terminal (it is used to serve mock data):
   json-server --watch db.json --static ./src/webapp
   (or npm run json-server)
5. Start the application in standalone dev mode with:
   npm start
6. Point your browser to http://localhost:4201/ and see the initial plugin UI!

Plugin Dev Mode overview

The plugin application home page is made of an application header, a navigator on the left and a main view in the center. Only the main view contains the plugin content, the header and navigator are extra dev UI components:

The generated plugin includes the three types of views that can extend the vSphere Client UI:

1. Global view, one that is not attached to a particular object context in the left navigator.
2. Object view, included into a specific object workspace (Summary, Monitor, Configure).
3. Modal view, used in response to actions, such as wizards, one-page dialogs, etc.

It demonstrates how to use mock data for vSphere objects (e.g. Hosts) or custom objects (e.g. Chassis).

Clicking on a Host on the left navigates to the object’s Summary, Monitor, and Configure views:

You can hide all dev UI by clicking on the top left (X) icon:

This shows the Monitor view without the “dev UI”, the way it will be displayed inside the vSphere Client:

Fast Development Cycle

Thanks to this dev mode approach you end up building your plugin UI as a standalone web application first, without involving the vSphere Client. This has many advantages:

• You focus on the UI components and treat all views in a single page app without being encumbered with the vSphere Client environment.
• The dev cycle is really fast: build quickly, prototype quickly, test quickly, and quickly fix any errors along the way!
• You can use mock data easily to separate UI development and testing from backend services.
• The “live data” mode allows to test the UI with your production backend.
• End-to-end testing is simpler.
• You may convert your plugin into another app later if necessary.

The next step is to modify and expand the plugin to match your actual use cases. For instance you may remove all chassis-related code (which demonstrates custom objects) and may want to create new views to extend the vSphere Client UI for virtual machines instead of hosts.

Because it is an Angular-CLI project, you can take advantage of the CLI commands to generate new components, directives, services, etc. You can also copy and modify the default plugin code which already contains many interesting patterns.

All your UI development can be done in an interactive manner while the app is rebuilding automatically after each change and refreshing in the browser (thanks to npm start), and while unit tests keep running in a separate terminal (using ng test).

Live Data Mode

Mock data is nice to start prototyping fast but at some point you also want to test with real data coming from backend services running in your local Virgo setup. This is possible with the Live data switch in the header! Using a simple setup described in the plugin-seed documentation, you can get the best of both worlds.

Plugin Mode

At any moment you can run the same code in “Plugin Mode”: Plugin Mode means deploying and testing your plugin with the vSphere Client. The same application is running inside each view which makes up your plugin. Instead of being one integrated app, your plugin views are accessible in each “extension” that you have declared in plugin.xml.

For instance:

1. One global view extension as the main view.
2. One global view extension as the settings view, in the client’s Administration area.
3. One object view extension as the Monitor sub-tab for Hosts.
4. One modal dialog for a menu action extension.

The view routing and how it applies to extensions in plugin.xml is described in more detail in the plugin-seed documentation, but you can see in the screenshots below that the plugin UI is automatically removed from any Dev Mode component. For a more info on SDK extensions in general see this doc.

The other difference with Dev Mode is that data access and service calls made from the UI go directly to back-end services instead of using the mock data server. (This is the same as the Live Mode available in the standalone app).

Fast Development in both Dev Mode and Plugin Mode!

Once you have deployed your plugin with your local vSphere Client server you can take advantage of both environments to keep developing and testing your plugin. All you need to do is keep the standalone app running with <code>npm start</code> on one hand, and to use the <code>gulp watch</code> script to refresh the plugin code on the Virgo server on the other hand: each code change will now be reflected both in dev mode and in the vSphere Client once you refresh the view.

Testing and packaging your plugin for production

Plugin-seed comes with many Jasmine unit tests that you can expand as you add code. Angular / Typescript tests are easy to write once you have a model to get started. End-to-end testing is done using Protractor.

Running the command ng test --code-coverage automatically generates test coverage information, which provides a nice HTML interface where you can drill down into directories and files to see details down to the source lines.

A plugin built with plugin-seed is packaged the same way other plugins are, please see Creating and Deploying Plug-In Packages in the HTML Client SDK 6.5 documentation.

There are several ways to optimize your Angular application for production:

• Use ng build --prod --aot to build production code and use Angular’s AOT compiler for smaller bundle size and faster runtime.
• Consider lazy loading components if you feel the loading performance should still be improved after using --aot. Plugin-seed includes such an example with the Settings view. The idea is to give the router a simple path to your lazy loaded modules, instead of a direct reference that would bring in all the code during the build. This way the module code is only loaded when you navigate to that particular view.

Other features of plugin-seed

Plugin-seed contains many other features or patterns that we don’t have time to cover here:

• The app-alert.component for standard use notifications.
• The common AppErrorHandler.
• The RefreshService using Rxjs Observables to propagate a global refresh.
• The i18nService to localize your UI in various languages
• The NavService which encapsulates navigation actions between views.
• The initialization of a global webPlatform object (no need to use web-platform.js anymore).
• The WebPlatform interface containing the SDK apis in a typescript format.
• The injection of modal components in a reusable DialogBoxComponent.

Conclusion

Although it is entirely possible to develop vSphere Client plugins with other UI stacks, and without the hybrid mode approach, we hope that after trying out plugin-seed for a short time you will appreciate what this stack and this development mode can bring you. Happy plugin writing!