Expecco Plugin API
Aus ExpeccoWiki
Inhaltsverzeichnis |
Expecco Plugin API
The expecco plugin API allows for both graphical and non-graphical extensions to be built for and added to expecco. Plugins are allowed to add items to the top menu, to the toolbar, to popup-menus in the tree or the diagram editor, and to add additional pages (tabs) to the testplan and testcase editors, and to the settings dialog. Plugins can also add custom fields to any artefact, for example to remember links or ids for external program interfacing.
Plugins which are placed into the "plugins" directory are automatically loaded and installed when expecco is started. Other plugins can be installed at any later time via the settings dialog.
Usually, plugins consist of dlls (dynamic link libraries) which contain binary compiled code. However, it is also possible to directly load source-code files, as expecco includes a compiler to generate bytecode from loaded program text.
Plugins are developed and created using the free Smalltalk/X (ST/X) development IDE, and deployed as binary class libraries. The ST/X IDE includes a project builder to generate self-installing deployable dll-packages. Alternatively, small plugins and additional classes can also be deployed in source form via the IDE's "fileOut" operation.
A plugin's protocol consists of a number of methods which MUST, in addition to optional methods which CAN be implemented.
The entry point of every plugin is represented by a plugin class, a subclass of
Expecco::AbstractPlugin.
Immediately after loading, that classes' initialize method is called,
followed by a number of other calls into the plugin, by which expecco collects various aspects from the plugin:
Initialization & Release
- void initialize (optional class method)
Invoked right after loading, before any of the methods below is called. Can be used to initialize files, connections, or check for other required packages to be loaded correctly. If redefined, do not forget to call"super initialize". Be careful to not block or perform long computations in this method, as it is invoked unconditionally - even if the plugin is never used later. If such computations or connections are needed, it might be better to perform them lazily later, when the plugin is first instantiated (by redefining either the classes"new"method, or the instances"initialize"method).
- void loadRequiredPackages (optional class method)
Invoked by the initialize method. Gives the plugin a change to load any additional required packages (for example: telecommunication class libraries). Normally, this is not required as binary class packages usually pull in any required packages automatically.
- void release (optional class method)
Invoked right before the plugin is unloaded (if it is so via the settings dialog). Should close any open files, connections and remove any temporary data-files which might have been created by the plugin.
Startup, Registration and Queries
- String pluginName (required class method)
Should return the plugin's name. This is the name shown in the list of loaded plugins (in the plugin settings dialog).
- String pluginInfo (required class method)
Should return the plugin's name. Must return some user readable info about what the plugin does (also for the plugin settings dialog).
- UUID pluginUUID (required class method)
Must return the plugin's unique UUID. This id should be hardcoded into the plugin to return the same constant value forever. It is needed to detect upgrades or duplicate plugin classes.
- Class[] pluginClasses (required class method)
Should return a collection of classes, which comprise the plugin. (used in the plugin settings dialog, and to unload a plugin).
- (String Symbol)[] pluginSettingsList (optional class method)
Should return a collection of 2-element arrays, each defining an additional tab in the settings application. The first element will be used as the name (in the settings-dialog's tree), the second entry must be the name of the class which implements the tabs GUI. It must be a subclass of ApplicationModel.
- Image pluginMenuIcon (optional class method)
Can be defined to return a bitmap image; this is shown in the plugin-menu. It should be of size 16x16.
Menu Queries
All of the above have been class methods. Once registered, one plugin instance is created for every open browser window. This allows for a plugin to keep context specific data (such as last used directory or settings) on a per-window basis, although most plugins don't do this, but instead keep their state in class variables which are shared by all browser windows.
The instance interface is:
- Boolean pluginBrowserMenuIsVisible (optional instance method)
Should return true, if this plugin has any visible menus for the browser (either topMenu or toolbar-menu).
- MenuItem[] pluginToolbarItemList (optional instance method)
A list of items to add to the toobar menu.
- MenuSpec pluginBrowserMenu (optional instance method)
Can be defined to return a menuspec; this menu will be built into the plugin-menu as a separate submenu. Menuspec methods can be created easily using the ST/X MenuEditor tool.
- MenuSpec pluginBrowserMainMenu (optional instance method)
Can be defined to return a menuspec; this menu will be sliced into the main-menu. Menuspec methods can be created easily using the ST/X MenuEditor tool.
- MenuSpec pluginHelpBrowserMenu (optional instance method)
Can be defined to return a menuspec; this menu will be built into the help-plugin-menu as a separate submenu. Use the ST/X MenuEditor tool to create menuspec methods.
- MenuSpec pluginMenuItemsFor: what forElement: anElement (optional instance method)
Can be defined to return a menuspec which is added to the right-click (popup) menu of an element. The argument "what" is either#diagramor#tree; the "anElement" argument is a tree item element (blockdescription, testplan, resource, etc.) or a diagram element (step, connection, pin, etc.).
If any menu items were returned in one of the above menu-query methods, corresponding menu items which call back into the plugin-instance are added to either the top- or the toolbar menu.
Editor Page Queries
In addition, plugins get a chance to add a private page to some editors, by returning an application instance (derived from ApplicationModel) from the following method:
- ApplicationModel pluginTabApplicationFor: aSymbol (optional instance method)
Can be defined to return an editor-specific additional tab-page. The argument specifies which editor is querying for the page; it is (currently) one of #testPlanEditor or #testCaseEditor (as of Mar 2010).
If an application was returned by the above entry, that application's GUI is added to the testplan- or testcase editor as a subapplication. The interface with the embedding editor is via the following protocol:
- void editedItem: aTestcaseItem (required)
The editor passes the item being edited (a testplan or testcase) to the plugin-app.
- String noteBoolTabLabel (required)
the plugin's tab will get this label in the notebook.
- void whenModifiedDo: aBlock (required)
the plugin's tab should remember this block argument and invoke it as a callback, whenever the edited item (i.e. testcase or testplan) is modified by it. This is used to enable the "accept" buttons at the bottom of the editor.
Private Data/Fields of a Plugin
Plugins can add private fields to testCases, testPlans and other artefacts. These additional fields are included in the xml, when the testSuite is stored or loaded.
- void propertyAt: aKey put: aString
To add a plugin-property. The key should be a string or symbol. Make sure that there are no conflicts, by prepending the plugin's name to the key. For example: 'JIRA.issueID' would be a good idea. Only string-values are allowed, If required, a string representation (i.e.printString) should be used to ensure this. These properties are stored in the xml under the "properties" tag.
- String propertyAt: aKey
To retrieve a plugin-property. Use the same key as used when storing the property. Only string-values can be retrieved - if required, reconstruct the object using#readFrom:.
Execution Hooks
Plugins get informed about test executions. Notice that these entries are only called for regular test executions. Executions of a test-diagram or via the project-tree-menu, are not forwarded to plugins.
- void pluginPreExecuteTestPlan: aTestPlanItem (optional instance method)
Called before a testplan is executed. Similar to a preaction, raising an error from within this preExecute-callback will cancel the testplan's execution.
- void pluginPreExecuteTestCase: aTestCaseItem (optional instance method)
Called before a testcase is executed. The log-argument (empty at this time) could be used to add a notification or other information feedback. Similar to a preaction, raising an error from within this preExecute-callback will cancel the testcases's execution (and the testplan's, if the testcase is not an optional one).
- void pluginPostExecuteTestCase: aTestCaseItem log: aLog (optional instance method)
Called after a testcase has been executed. The log-argument contains the detailed execution log information, and especially the outcome verdict.
- void pluginPostExecuteTestPlan: aTestPlanItem (optional instance method)
Called after a testplan has been executed.
Back to Online Documentation
