• NAME
• USAGE
• SYNOPSIS
• TOP OF FILE
• BOTTOM OF FILE
• OTHER FUNCTIONS
• PLUGIN BUILTIN FUNCTIONS
• PLUGIN UTILITY FUNCTIONS
• PRINT FUNCTIONS
• PLUGIN CALLBACKS
• PLUGIN DOCUMENTATION
• Event Functions
• Fixed Reactions

NAME

Plugin.pm - Base Class For GEM Plugins

USAGE

This Document Describes how plugins work and how to write them.

Plugins are the objects within the generic enterprise manager that perform all the functionality. This class provides core functionality and is inheirited by .pm files that reside in the plugins subdirectory. This is the documentation on how to write a plugin.

SYNOPSIS

Generic Enterprise Manager plugins are written to provide users features through the GEM. A plugin is a perl module (extension .pm) that inheirits from the base class Plugin. The .pm file and a .xml file which identifies associated data (author, copyright notice...) are placed in the plugins subdirecory of the application where they will automatically be loaded at run time. Plugins should conform to this specification. If a plugin does not compile, it not loaded at run time ( you will see error messages ). Plugins are called by and run from the PluginManager module.

TOP OF FILE

It is recommended that the top of a plugin file named xyz follow the following template:

        package xyz;
        @ISA = qw(Plugin);
        use strict;
        use vars qw($VERSION);
        $VERSION = ".01";

BOTTOM OF FILE

As with all perl modules, the plugin must return a 1 and of course you are encouraged to embed embed perldoc documentation after that line.

  1;
  __END__

  =head1 NAME

  eventviewer.pm -  Module for viewing events

  =head2 DESCRIPTION

  The event viewer can be viewed as an example plugin.
  etc...

OTHER FUNCTIONS

After that, the plugin should contain subroutines that override the subroutines in its parent Plugin.pm. These will be used to define user interface elements and to handle functionality. You can create and paint a notebook tab if you wish to use one. You can create explorer buttons (lower left side), bitmaps for the upper left side, can add items to the main explorer tree, and can create the functionality that occurs when you right click items on an element of that tree. You can also create menu items for the menu bar. The heirarchy is that the explorer buttons, when clicked, will populate the explorer tree. The tree is painted and right click items added to elements. When a user selects an element on this tree, selects a menu item, or right clicks on one of the right click items, a call back to event_handler() will be performed.

PLUGIN BUILTIN FUNCTIONS

This section lists functions that your plugin must NOT override. These are automatically called from GEM. In other words... theses functions should not be defined by the plugin.

• new - called by PluginManager
  
• initialize - called by PluginManager
  

PLUGIN UTILITY FUNCTIONS

The following functions are available to you to use in your plugin:

• $plugin->refresh_tree - refreshes the left side window tree
  
• $plugin->messageBox(-message=>$str, -title=>$ttl)
  
Calls a messageBox($str)
• $plugin->DialogBox - return a DialogBox(@_) using normal DialogBox arguments
  
• $plugin->make_button()
  
• -widget=>$frame
  
• -text=>$bstr
  
• -help=>$help_string
  
• -command=>$func
  
• $package->clear_tab($tabname)
  

        $current_main_frame = $package->clear_tab($tabname);

Clears the notebook tab named by $tabname. The cleared frame is then raised and returned to the calling program and can be used as a base frame.

• $package->global_data()
  
calls gemdata->global_data() to get/set values from the gem.xml configuration file
• $package->show_html()
  
show a html frame
• $package->unimplemented()
  
pops up a dialog box that says ... unimplemented...
• $package->write_XMLDATA()
  
save the globaldata() if needed
• $package->get_last_event_info()
  
• $package->ignore_events()
  
• $package->browse()
  
• $package->get_CONFIG()
  

PRINT FUNCTIONS

You also have 3 print functions.

• $package->statusmsg(@msg)
  
a normal/status message that will print to the console, log, and logfile
• $package->notifymsg(@msg)
  
a status message that will not print to the console
• $package->debugmsg(@msg)
  
a debug message that will print to the log and console if --DEBUG passed and will always print to the logfile

The following example line will set the statusbar and print to stdout

        $package->statusmsg( "[navigator.pm] menuclick($menuitem)\n" );

PLUGIN CALLBACKS

