Plugin Design - Necessities

Description

All plugins are assumed to conform to certain requirements. These requirements are necessary to register, initialize, and execute plugins. All plugins must extend the Ruby class Plugin::PluginSkeleton, which is included with Draco in the scripts/ruby/pengine/model directory. This class can be directly extended, although a convenience class for regression plugins is also included.

Registration

Plugins are registered at program startup via calls to the register function. Ruby files containing plugin classes must also execute the following call in order for the plugin to be recognized by Draco:



register(PluginClassName)

The plugin class itself must contain the following class attributes:

Attribute	Description
@@NAME	The plain-text name of the plugin as it will appear in menus and window titles
@@TYPE	The type of plugin, which is one of the following: PluginType.regression PluginType.analysis

These attributes are read via the class methods name and type.

In release 1.1, all plugins must reside in the appropriate plugin directory.

Initialization

Plugins are initialized when selected from their corresponding menu. Initialization simply creates the Ruby object, and no siginificant calculations should be performed during this period.

At initialization, the PluginSkeleton constructor automatically calls the methods initialize_columns and initialize_options methods without any arguments. These methods initialize the list of columns to be displayed in the plugin's window and any simple options associated with the plugin respectively.

initialize_columns

The initialize_columns method should specify the name of selection columns to be displayed in the plugin window. The selection columns allow the user to select variables via check boxes for different purposes. A selection column can be initialized via the following calls within the initialize_columns method:

@selectioncolumns.add PluginSkeleton.createColumn(name,
multiple-selections, exclusivity)

The call above uses a convenience class method, createColumn, to generate a selection column. The arguments are defined as follows:

Argument	Description
name	Plain text name of the column to be displayed
multiple-selections	true to allow multiple variables to be selected in a single column
exclusivity	true to force variables selected in this column to only be selected in this column, eliminating preexisting selections of the same variable in other columns

initialize_options

The initialize_options method should specify the option names, types, and default values for the plugin. These options are presented to the user via a dialog that can be opened from the plugin's menu.

An option can be added to the plugin in the initialize_options method via the following call

@options.add name, type, default-value

The statement above accepts three arguments, all strings. The name specifies the human-readable name for the option. The type and default values can be any of the following:

Type	Default Values	Description
"boolean" "truefalse" "check" "checkbox"	"true" or "false"	Initializes a simple check box option
"int" "integer"	Any integer value	Creates a textfield that accepts an integer
"float" "double"	Any floating point value	Creates a textfield that accepts a floating point value
"string"	Any string	Initializes a textfield that accepts any text
"variable"	A valid variable name or index	Generates a dropdown listing all current variables, which returns the variable name as plain text
"constant"	A valid constant name	Generates a dropdown listing all current constants, which returns the constant value

Execution

Plugins must override two methods, run and results, which represent execution of the plugin's calculation code and extraction of results respectively. Both are called within a thread separate from the GUI, and are expected to require a non-trivial period to complete. Once the call to the run method has completed, Draco immediately calls the results method to retrieve the results of the plugin calculations. The results method is expected to return a string, and can return a valid HTML document within the string for display. Regression plugins have additional extensions to the results method for simple results generation provided the regression conforms to certain attributes.

Access to Selection Columns

Selection columns can be accessed by plugins using calls to the selections method. The selections method accepts one argument, a valid column name, and returns an array of variable names which have been selected by the user. The resulting array of variable names can be used in conjuction with the to_matrix method within the data model to retrieve data.

Access to Options

Options can be accessed via the following calls:

@options.get_option(name)
or
@options.get_options

The first column retrieves the value of the option by name as specified by a plain text string. The second method returns a hash of all option names as keys referencing their corresponding values.