Writing plug-ins

From ISPWiki

Jump to: navigation, search

Contents

Description

A plug-in should contain the following tags:

  • name - brief description of a plug-in;
  • description - detailed information about the functions a plug-in should perform, the interface elements that will be added, when it is active, and their location;
  • version - plug-in's version, normally figures, separated by a dot. You may use any number of dots. The versions are compared by comparing each part (dot separated) starting from the beginning. If symbols are used instead of figures, the part equals zero;
  • url - URL to the web page from which you can download the plug-in ;
  • lang - programming language that was used to write a plug-in. Possible variants are Perl, PHP, Python (the list may be enlarged, if necessary). If your plug-in does not need interpreters (if it is written in Shell or does not contain interpreters at all), you do not need to provide this tag;
  • langver - minimal version of the interpreter. If the tag is not present, the version will not be checked; the tag has the strict attribute, if it is yes, the strict version correspondence will be checked. If you plug-in is running Python 2.5 and 2.6., create two tags langver with strict="yes". Several versions of the interpreter are not supported, verification is started by the command, such as "python --version", if necessary, you can configure the server to start a required version by default;
  • require - modules that are required for a plug-in. The installer will check whether they are installed. If not, a user will be prompted to install them;
  • depend - name and version of a plug-in that is required for this plug-in, such as "libxxx 2.0". The version is optional; if any, the plug-in's version must not be earlier than a specified one;
  • manager - name of the software that will use this plug-in, such as ispmgr, billmgr. There can be several tags. Optional tag.
  • mgrver - version of the software that will use the plug-in, such as ISPmanager-Lite, ISPmanager-Pro 4.3. There can be several tags, if this type is not present, the plug-in is supposed to be used in all the versions. If a numerical version is provided, it will be checked according to the procedure described above;
  • os - operating system for which a plug-in will be used. You may provide a numerical version, such as Linux, FreeBSD-8. You can locate the current operating system the same way as the license information. You can use several tags;
  • author - information about the plug-in's author;
  • site - page that contains information about a plug-in. This can be a web-site, forum topic or blog;
  • contact - author's contact information. You may use any format.

All the tags are optional (except for manager), but we would recommend that you provide as much information, as possible. Following is the example of the plug-in

<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
<plugin> 
<name lang="ru">Massive password change</name>
<description lang="ru">Plug-in that can be used for massive password change. A new icon will be displayed on the user list; select the users whose passwords you want to change and click this icon.</description>
<url>http://download.ispsystem.com/plugins/plugins/masspasswdchange.tar.gz</url>
<version>1.0</version>
<lang>perl</lang>
<langver strict="yes">5.8</langver>
<require>XML-LibXML</require>
<require>DBD-mysql</require>
<require>Math-BigInt</require>
<manager>ispmgr</manager>
<author>John Ivanov</author>
<site>http://mysite.com/plugin1</site>
<contact>ICQ: 123; email:user@example.com</contact>
</plugin>
 tags that describe functionality of the plug-in
</mgrdata>

Plug-in's scripts

A plug-in can contain the following scripts:

  • preinstall - script to be called before installing a plug-in
  • postinstall - the script to be called after installing a plug-in
  • preupdate - script to be called before update
  • postupdate - script to be called after update
  • predelete - script to be called before deleting a plug-in

All the scripts must locate in var/.plugin_scripts/. The name's format - NAME_TYPE, where NAME is the name of a plug-in , TYPE is a script type, for example, apachestatus_preinstall.

Upon successful execution, the script will return 0.

If anything went wrong, the script will return another figure, and stdout will contain any message that will be shown to user.

Installation steps

After you have run the installation process, the following actions will be performed:

  • The plug-in will be uploaded to the server, the archive will be unpacked into a temporary directory.
  • The interpreter and its version will be checked
  • Required modules will be checked
  • The preinstall script will run
  • The plug-in's files will be copied into the control panel's directory, and the control panel will be restarted
  • The postinstall script will run

If one or several errors occurred during installation, the installation will stop, and all the plug-in's files will be removed. Please note, that in case of error the preinstall and postinstall scripts will be used to roll back the changes.

Updating plug-ins

Depending on the settings, the control panel can automatically install a new version, if any, or inform you that one is available.

Follow the steps described above to update, except for the plug-ins to be called. If you wish to update, preupdate and postupdate will be called. Please note, that if pstupdate returns an error, the plug-in will be deleted.

Choosing programming language

If you want to provide your plug-in to users, note, that either they may not have the interpreter you choose or it may be missing at all as well as have incompatible versions in different distributions of operating systems.

A bright example is Python. Versions 2.4, 2.5, 2.6 and 3.0 are not compatible. Different distributions use different default versions, some of them allow installation of another versions, but this causes installation problems. You can install a required interpreter and modules manually, but can you imagine how many user will agree to do this instead of clicking several buttons on the interface?

PHP - normally you won't have difficulties when using it; version 4 was used long ago. However, differences in versions 5.2 and 5.3 may cause some problems. We would recommend that you avoid using incompatible functions.

Perl - it is possibly the most stable interpreter; problems with scripts usage on different distributions were not encountered.

sh - is a good solution for uncomplicated handlers, which is included in all the systems and no additional packages are required.

All the information given above is not an author opinion, but the data based on plug-in's installation and usage statistics, bug reports and trouble tickets to technical support.

Was this helpful? Yes | No
Views
Personal tools