All FOSSology plugins are based on a common template class called FO_Plugin that defines basic functions and common variables. (The template can be found in ui/template/template-plugin.php or here in the sourceforge subversion tree.) Existing and new plugins extend the functionality of this FOSSology template and have the ability to set or override any of the values or logic defined by FO_Plugin.

Variables defined by FO-Plugin are as follows:

• $State. This defines the state of the plugin.
  • PLUGIN_STATE_FAIL,-1 plugin failed status
  • PLUGIN_STATE_INVALID,0 plugin not defined - this is the default value
  • PLUGIN_STATE_VALID,1 used during the UI installation
  • PLUGIN_STATE_READY,2 used during the UI post-installation
• $Name. This must be a name for referencing this plugin. In particular, if another plugin depends on this plugin, then this is the name that will be used to reference it.
• $Version. Multiple versions of the same $Name may exist (good for debugging or upgrading). Other plugins may have a dependency on a specific $Version of $Name, but usually just want the latest greatest. The value of $Version should be a number (for sorting). The default value is “1.0”.
• $Title. This string is used for HTML title tags and window menu bars.
• $PluginLevel. Plugins are actually sorted in the plugin data structure. If there is some reason this plugin must come first, then increase this number (default is 10). First plugins are sorted by dependencies. If all dependencies are met, then plugins are sorted by this number.

In the Hello World plugin example, the variables $State, $Version and $PluginLevel were left to the values set by FO_Plugin. $Name and $Title were overridden like this:

   var $Name       = "hello";                 /* This is the name by which FOSSology identifies the plugin */
   var $Title      = "Hello World Example";   /* This is the title that will be displayed in the UI */

• $DBaccess. Plugins can be restricted based on logged-in user level. If the user does not have the correct access level, then the plugin is disabled. Current user levels are tied to the type of database access. The levels are:
  • PLUGIN_DB_NONE (0). This plugin does not use the database. Anyone can access this plugin.
  • PLUGIN_DB_READ (1). This plugin does read-only access to the database. Any user with read-only access can use this plugin. (This is the default access level for users who are not logged in.)
  • PLUGIN_DB_DOWNLOAD (2). Along with read-only access, the user may download files. This is given its own access level because “downloading” is considered “distributing software”. Since some licenses restrict distribution, this access level is restricted.
  • PLUGIN_DB_WRITE (3). Besides read and possible download, this plugin writes to the database.
  • PLUGIN_DB_UPLOAD (4). Besides read, download, and write, this plugin is used for managing uploaded files.
  • PLUGIN_DB_ANALYZE (5). All of the above is permitted, as well as managing analysis jobs.
  • PLUGIN_DB_DELETE (6). (All of the above, plus:) While adding to the database takes one set of access levels, deleting is a higher access level. The main reason this is a different access level: adding and analyzing can take time. Deleting can undo all of that effort. To prevent accidental (or malicious) deletions, this functionality is placed in its own access level.
  • PLUGIN_DB_DEBUG (7). This plugin is used for debugging the system. Most users won't have a need for this. Debug plugins are permitted to do all of the above functionality.
  • PLUGIN_DB_USERADMIN (10). This is the current super-user. This plugin level permits doing *anything*, including creating, managing, and deleting user accounts. The basic idea: if you can create a user with specific permissions, then you might as well already have those permissions.
• $LoginFlag. Some plugins require a logged in user, even if the access is read-only or “none”. The default value is “1” meaning “login required”. Set to 0 if any user (including not logged in) can access this plugin.

In the Hello World plugin example, $DBaccess is left to the value set in FO_Plugin (PLUGIN_DB_NONE) and the value of $LoginFlag is overridden like this:

   var $LoginFlag  = 0;   /* You do not need to be logged into the UI to execute this plugin */

• $NoMenu. When executed through the web browser, all plugins default to showing the banner and drop-down menus at the top. If you don't wish to have these drop down menus displayed, then set this to “0”. As an example, the folder plugin (ui-folders.php) sets $NoMenu=1 because the output from this plugin is its own menu.
• $NoHTML. Similar to $NoMenu, this variable disables all default HTML, including the default CSS definitions. The AJAX plugins set $NoHTML=1 since the default HTML would corrupt the XML (or other) formatted results. If you set $NoHTML=1, then you don't need to set $NoMenu=1 (the menu will not be there).
• $NoHeader. Similar to $NoMenu and $NoHTML, this variable disables all of the default HTTP header information AND all default HTML. (Default is 0, set to 1 to disable the headers. Setting it to 1 also sets $NoMenu=1 and $NoHTML=1.) For example, the “download file” plugin (ui-download.php) does not use any default html or headers since those would corrupt the download stream.

