delete_me2Add my vote for this tag create new tag
, view all tags

DOCUMENTATION from this topic is located in: TWiki.TWikiPlugins

The current plugin installation requires some manual steps. The word "Plugin" implies that you simply plug a connecter (e.g. Perl module) into a socket (e.g. directory) and that's all there is to get things rolling. We would make it much easier for the TWiki users if we change the spec to do that.

Potential issues / spec changes:

  • Plugin is not compilable or is not compatible and renders TWiki inoperable.
    • Solution: We already have the $disableAllPlugins emergency break in TWiki.cfg.

  • Plugins need to be enabled by the ACTIVEPLUGINS preferences variable.
    • Solution: Turn it around by enabling all plugins that are not specifically excluded by a DISABLEDPLUGINS preferences variable.

  • Plugin specific variable are now defined as PLUGINNAME_PARAM preferences variables.
    • Solution: Allow plugin variables in the plugin topic and offer a getPluginVariable sub in TWiki::Plugins

  • How to install a plugin just for a web.
    • Solution: Possible with DISABLEDPLUGINS preferences variables on system level and web level.

  • How to add a plugin description bullet at the end of the TextFormattingRules. Currently a manual step.
    • Solution: The plugin handler asks each plugin for the description and composes a %PLUGINDESCRIPTIONS% variable used by TextFormattingRules.

-- PeterThoeny - 23 Jun 2001

Sounds like a great idea. Only bit I wasn't sure about was the plugin just for a web. If DISABALEPLUGINS is set at the system level, presumably you need an ENABLEPLUGINS at the Web level.

-- JohnTalintyre - 23 Jun 2001

Example: You want the XyzPlugin only for the Test web.

-- PeterThoeny - 23 Jun 2001

Hmm. But, that means if you then disable AbcPlugin in TWiki.TWikiPreferences you then get it enabled in Sandbox.WebPreferences without meaning to.

-- JohnTalintyre - 23 Jun 2001

  • non-compilable plugins:
    • TODO: when the "use ...Plugin;" step of the initialization fails, the plugin should be just disabled
  • not compatible plugins:
    • in our plugins the initialization step should checks that all needed pieces are OK before returning "1"
  • Plugin specific vars:
    • if we move plugin variables to the plugin topic then we loose the per-web configurability, and moreover, the page must be protected (e.g. by the TWikiAdminGroup)
    • [ PeterThoeny ] - I think this is a small price to pay for what we gain.
  • Plugin activation: we surely need a "discovery" mechanism (e.g. an %INSTALLEDPLUGINS% variable) that shows all plugins found in the lib::TWiki::Plugins directory. This would also automagically link all plugin documentation pages. (I don't have an opinion now on the automatic activation process, I should think to it)
    • [ PeterThoeny ] - The installed plugins could be shown by a %INSTALLEDPLUGINS% variable, but not sure what this is for besides for debug.
  • I like the idea to have all plugins automatically described once configured, let do it! I suggest some kind of getDescription() that returns a list (or hash) containing:
    • the one-line plugin description (good for tooltips also)
    • the syntax usage description (as it is now in TextFormattingRules)
    • an example of usage
      • it can be escaped with <verbatim> if it has to be shown
      • it can be "executed"
    • how the example is rendered if the plugin is correctly installed
      • [ PeterThoeny ] - I suggest KISS, all plugin specific description should go into the plugin topic, the only content that is needed outside is a bullet with a one line description that gets automatically added to the plugins section of the TextFormattingRules topic. How:
        • The plugin handler extracts the one line description from all initialized plugins and composes a bullet list of all plugins that have a non empty one line description. Example text in AbcPlugin topic:
          | One Line Description: | Short description here. |
          Example bullet based on above text:
          • AbcPlugin: Short description here.
        • The %PLUGINDESCRIPTIONS% variable is set to the bullet list, and the TextFormattingRules topic displays the variable.

    • NOTICE that all the above info could
      • either be collected from the plugin's topic
      • or (the reverse) to be in the code (pod format?) and fill up all plugin's topic holes
        • [ PeterThoeny ] - I suggest the former one so that all description is in one place.

-- AndreaSterbini - 25 Jun 2001

To summarize, I suggest below changes with KISS, performance and compatibility with existing plugins in mind:

  • Remove ACTIVEPLUGINS preferences variable and replace by DISABLEDPLUGINS so that installed plugins can be excluded.

  • Remove the PLUGINNAME_VAR preferences variables and replace by * Set VAR = value settings in the Plugin topic.

  • The Plugin module does this at init time:
    • Load all non-disabled plugin modules that are compilable.
    • Build preferences variables out of * Set VAR = value settings of plugin topics of all non-disabled plugins. To avoid name clashes, the variable name is prefixed with the capitalized plugin name. Example: The AbcPlugin has * Set COLOR = red defined, so the preference variable is %ABCPLUGIN_COLOR%).

  • The Plugin module does this in commonTagsHandler:
    • Handle the %PLUGINDESCRIPTIONS% variable: Build it from %<plugin>_SHORTDESCRIPTION% preferences variables of all non-disabled plugin topics.

-- PeterThoeny - 06 Jul 2001

The first enhancement is in TWikiAlphaRelease: The plugin preferences moved from TWikiPreferences to the individual plugin topics, and the %PLUGINDESCRIPTIONS% variable is automatically expanded to a bullet list with a short description of all plugins.

