[Engine-devel] UI plugins crash course (for plugin developers)

Mon Nov 19 14:29:24 UTC 2012

Hi guys,

Oved asked me how to get started with writing UI plugins, and I thought I'd post a quick "crash course" for writing simple UI plugin here.

Level 1 - Plugin basics
=======================

1. Sync with upstream git repository and apply recent UI plugin patches (rev.6 and rev.7)
$ cd <OVIRT_HOME>
$ git fetch && git rebase origin
$ git fetch git://gerrit.ovirt.org/ovirt-engine refs/changes/20/8120/4 && git checkout FETCH_HEAD
$ git fetch git://gerrit.ovirt.org/ovirt-engine refs/changes/50/9250/2 && git checkout FETCH_HEAD

2. Verify your default (machine-specific) Engine configuration - do this if /usr/share/ovirt-engine/conf doesn't exist yet:
$ mkdir -p /usr/share/ovirt-engine/conf
$ cp <OVIRT_HOME>/backend/manager/conf/engine.conf.defaults /usr/share/ovirt-engine/conf/engine.conf.defaults

3. Create plugin descriptor
$ mkdir /usr/share/ovirt-engine/ui-plugins
$ vim /usr/share/ovirt-engine/ui-plugins/hello-ui-world.json

[hello-world.json]
{
  "name": "HelloWorldPlugin",
  "url": "/webadmin/webadmin/plugin/HelloWorldPlugin/start.html",
  "resourcePath": "hello-world-files"
}
[/hello-ui-world.json]

4. Create plugin host page
$ mkdir /usr/share/ovirt-engine/ui-plugins/hello-world-files
$ vim /usr/share/ovirt-engine/ui-plugins/hello-world-files/start.html

[start.html]
<!DOCTYPE html><html><head>
<script type='text/javascript'>
  var api = parent.pluginApi('HelloWorldPlugin');
  api.register({
    UiInit: function() {
      window.alert('Hello World!');
    }
  });
  api.ready();
</script>
</head><body></body></html>
[/start.html]

5. See plugin in action by logging into WebAdmin, you should see following message in Engine log:
... Reading UI plugin descriptor [/usr/share/ovirt-engine/ui-plugins/hello-ui-world.json]

Level 2 - Using plugin API
==========================

6. Add custom main tab that shows content of the given URL

[start.html]
...
api.register({
  UiInit: function() {
    api.addMainTab('Test Tab', 'test-tab', 'http://www.example.com/');
  }
});
...
[/start.html]

7. Update main tab content URL

[start.html]
...
# Anywhere within event handler function code (e.g. UiInit)
api.setMainTabContentUrl('test-tab', 'http://www.another-example.com/');
...
[/start.html]

8. Add custom context-sensitive button to existing main tab

[start.html]
...
api.register({
  UiInit: function() {
    api.addMainTabActionButton('Host', 'Do something with selected host', {
      onClick: function() {
        # arguments[0] is the first selected item
        var hostId = arguments[0].entityId;
        window.alert('Host ID ' + hostId);
      },
      isEnabled: function() {
        # This button is enabled only on single item selection
        return arguments.length == 1;
      }
    });
  }
});
...
[/start.html]

9. Show custom dialog that shows content of the given URL

[start.html]
...
# Anywhere within event handler function code (e.g. UiInit)
api.showDialog('Test Dialog', 'http://www.example.com/', 600, 400);
...
[/start.html]

Level 3 - REST API integration
==============================

10. Get notified upon acquiring new Engine REST API session

[start.html]
...
api.register({
  RestApiSessionAcquired: function(sessionId) {
    window.alert('REST API session ID ' + sessionId);
  }
});
...
[/start.html]

Regards,
Vojtech