In the Hello World plugin example, we want the banner & drop-down menus displayed and we want HTML formatting & the HTTP header information included. Therefore, we simply default to the values set in FO_Plugin:

   var $NoMenu=0;	/* 1 = Don't show the HTML menu at the top of page */
   var $NoHeader=0;	/* 1 = Don't show the HTML header at the top of page */
   var $NoHTML=0;	/* 1 = Don't add any HTML to the output */

• $InitOrder. On rare occasions, a plugin may be needed to initialize before all other plugins. (E.g., the database should be initialize before all else.) Higher values will initialize first. Under normal circumstances, plugins should not need to change the default value.
• $Dependency. This is an array of plugin names (set by each plugin's $Name) that are required by this plugin. For example, if your plugin contains $Dependency=array(“db”,”ui-browse”); then it will only be available if both the plugin named “db” and “ui-browse” are available. NOTE: Dependency loops between plugins will always fail since the dependent plugin is unavailable.

Again, we default to the values set in FO_Plugin for Hello World:

  var $Dependency = array();
  var $InitOrder=0;

Plugins may define a menu item and many plugins register themselves with the top user menu. Each menu item belongs in a category (menu list) and could be in subcategories (menu sublists). The MenuList identifies the list (and sublists) where this item belongs. The menu heirarchy is defined by a name and a ”::” to denote a submenu item.

These three variables simplify this registration process.

• $MenuList. This is the full name of the menu option, with ”::” defining the path. For example, “Organize::Folders::Create” will register this plugin under the “Organize” menu heading, submenu “Folder”, using the name “Create”.
• $MenuOrder. The default menu ordering is alphabetical. If you don't want to be alphabetical, then change the menu order. The default value is “0”. Higher numbers come first in the menu. All menu items with the same $MenuOrder value are sorted alphabetically.
• $MenuTarget. The top-level user menu has the ability to return content in different windows. Set $MenuTarget to specify an alternate ”<a href=… target=value>” target value.

For example, to define our “Hello World” menu item under the “Help” menu, we used this definition:

   $MenuList = "Help::Hello World";

And the “delete” agent under the Tools, Administration menu is defined like this:

   $MenuList = "Tools::Administration::Delete";
   $MenuOrder=0;

Since menus may link to results that belong in a specific window, $MenuTarget can identify the window. If not defined, the UI will use a default results window.

NOTES:

1. If the MenuList location does not exist, then it will be created.
2. If a plugin does not have a menulist item, then it will not appear in any menus.
3. MenuList is case and SPACE sensitive. “Help :: About” defines “Help ” and ” About”. While “Help::About” defines “Help” and “About”.

Finally, we'll say a few words about the functions defined by FO_Plugin. There are basically 2 types of functions in FO_Plugin. The first consists of all functions that do “housekeeping”; Install(), Remove(), Initialize(), PostInitialize(), RegisterMenus() and Destroy(). At a minimum, all plugins must call the Initialize() function to be added to an internal data structure (an array called $Plugins). For the Hello World plugin it looks like this:

  $NewPlugin = new ui_hello;
  $NewPlugin->Initialize();    /* Initialize is a function defined by FO_Plugin */

The other type of function defined in FO_Plugin are those that generate output for use in a text CLI or web page; OutputOpen(), Output(), OutputClose() to generate output, or OutputSet(), Output(), OutputUnset() to generate output that will be included within other output.

The type of output generated is determined by the variable $OutputType and the variable $OutputToStdout determines if output goes to stdout or a web page. Possible values for OutputType are Text, HTML, or XML.

Default values for these variables are set in FO_Plugin like this:

  var $OutputType="Text";
  var $OutputToStdout=0;

The Hello World plugin includes a function to print the “Hello World” message witch incorporates both the $OutputType and $OutputToStdout variables from FO_Plugin.

  function Output()
    {
    if ($this->State != PLUGIN_STATE_READY) { return; }     /* State is set by FO_Plugin */
    $V="";
    switch($this->OutputType)                               /* OutputType is set by FO_Plugin */
      {
      case "XML":
        $V .= "<text>$this->_Text</text>\n";
        break;
      case "HTML":
        $V .= "<b>$this->_Text</b>\n";
        break;
      case "Text":
        $V .= "$this->_Text\n";
        break;
      default:
        break;
      }
    if (!$this->OutputToStdout) { return($V); }            /* OutputToStdout is a function defined by FO_Plugin */  
    print($V);
    return;
    }

• The complete code for FO_Plugin can be found here in the SourceForge subversion repository.
• Additional information about plugins can be found in an overview of the UI architecture here.