There is a small spec change needed to make it consistent with preferences variables: The "One line description" table row in the plugin topic needs to be replaced with a preference variable like this:
   * Set SHORTDESCRIPTION = Blah blah....

See the example in Plugins.DefaultPlugin

To do: Load all plugins unless disabled.

Question to a Perl expert: In order to load all plugins automatically I need to get the actual plugin directory. Is there are way to find out the full path of the current module, i.e. TWiki::Plugins?

-- PeterThoeny - 09 Jul 2001

I dont know about the full path. But, you can get the relative path by using caller e.g.

my ($package, $filename, $line) = caller;

A call from one sub in TWiki.pm to another could get the relative path for TWiki.pm, then sub Plugins for that.

-- JohnTalintyre - 13 Jul 2001

I figured out how to get the list of all *Plugins.pm files:

  • Find out the absolute location of TWiki.pm based on the @INC variable (done in new sub &TWiki::getTWikiLibDir())
  • Read all plugin module files relative to the TWiki lib dir.

The plug & play mechanism for plugins is now finished. Changed spec:

  • All plugin modules that exist in the lib/TWiki/Plugins directory are activated automatically unless disabled by the DISABLEDPLUGINS preferences variable. You can optionally list the installed plugins in the INSTALLEDPLUGINS preferences variable. This is useful to define the sequence of plugin execution, or to specify other webs then the TWiki web for the plugin topics. Settings in TWikiPreferences:

  • The %ACTIVATEDPLUGINS% variable shows all currently activated plugins. This variable is shown in TWikiPreferences for debug reasons.

  • Search order for plugin webs: Use full web.topicname name if specified in INSTALLEDPLUGINS, else look in the TWiki web, then the Plugins web, then the current web.

  • Plugin specific settings are done in individual plugin topics. Two settings are standard per plugin:
    • One line description, is included in the TextFormattingRules topic:
      • Set SHORTDESCRIPTION = Blah blah.
    • Debug plugin, set 0 or 1: (See output in data/debug.txt)
      • Set DEBUG = 0

  • The %PLUGINDESCRIPTIONS% variable shows a bullet list with description of all currently activated plugins. This variable is based on %<plugin>_SHORTDESCRIPTION% preferences variables of individual topics and is shown in TextFormattingRules.

It is recommended to update the existing plugins, however they do run without changes. In case you don't you will not get the automatic description in TextFormattingRules. Update is recommended because plugins may only use functions in &TWiki::Func module (see OfficialCoreSubsForPlugins).

Latest changes are now in TWikiAlphaRelease and TWikiBetaRelease, but not yet at TWiki.org.

-- PeterThoeny - 14 Jul 2001

On the automatic activation of plugins, it seems to me that you have replaced one PITA by another. In my case I rather have the problem of activating every plugin in each web so that I can control what executes where, or even just activate them in the Test web so that I can have some idea of performance/usability/features, so under this scheme after I install the plugin, I have to go to every web preferences page, and deactivate the plugin, so that I can test it, and after testing is done I have to go back to those webs that I want to have it active on.

The previous scheme allowed each web administrator to decide what would run, now it's in the hands of the main twiki admin.

At the very least a TWiki.cfg variable should be set so that this automatic activation is optional, or to list those plugins that are "under test" and should not be globaly activated.

A simple analogy is in the ALLOWTOPICCHANGE DENYTOPICCHANGE variables, we have both of them, wouldn't it be easier to just list everybody that we don't want to be able to edit the topics???? ---- not!!!.

-- EdgarBrown - 17 Jul 2001

There was a good reson for the spec change: Plug & play is convenient and reduces errors in configuration. (Parallel port vs. serial port analogy; did you know what RS-232 stands for? 232 possible ways of configuring something incorrectly...)

For testing new plugins you can do one of the following (the former one I use at work) :

  1. Have a production and a test installation of TWiki. The twiki/data, twiki/templates and twiki/pub directories are shared, and the twiki/bin and twiki/lib directories are separate. Do all tests of plugins and other parts in the test installation. Once satisfied that everything works as expected copy the modified files over to the production installation. That way you can update a live TWiki installation and users won't even notice it.
  2. List the plugin under test in the DISABLEDPLUGINS variable of the TWikiPreferences. Redefine the DISABLEDPLUGINS variable in the test web and do the testing there.

-- PeterThoeny - 17 Jul 2001

I've tried the new auto-plugin and really like it. One thing that tripped me up was a plugin, the DefaultPlugin, not having a plugin topic, hence it wasn't enabled. I've changed my source to call writeWarning in this instance, will upload to CVS.

-- JohnTalintyre - 18 Jul 2001

I may have missed seeing this, but I have a couple of ideas wrt plugins:

  • Have an api "getVersion" and if the TWiki version isn't compatible, the plugin unplugs itself. In like vein, if a plugin returns an error (perhaps based on some threshold), TWiki unplugs it, adds it to the disabled plugins list (to prevent repeated emails) and sends mail to the webmaster for his/her attention.

  • %PLUGINS% should cascade like most (all?) TWiki variables and be overridable or finalizable at any level. This answers the problem of having to configure plugins in every web and also offers tailoring plugin availability for different webs.

-- DavidLeBlanc - 24 Aug 2001

Edit | Attach | Watch | Print version | History: r18 < r17 < r16 < r15 < r14 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r18 - 2001-09-18 - MikeMannix
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.