[Engine-devel] UI Plugins: PoC patch revision 6 now available
Morrissey, Christopher
Christopher.Morrissey at netapp.com
Fri Oct 19 13:38:41 UTC 2012
Nice work Vojtech! I’m still in the process of pulling down the code but look forward to trying it out. Based on the descriptions of the implementations, it looks like it will give us what we need. I’ll let you know further once I get it going.
-Chris
From: engine-devel-bounces at ovirt.org [mailto:engine-devel-bounces at ovirt.org] On Behalf Of Vojtech Szocs
Sent: Thursday, October 18, 2012 10:49 AM
To: engine-devel
Subject: [Engine-devel] UI Plugins: PoC patch revision 6 now available
Hi guys,
the latest revision of UI Plugins proof-of-concept patch is now available for you to experiment with. You can download the patch from oVirt Gerrit at http://gerrit.ovirt.org/#/c/8120/2 (patch set 2).
Please read on to learn what's new in this revision. If you have any comments, questions or ideas, please let me know!
________________________________
0. UI plugin path information resolved using local Engine configuration
Server-side UI plugin infrastructure now uses local (machine-specific) Engine configuration instead of global (vdc_options database table) Engine configuration:
* Previously, path information was resolved through org.ovirt.engine.core.common.config.Config class - Engine configuration values were retrieved from vdc_options database table.
* Currently, path information is resolved through org.ovirt.engine.core.utils.LocalConfig class - Engine configuration values are retrieved from local file system.
In case you're not working with oVirt Engine through RPM package system, e.g. you have a local development environment set up and you build and deploy oVirt Engine through Maven, please follow these steps:
a. Copy default Engine configuration into /usr/share/ovirt-engine/conf
# mkdir -p /usr/share/ovirt-engine/conf
# cp <OVIRT_HOME>/backend/manager/conf/engine.conf.defaults /usr/share/ovirt-engine/conf/engine.conf.defaults
b. If necessary, copy UI plugin data files from /usr/share/engine/ui-plugins to /usr/share/ovirt-engine/ui-plugins
c. If necessary, copy UI plugin config files from /etc/engine/ui-plugins to /etc/ovirt-engine/ui-plugins
d, In case you want to override the default Engine configuration, put your custom property file into /etc/sysconfig/ovirt-engine
The reason behind this change is that path information for UI plugin data and configuration is typically machine-specific, and should be customizable per machine through Engine local configuration.
________________________________
1. New plugin API function: addMainTabActionButton
The "addMainTabActionButton" API adds custom context-sensitive button to the given main tab's data grid, along with corresponding data grid context menu item.
addMainTabActionButton(entityTypeName, label, actionButtonInterface)
entityTypeName indicates which main tab's data grid the button should be added to, according to the entity type associated with the main tab. entityTypeName values are strings reflecting org.ovirt.engine.ui.webadmin.plugin.entityEntityType enum members. Following entityTypeName values are currently supported (values are case-sensitive): "DataCenter", "Cluster", "Host", "Storage", "Disk", "VirtualMachine", "Template".
Note: "Pool" value is currently not supported, because of org.ovirt.engine.core.common.businessentities.vm_pools entity not implementing the BusinessEntity interface, not sure why though. Maybe we should switch from BusinessEntity to IVdcQueryable interface and always cast getQueryableId method result value to Guid?
label is the title displayed on the button.
actionButtonInterface represents an object that "implements the button interface" by declaring its functions: onClick, isEnabled, isAccessible. All functions of actionButtonInterface receive currently selected item(s) as function arguments.
Let's take a closer look at the concept behind actionButtonInterface. In traditional class-based object-oriented languages, such as Java, interface is an abstract type that contains method declarations without an implementation. A class that implements the given interface must implement all methods declared by that interface (unless it's an abstract class, but this isn't relevant in our case).
In contrast with traditional class-based object-oriented languages, JavaScript supports OOP through prototype-based programming model (https://developer.mozilla.org/en-US/docs/JavaScript/Introduction_to_Object-Oriented_JavaScript). At the same time, JavaScript language is dynamically-typed and therefore doesn't support traditional concept of interface in OOP, it uses "duck typing" technique instead (http://en.wikipedia.org/wiki/Duck_typing).
The simplest way to provide an object that "implements the given interface" in JavaScript is to use "duck typing" technique: providing an object that contains well-known functions. In UI plugin infrastructure, I call this concept "interface object", represented by org.ovirt.engine.ui.webadmin.plugin.jsni.JsInterfaceObject class. Unlike the traditional concept of interface abstract type in object-oriented languages, an "interface object" does not necessarily have to declare all functions of the given interface in order to "implement" such interface. In fact, an empty object can be used as a valid "interface object". Missing functions will be simply treated as empty (no-op) functions. Furthermore, an "interface object" can "implement" multiple interfaces by declaring functions of those interfaces (interface composition).
Getting back to "addMainTabActionButton" API, here's a sample code that adds new button to "Host" main tab data grid, as part of UiInit event handler function:
UiInit: function() {
api.addMainTabActionButton('Host', 'Single-Host Action',
// Action button interface object
// All functions receive currently selected item(s) as function arguments
{
// Called when the user clicks the button
onClick: function() {
// Calling 'arguments[0]' is safe, because onClick() can be called
// only when exactly one item is currently selected in the data grid
window.alert('Selected host entity ID = ' + arguments[0].entityId);
},
// Returning 'true' means the button is enabled (clickable)
// Returning 'false' means the button is disabled (non-clickable)
// Default value = 'true'
isEnabled: function() {
// Enable button only when exactly one item is selected
return arguments.length == 1;
},
// Returning 'true' means the button is visible
// Returning 'false' means the button is hidden
// Default value = 'true'
isAccessible: function() {
// Always show the button in the corresponding data grid
return true;
}
}
);
}
As mentioned above, all functions of an interface object are optional. For functions expecting return value, default value is defined by UI plugin infrastructure. For example:
* onClick - no default value (no return value expected)
* isEnabled / isAccessible - default value "true" (boolean return value expected)
Note: UI plugin infrastructure checks the actual return value type, and uses default value in case the function returned something of wrong (unexpected) type.
In the example above, "currently selected item(s)" maps to JSON-like representations of business entities currently selected in the corresponding data grid. For now, the entity representation is quite simple and same for all entity types:
{ entityId: "[BusinessEntityGuidAsString]" }
In future, we will create specific JSON-like representations for specific business entities, in compliance with Engine REST API entity structure.
For a more extensive example of using "addMainTabActionButton" API, please see the attached "addMainTabActionButton.html.example" file.
________________________________
2. Improved plugin API function: addMainTab
The "addMainTab" API was improved to address following issues:
* "addMainTab" can now be called at any moment during UI plugin runtime, given that the plugin is allowed invoke plugin API functions (plugin is either INITIALIZING or IN_USE).
Previously, "addMainTab" worked reliably only when called from within UiInit event handler function.
Currently, it's possible to call "addMainTab" at any moment, e.g. from within some other event handler function (after UiInit has completed).
* "addMainTab" now retains "active" tab (highlighted tab GUI).
"addMainTab" works by adding new tab component (GWTP presenter proxy) and refreshing main tab panel GUI by removing all related tabs and re-adding them again.
This logic is handled by org.ovirt.engine.ui.common.presenter.DynamicTabContainerPresenter class, which makes sure that "active" tab is retained even after main tab panel was refreshed.
Furthermore, custom main tab implementation now displays the content of the given URL through HTML iframe element.
________________________________
3. Improved native JavaScript function handling (GWT JSNI)
This patch introduces org.ovirt.engine.ui.webadmin.plugin.jsni.JsFunction and org.ovirt.engine.ui.webadmin.plugin.jsni.JsFunctionResultHelper classes providing Java abstraction for invoking native JavaScript functions. These classes follow the general contract of "interface object" as mentioned above.
JsFunctionResultHelper is particularly useful when dealing with functions which are expected to return value of a certain type. Too bad standard GWT JSNI classes don't provide such abstraction for working with native functions out-of-the-box...
________________________________
4. ActionPanel and ActionTable type hierarchy refactoring (related to "addMainTabActionButton" API)
Previously, AbstractActionPanel and AbstractActionTable classes didn't implement any reasonable interface that would allow other components (client-side UI plugin infrastructure) to depend on their functionality in a loosely-coupled manner. This would make code that implements "addMainTabActionButton" API "ugly": main tab view interface would have to reference AbstractActionTable class directly. In MVP design pattern, view interface should avoid referencing specific GWT Widget classes directly.
This patch introduces new interfaces for ActionPanel and ActionTable components while eliminating code redundancy (duplicate or unnecessary code).
________________________________
5. ActionPanel type hierarchy refactoring (related to "addMainTab" API)
Since org.ovirt.engine.ui.common.presenter.DynamicTabContainerPresenter defines new DynamicTabPanel interface that extends standard GWTP TabPanel interface, some refactoring had to be done in related ActionPanel classes.
This patch makes sure that both org.ovirt.engine.ui.common.widget.tab.AbstractTabPanel (widget) and org.ovirt.engine.ui.common.view.AbstractTabPanelView (view) support DynamicTabPanel interface.
Note that for now, only main tab panel (org.ovirt.engine.ui.webadmin.section.main.presenter.MainTabPanelPresenter) supports dynamic tabs within its view.
________________________________
Where is addSubTab API function?
Implementing "addSubTab" API requires some more changes, and I didn't want to delay this PoC patch just because of it...
Here's a sample code that illustrates proposed "addSubTab" API usage:
UiInit: function() {
api.addSubTab('Host', // entityTypeName
'Custom Host Sub Tab', // label
'custom-host-sub-tab', // historyToken
'http://www.ovirt.org/', // contentUrl
// Sub tab interface object
// All functions receive currently selected item(s)
// within the main tab data grid as function arguments
{
// Returning 'true' means the sub tab is visible
// Returning 'false' means the sub tab is hidden
// Default value = 'true'
isAccessible: function() {
return arguments.length == 1 && arguments[0].entityId == '<MyHostEntityId>';
}
}
);
}
As part of "addSubTab" API implementation, I'll refactor custom main tab components, in order to use one "tab type" for both main and sub tabs.
Currently, we have one (and only one) "tab type" - a tab that shows content of the given URL through HTML iframe element.
We could also create new "tab types", e.g. form-based tab that shows key/value pairs (IMHO this could be quite useful for custom sub tabs).
________________________________
Let me know what you think!
Cheers,
Vojtech
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ovirt.org/pipermail/engine-devel/attachments/20121019/9c3b5a08/attachment.html>
More information about the Engine-devel
mailing list