From vszocs at redhat.com Mon Nov 19 09:29:24 2012 Content-Type: multipart/mixed; boundary="===============4895327551741352815==" MIME-Version: 1.0 From: Vojtech Szocs To: devel at ovirt.org Subject: [Engine-devel] UI plugins crash course (for plugin developers) Date: Mon, 19 Nov 2012 09:29:24 -0500 Message-ID: <415793932.7311099.1353335364366.JavaMail.root@redhat.com> In-Reply-To: 288289482.7271048.1353327709415.JavaMail.root@redhat.com --===============4895327551741352815== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 1. Sync with upstream git repository and apply recent UI plugin patches (re= v.6 and rev.7) $ cd $ git fetch && git rebase origin $ git fetch git://gerrit.ovirt.org/ovirt-engine refs/changes/20/8120/4 && g= it checkout FETCH_HEAD $ git fetch git://gerrit.ovirt.org/ovirt-engine refs/changes/50/9250/2 && g= it 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 /backend/manager/conf/engine.conf.defaults /usr/share/ovir= t-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] [/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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D 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 =3D arguments[0].entityId; window.alert('Host ID ' + hostId); }, isEnabled: function() { # This button is enabled only on single item selection return arguments.length =3D=3D 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D 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 --===============4895327551741352815==-- From vszocs at redhat.com Mon Nov 19 09:49:39 2012 Content-Type: multipart/mixed; boundary="===============6782812679571034971==" MIME-Version: 1.0 From: Vojtech Szocs To: devel at ovirt.org Subject: [Engine-devel] UI plugins crash course part two (for plugin developers) Date: Mon, 19 Nov 2012 09:49:38 -0500 Message-ID: <670870582.7319531.1353336578842.JavaMail.root@redhat.com> In-Reply-To: 415793932.7311099.1353335364366.JavaMail.root@redhat.com --===============6782812679571034971== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Hi guys, this is a follow-up on the quick "crash course" for writing simple UI plugi= n. Before we proceed, please keep in mind that: - api.register() must be called exactly once, subsequent calls "overwrite" = previous ones - api.register() must be called before api.ready(), otherwise your plugin w= ill not work - you don't have to define all supported event handler functions in api.reg= ister(), just the ones your plugin is interested in (e.g. UiInit) Level 4 - Let's make things configurable =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 1. Specify default plugin configuration (optional) $ vim /usr/share/ovirt-engine/ui-plugins/hello-ui-world.json [hello-ui-world.json] ... "config": { "testLink": "http://www.example.com/" } ... [/hello-ui-world.json] 2. Override default plugin configuration (optional) $ mkdir -p /etc/ovirt-engine/ui-plugins $ vim /etc/ovirt-engine/ui-plugins/hello-ui-world-config.json [hello-ui-world-config.json] { "config": { "testLink": "http://www.another-example.com/" } } [/hello-ui-world-config.json] 3. Use plugin configuration that has been merged together $ vim /usr/share/ovirt-engine/ui-plugins/hello-world-files/start.html [start.html] ... # Anywhere within event handler function code (e.g. UiInit) var conf =3D api.configObject(); api.showDialog('Test Dialog', conf.testLink, 600, 400); ... [/start.html] Regards, Vojtech --===============6782812679571034971==-- From dneary at redhat.com Wed Nov 21 08:57:23 2012 Content-Type: multipart/mixed; boundary="===============5030389220802491618==" MIME-Version: 1.0 From: Dave Neary To: devel at ovirt.org Subject: Re: [Engine-devel] UI plugins crash course part two (for plugin developers) Date: Wed, 21 Nov 2012 14:57:20 +0100 Message-ID: <50ACDDC0.3000604@redhat.com> In-Reply-To: 670870582.7319531.1353336578842.JavaMail.root@redhat.com --===============5030389220802491618== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Hi Vojtech, This is great! Would you be interested in writing this up as a tutorial series (working = through a real-life example) for publication on the oVirt website? I = think it's the kind of article which would be very useful in promoting = the plug-in API. Cheers, Dave. On 11/19/2012 03:49 PM, Vojtech Szocs wrote: > Hi guys, > > this is a follow-up on the quick "crash course" for writing simple UI plu= gin. > > Before we proceed, please keep in mind that: > - api.register() must be called exactly once, subsequent calls "overwrite= " previous ones > - api.register() must be called before api.ready(), otherwise your plugin= will not work > - you don't have to define all supported event handler functions in api.r= egister(), just the ones your plugin is interested in (e.g. UiInit) > > > Level 4 - Let's make things configurable > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > 1. Specify default plugin configuration (optional) > $ vim /usr/share/ovirt-engine/ui-plugins/hello-ui-world.json > > [hello-ui-world.json] > ... > "config": { "testLink": "http://www.example.com/" } > ... > [/hello-ui-world.json] > > 2. Override default plugin configuration (optional) > $ mkdir -p /etc/ovirt-engine/ui-plugins > $ vim /etc/ovirt-engine/ui-plugins/hello-ui-world-config.json > > [hello-ui-world-config.json] > { > "config": { "testLink": "http://www.another-example.com/" } > } > [/hello-ui-world-config.json] > > 3. Use plugin configuration that has been merged together > $ vim /usr/share/ovirt-engine/ui-plugins/hello-world-files/start.html > > [start.html] > ... > # Anywhere within event handler function code (e.g. UiInit) > var conf =3D api.configObject(); > api.showDialog('Test Dialog', conf.testLink, 600, 400); > ... > [/start.html] > > > Regards, > Vojtech > > _______________________________________________ > Engine-devel mailing list > Engine-devel(a)ovirt.org > http://lists.ovirt.org/mailman/listinfo/engine-devel > -- = Dave Neary - Community Action and Impact Open Source and Standards, Red Hat - http://community.redhat.com Ph: +33 9 50 71 55 62 / Cell: +33 6 77 01 92 13 --===============5030389220802491618==-- From vszocs at redhat.com Thu Nov 22 11:53:27 2012 Content-Type: multipart/mixed; boundary="===============3136887393631880716==" MIME-Version: 1.0 From: Vojtech Szocs To: devel at ovirt.org Subject: Re: [Engine-devel] UI plugins crash course part two (for plugin developers) Date: Thu, 22 Nov 2012 11:53:26 -0500 Message-ID: <515215285.8800865.1353603206945.JavaMail.root@redhat.com> In-Reply-To: 50ACDDC0.3000604@redhat.com --===============3136887393631880716== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Hi Dave, this is excellent idea! It's definitely easier (and more fun) for others to= follow "crash course" tutorials than just reading wiki docs :) (I've used the "Level" metaphor to give readers the feeling that they're pr= ogressing from beginner to advanced topics, as they make their way through = UI plugin development.) I can certainly dedicate some time to writing such tutorial series. What wo= uld be the best way to start? Regards, Vojtech ----- Original Message ----- From: "Dave Neary" To: engine-devel(a)ovirt.org Sent: Wednesday, November 21, 2012 2:57:20 PM Subject: Re: [Engine-devel] UI plugins crash course part two (for plugin de= velopers) Hi Vojtech, This is great! Would you be interested in writing this up as a tutorial series (working = through a real-life example) for publication on the oVirt website? I = think it's the kind of article which would be very useful in promoting = the plug-in API. Cheers, Dave. On 11/19/2012 03:49 PM, Vojtech Szocs wrote: > Hi guys, > > this is a follow-up on the quick "crash course" for writing simple UI plu= gin. > > Before we proceed, please keep in mind that: > - api.register() must be called exactly once, subsequent calls "overwrite= " previous ones > - api.register() must be called before api.ready(), otherwise your plugin= will not work > - you don't have to define all supported event handler functions in api.r= egister(), just the ones your plugin is interested in (e.g. UiInit) > > > Level 4 - Let's make things configurable > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > 1. Specify default plugin configuration (optional) > $ vim /usr/share/ovirt-engine/ui-plugins/hello-ui-world.json > > [hello-ui-world.json] > ... > "config": { "testLink": "http://www.example.com/" } > ... > [/hello-ui-world.json] > > 2. Override default plugin configuration (optional) > $ mkdir -p /etc/ovirt-engine/ui-plugins > $ vim /etc/ovirt-engine/ui-plugins/hello-ui-world-config.json > > [hello-ui-world-config.json] > { > "config": { "testLink": "http://www.another-example.com/" } > } > [/hello-ui-world-config.json] > > 3. Use plugin configuration that has been merged together > $ vim /usr/share/ovirt-engine/ui-plugins/hello-world-files/start.html > > [start.html] > ... > # Anywhere within event handler function code (e.g. UiInit) > var conf =3D api.configObject(); > api.showDialog('Test Dialog', conf.testLink, 600, 400); > ... > [/start.html] > > > Regards, > Vojtech > > _______________________________________________ > Engine-devel mailing list > Engine-devel(a)ovirt.org > http://lists.ovirt.org/mailman/listinfo/engine-devel > -- = Dave Neary - Community Action and Impact Open Source and Standards, Red Hat - http://community.redhat.com Ph: +33 9 50 71 55 62 / Cell: +33 6 77 01 92 13 _______________________________________________ Engine-devel mailing list Engine-devel(a)ovirt.org http://lists.ovirt.org/mailman/listinfo/engine-devel --===============3136887393631880716==-- From dneary at redhat.com Fri Nov 23 02:37:27 2012 Content-Type: multipart/mixed; boundary="===============9218475805113193973==" MIME-Version: 1.0 From: Dave Neary To: devel at ovirt.org Subject: Re: [Engine-devel] UI plugins crash course part two (for plugin developers) Date: Fri, 23 Nov 2012 08:37:24 +0100 Message-ID: <50AF27B4.8030707@redhat.com> In-Reply-To: 515215285.8800865.1353603206945.JavaMail.root@redhat.com --===============9218475805113193973== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Hi, On 11/22/2012 05:53 PM, Vojtech Szocs wrote: > this is excellent idea! It's definitely easier (and more fun) for others = to follow "crash course" tutorials than just reading wiki docs :) I think so too. > (I've used the "Level" metaphor to give readers the feeling that they're = progressing from beginner to advanced topics, as they make their way throug= h UI plugin development.) I noticed! And I like it :-) > I can certainly dedicate some time to writing such tutorial series. What = would be the best way to start? with Level 1, I suppose... One thing I would like is to have something you can do to validate that = you've understood a level before you move on (like the bad guy that you = have to beat to complete levels in video games). It could be something = as straightforward as a "Compilation successful" message, or a "Test = passed" on a unit test, or a screenshot of "here's what you should have = now" - something to let the reader know when they're only a little off = the path, and how to get back onto it. I think that the wiki or website could be fine - it's just a web page = after all - what's important is the promotion of the series in the right = places, and making it look nice, and like a series of articles rather = than one big wiki page. Thanks again! It looks great so far. Cheers, Dave. -- = Dave Neary - Community Action and Impact Open Source and Standards, Red Hat - http://community.redhat.com Ph: +33 9 50 71 55 62 / Cell: +33 6 77 01 92 13 --===============9218475805113193973==--