Class PlugMan::Plugin
In: src/PlugMan.rb
Parent: Object

A class to hold a plugin‘s definition. Objects of this type should only be created using PlugMan.define.

In fact, dealing directly with this class shouldn‘t happen much at all and most dealins with the plugin framework will be through the PlugMan class and the plugins themselves.

Each plugin has the following fields that are useful to programmers using the plugin framework in figuring out how plugins interact with eachother:

 * name - plugin name, set automagically by PlugMan.define param, will be a symbol.
 * author - plugin author.
 * version - plugin version.  Only latest version of a plugin can be active. "1.2.3"
 * extends - extension points this plugin extends { :parent_plug => [:extpt1, :extpt2], parent_plug2 => [:extpt3] }
 * requires - the plugin that contains the extension point this plugin extends
 * extension_points - extension points defined by this plugin [:ext_a:, :ext_b]
 * params - parameters to pass to the parent plugin { :param1 => "abc", :param2 => 123 }
 * state - :started, :stopped, :error

These can be set using methods magically provided by the PluginMeta module. e.g. to get the author, use (no arguments):

  Plugin.author

and to set the author, use (single argument):

  Plugin.author "A. Uthor"

An example of how trivial a plugin definition is is shown below, a make-believe preferences plugin for a GUI app is being defined (this should be in a file ./plugins/some_subdir/preferences.rb):

  PlugMan.define :preferences do

    # define plugin metadata
    author "Aaron"
    version "1.0.0"
    extends(:menu_bar => [:menu_item], :tool_bar => [:tool_item])
    requires [:widget_factory]
    extension_points [:preference_item, :preferences_open, :preferences_close]
    params(:menu_tree => "View", :menu_text => "Preferences",
      :tool_tip => "Shows the preferences dialog.")

    def do_menu_action
      do_action
    end

    def do_tool_action
      do_action
    end

    def do_action
      ...
    end
  end

In the above example, the plugin will be discovered by the menu_bar and tool_bar plugins because this plugin is defined as extending those plugins at their extension points. It should be noted that the plugins being extended define the interface for each of those extension points (this is a soft contract and is not enforced in the plugin architecture.)

This plugin also requires the widget_factory plugin, but it won‘t be discovered by widget_factory in the same manner as the extensions. A "requires" plugin is a definite and known plugin that is required for this plugin to perform its tasks. In this case, the preferences plugin is relying on a service of the widget_factory plugin (presumably for obtaining widgets!) widget_factory can exist happily without the preferences plugin, but preferences will not work if widget_factory is not available.

The preferences plugin also defines some extension points that other plugins can use. At runtime, the preferences plugin asks PlugMan for all the plugins that extend its extension points and invokes a contract method on each. This preferences plugin does not know anything about the connected plugins other than they implement a particular method. By having this extension point mechanism, the application can define various specialty preference plugins that suit particular needs in the system. e.g. a new product feature, implemented as plugins, may be an FTP client and this client will make use of the extension points defined in the preferences plugin to make use of the applications preferences interface.

Parameters can also be passed from a plugin to its parent. The preferences plugin tells its parents application information about the plugin (i.e. not plugin metadata) that may be useful. Once again this is a soft contract and it is the responsibility of the plugin author to document the parameters required for extensions to define.

Methods

define_meta_field   dirname   new   new   start   stop  

Attributes

state  [RW]  The state of the plugin. Values can be :started:, :stopped, :error

Public Class methods

Allow plugins to specify metadata fields w/ magic

Should not be called directly, use PlugMan.define instead.

Public Instance methods

The base dir name that the plugin was loaded from

start the plugin. If a plugin needs to perform some specialised startup processing, it should override this method.

stop the plugin. If a plugin needs to perform some specialised stop processing, it should override this method.

[Validate]