HTML Client Plugin Seed: A Fast and Easy Path to Great vSphere Client Plugins!

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!