The anatomy of a KwaMoja plugin

As promised in my previous post regarding KwaMoja plugins, here is a tutorial on constructing a plugin.

Each plugin is a zip file. For this tutorial we will use the demo plugin that is available from http://www.kwamoja.com/demo_plugin.zip.

This demo takes the form of a standard "Hello World" type application, as used in most programming tutorials. The plugin will present the user with a text box asking for the users name. If that user has not used the plugin before from that IP address they will get a message saying "Hello John" or "Hello Jane" or whatever his or her name is. If they are returning, they will get a welcome back message.

If you unzip this file you will see it contains 5 files:

HelloWorld.php
HelloWorldDB.php
HelloWorldDBRemoval.php
HelloWorldLinks.txt
summary.xml

ALL KwaMoja plugins must have a summary.xml file. This is the file that tells KwaMoja how to install the plugin. Here is the xml contained in this examples summary.xml:

<plugin>
    <name>Demo Plugin</name>
    <installed>0</installed>
    <license>gpl</license>
    <scripts>
        <script>
            <name>HelloWorld.php</name>
            <pagesecurity>1</pagesecurity>
        </script>
    </scripts>
    <menulinks>HelloWorldLinks.txt</menulinks>
    <dbupdates>HelloWorldDB.php</dbupdates>
    <dbremoval>HelloWorldDBRemoval.php</dbremoval>
</plugin>

The first attribute is a descriptive name for the plugin. I have just called this one "Demo Plugin" .

The next attribute shows whether the plugin has been installed. KwaMoja will automatically set this to 1 when the plugin is installed. This should be set to zero when writing the plugin, and then never manually changed.

Then there follows the name of the license that this plugin is covered by. In this case, the GPL.

Next is an array of scripts that will be installed and a security token for each script. HelloWorld.php is a KwaMoja script. The plugin can contain any number of these scripts. In this simple example we only need the one, and I have given it a security token of one meaning any user can use it. I will go through this script and how to write a KwaMoja script in my next post.

The next attribute is called "menulinks" and contains the name of the file containing details of what new menu items are required to be added, and if any new modules are to be added to the menus. The full contents of this file for our example are:

$ModuleLink[] = 'Test';
$ReportList['Test'] = 'test';
$ModuleList[] = 'Test';

$MenuItems['Test']['Transactions']['Caption'][] = 'Hello World';
$MenuItems['Test']['Transactions']['URL'][] = '/HelloWorld.php';

The first three items on the list will setup a new module called "Test" to appear on the main menu. This is not obligatory. For instance if your plugin fits best in the Manufacturing module, then there is no need to have these lines. The next two lines are necessary for every script that you want the user to have access too via the main menu. These take the form of $MenuItems[Module][Section][Caption] and $MenuItems[Module][Section][URL] where "Module" is the name of the module, either one that you have just created or from the following list:

'orders', 
'AR', 
'AP', 
'PO', 
'stock', 
'manuf',  
'GL', 
'FA', 
'PC', 
'system', 
'Utilities'

The section is either "Transactions", "Reports", or "Maintenance" and determines whether the item appears in the left, centre, or right section of the menu. The Caption is the string that will appear in the menu, and the URL is the path to that menu, which must include a "/" at the beginning, as in "/HelloWorld.php".

Penultimately there is an attribute called dbupdates. This provides a link to a file containing the following:

<?php
CreateTable('helloworld',
"CREATE TABLE helloworld (
ipaddress char(13),
name varchar(30),
PRIMARY KEY  (`ipaddress`, `name`)
)", $db);

$SQL = "UPDATE www_users SET modulesallowed=modulesallowed+'1, WHERE userid='" . $_SESSION['UserID'] . "'";
executeSQL($SQL, $db);
?>

These are commands used to make any necessary changes to the database for your plugin to work. If it doesn't need any changes there should still be a file that just contains the <?php ?> tags in it. KwaMoja comes with an api to allow you to access the database, and facilitates the use of different DBMS's. You can find the functions here. The first call is to the CreateTable() function. Secondly there is some sql to update the users modulesallowed field and finally there is a call to the executeSQL() function to run this SQL.


The final attribute in the summary.xml file is called dbremoval. This is a reference to the file that contains the commands required to remove the database changes when the user uninstalls the plugin. Our demo file contains the following:

<?php
DropTable('helloworld', 'name', $db);

$SQL = "SELECT modulesallowed FROM www_users WHERE userid='" . $_SESSION['UserID'] . "'";
$Result = DB_query($SQL, $db);
$MyRow = DB_fetch_array($Result);

$SQL = "UPDATE www_users SET modulesallowed='" . substr($MyRow['modulesallowed'], 0, strlen($MyRow['modulesallowed'])-2) . "' WHERE userid='" . $_SESSION['UserID'] . "'";
executeSQL($SQL, $db);
?>
As you can see above, both the dbupdates and the dbremoval files can contain php code to verify information before updating the database.




So that is a simple KwaMoja plugin. This zip file can be imported into KwaMoja, and you can see and use this plugin directly from the menu.
The next post will cover actually writing the script.