The callbacks define the look and feel of the application. The buttons on the lower left side determines which tree is selected in the explorer type menu above it. This function returns an array of buttons to place in that corner.

• $package->init()
  
This user defined function will be called to initialize the plugin during startup
• $package->event_handler()
  
This function takes an event and processes it. The event are categorized. The -eventtype argument defines what type of event is being sent. The following list describes the options that each eventtype can have. Note that the one confusion here is the difference between a tab and a page. A tab is the high level notebook tab (monitoring, log, welcome...). A page is a screen within the tab. Im not really sure how to work pages - how to navigate on them. But the idea is that you have a fixed number of tabs and rather than requiring each plugin to create their own, the plugins can share the tabs. This will make things less crowded.

        <TABLE>
        <TR><TH>EVENT TYPE</TH><TH>ARGUMENT</TH></TR>
        <TR><TD>menu</TD><TD>
                -menuitem</TD></TR>
        <TR><TD>tabchange</TD><TD>
                -oldtab<br>
                -curtab</TD></TR>
        <TR><TD>pagechange</TD><TD>
                -oldpage<br>
                -newpage</TD></TR>
        <TR><TD>treebrowse</TD><TD>
                -entrypath<br>
                -curtab1</TD></TR>
        <TR><TD>treertclick</TD><TD>
                -entrypath<br>
                -clicktext</TD></TR>
        <TR><TD>expbutton</TD><TD>
                -context</TD></TR>
        <TR><TD>imgbutton</TD><TD>
                -text</TD></TR></TABLE>
                
=item * $package->getExplorerButtons()

return a hash of buttons that will go in the lower left corner.

• $package->getMenuItems()
  
Returns an array of menu items (slash delimited) to be displayed in the menu bar. If the parents for the menu item do not exist, they will be created. Thus, if you return /a/b/c you will get 'a' on the menubar and b on its submenu. Placing the mouse on b will show a further submenu of c.
• $package->getPluginPanes($package)
  
Defines the tabs the plugin wishes to create. The tab names are based on the keys returned in a hash. and the values indicate pointer to functions to run when the tab is raised
• $package->menuclick($package,$Frame,$entryPath)
  
This function is called with the full path name to the menu (see getMenuItems) when a user clicks on a menu item.
• $package->getTreeColorFunc($package,$curTreeType)
  
Return function pointer to colorize the tree
• $package->getTreeItems($package,$curTreeType)
  
Return an array of Tree Items for the current tree type. The tree type is related to the explorer button that is pressed and this function is called every time you press one of these buttons. You should obviously test for tree type and not return anything if the tree type is not of your creation.
• $package->getBitMaps($package)
  
Called on initialization to get bitmaps that might want to show in upper left side of window
• $package->bitmapclick($package,$Frame,$entryPath)
  
Called when the bitmap is clicked.
• $package->getTreeRtclk($package,$curTreeType,$treeitmptr)
  
Native callback that allows you to add right click items in the current tree. Basically you get a tree type in $curTreeType and a pointer to an array of items in the tree ($treeitmptr). You return an array of arrays where the outer array matches the items in $treeitmptr and the inner array is a list of the popup right clicks.
• $package->rtclick($package, $entryPath, $clktext)
  
This function is called when a user selects a right click item. The entry path is the full path to the item and will match that which was specified in getTreeRtclk. The clktext is the subitem on that menu that was clicked.

PLUGIN DOCUMENTATION

Plugin documentation is contained in an xml file in the plugins directory that has the same root name as the .pm file. I suggest you browse a few of them for functionality.

 <package name="MDA_tables" version=".01">
   <copyright type="gpl" key="" expires="never" notice="copyright (c) 2005 by edward barlow" />
   <help_url>http://www.edbarlow.com/plugins/MDA_tables.html</help_url>;
   <long_description>Monitoring Table Viewer</long_description>
   <short_description>Monitoring Table Viewer</short_description>
   <author_name>Edward Barlow</author_name>
   <author_mail>barlowedward@hotmail.com</author_mail>
 </package>

Event Functions

GEM communicates with the plugins using the function $pluginname->send_event(%args). This function sends the event to each event_handler() function in loaded plugins. These functions, on a plugin by plugin basis, will handle the event.

Fixed Reactions

Clicking on the buttons in the lower left corner will always redraw_tree() in addition to anything else you want it to do.