> WebRSH: Help: Extending WebRSH's Functionality:
WebRSH is designed to be highly configurable and extensible. There are many ways of extending its functionality. Two specific mechanisms that have been implemented for that purpose are dynamically parsed HTML pages and WebRSH's plugin architecture.

Dynamically parsed HTML pages

This is a mechanism which allows for extending WebRSH's functionality without having to write any additional Perl code or to modify any of WebRSH itself. WebRSH's online help pages are implemented using this mechanism. It can also be used for many other things, such as for creating menus with various command links.

The two main things to note about dynamically parsed HTML pages are:

  1. They must reside in WebRSH's 'htm' directory. This is the 'htm' subdirectory of the 'Main Program Directory'.
  2. They are simply HTML pages which may contain certain special strings. These strings will be replaced (when the page is appropriately called through WebRSH) by values of appropriate WebRSH variables. This enables such pages to always have the appropriate WebRSH look and feel, and also to contain links and form fields that would be dynamically updated with appropriate current values.

The general format for the special dynamically replaced strings is <!$VariableName!> where $VariableName can be any of
$BGColor, $BodyParam, $TableColor, $FTableParam, $TableParam, $ScriptUrl, $SendFilesUrl, $counter, $id, $lpwd, $plpwd.
The definitions and proper usage of these variables can be determined by looking at the main WebRSH script and at some of the existing pages in the 'htm' directory.

Once an HTML page is located in WebRSH's 'htm' directory, it can be invoked as a dynamically parsed HTML page by using the command:
rshgethtm <htmname>
(which can be issued by an appropriate link) where <htmname> is the name of the file. WebRSH's Main Form is being appended to such pages, such that they appear as an integrated part of it.

WebRSH ships with one specific dynamically parsed HTML page that can be invoked from WebRSH's Main Menu and provides a natural place for adding command links. This is the 'more.htm' page in the 'htm' directory, which is invoked through the 'MORE' link in the Main Menu.


Plugins

WebRSH plugins are simply CGI Perl programs that can be integrated with WebRSH. In principle, CGI programs written in other languages can also be used, but they would need to be "wrapped" in a Perl script. The plugin mechanism can be used to:

  1. Integrate existing programs into WebRSH.
  2. Extend WebRSH without needing to make any changes to the core WebRSH code or know too much about how it works.

There are three main things to note about plugins:

  1. Almost any CGI Perl script can be used as a plugin. (Namely, WebRSH's plugin API is simply CGI). The main restriction is that plugins should refer back to themselves using the environment variable 'SCRIPT_NAME'. Well-designed CGI programs should be doing that anyway. Another restriction is that plugins should not modify certain WebRSH variables, but the chance of any independently written program doing that by accident is very small.
  2. Plugins are enabled by placing them in appropriate directories, after which they can be invoked with an appropriate URL. No changes to WebRSH or any of its files are needed.
  3. Plugins MAY use various portions (variables, subroutines, etc.) of WebRSH, and they do not NEED to be usable as stand alone CGI programs. It is recommended (although not necessary for strict functionality) that plugins would at least use some of the variables that control WebRSH's look and feel (such as the background color) in order to provide similar look and feel.

So, if plugins are simply CGI programs, what is the point in making them plugins in the first place?

There are a number of advantages to doing that. In particular:

Let us now describe the plugin architecture in more detail. There are actually two kinds of plugins. The first kind are 'library plugins' which must reside in WebRSH's 'lib' directory (the 'lib' subdirectory of the 'Main Program Directory'). The second kind are 'user plugins' which must reside in WebRSH's 'Plugin Directory'. The 'Plugin Directory' may be set to be the same as the 'lib' directory, but it can also be moved elsewhere if desired or needed. The idea of having these two kinds is that scripts whose main purpose is to be integrated parts of WebRSH should be implemented as 'library plugins', while self contained programs that are merely being used as plugins should be implemented as 'user plugins'. Also, with a system-wide install of WebRSH, system-wide plugins can be implemented as 'library plugins' and be located in a central 'lib' directory, while users can have private plugins in their own private plugin directories. Both kinds of plugins are simply CGI programs and have essentially the same requirements and capabilities. There are some mild differences in how the two kinds are being invoked (see below), and in the way they get executed by WebRSH. More specifically, 'user plugins' are being launched from the directories in which they reside (since many CGI programs expect that), and also the Perl $0 variable (which holds the identity of the currently executed script) is being set for them such that they know who they are if they need to. 'Library plugins', on the other hand, get launched from whatever directory the server is launching the main WebRSH script from, and have their $0 variable set to this WebRSH script. The main implications of all this are:

  1. 'library plugins' should not require being launched from the directory in which they reside.
  2. In order to run 'user plugins', the user running WebRSH must be able to make the 'Plugins Directory' a working directory (namely, he must have the appropriate level of permissions to do so).

Once a plugin is located in its appropriate directory, it can be invoked by specifying an appropriate URL. This URL should be formatted as follows:

The natural way of invoking plugins is through appropriate dynamically generated links which can be placed in dynamically parsed HTML pages. The 'more.htm' page in WebRSH's 'htm' directory (which is invoked by the 'MORE' link in WebRSH's Main Menu) is a natural place. Alternatively, it is also possible to modify the main WebRSH script and/or the menu file of the 'Frames Interface' and add such dynamically generated links there (links to plugins in the menu file of the 'Frames Interface' should be generated with the 'MakePluginLink(*)' JavaScript function).