Plugins for kOOL

With plugins you can accomplish small changes or enhancements withouth the need to change the code of kOOL itself.

Every plugin is stored in a separate folder which has the name of the plugin. In this folder there can be different files:

config.php	mandatory	Info about the plugin itself. Part of it is displayed in the tools module.
PLUGINNAME.php	mandatory	PHP file with the same name as the plugin. This is the file that will hold any code used in this plugin. See more about the naming conventions of the functions further down in this document.
locallang.php		LL file for strings used in this plugin. It is also possible to overwrite predefined values.
kota.inc		Extensions or changes to the KOTA array to add new db columns.
db.sql		SQL file to extend the kOOL database.
submenu.php		Add new submenu entries.

Install plugins

Plugins are stored in the web folder of each kOOL installation, so different installation can have different plugins with different version even. For now you have to manually copy the plugin into the plugins folder. Afterwards you will find the plugin listed in the tools module (as root) and that's where you can install them.

It is also possible to install the plugins manually by entering a line like the following in config/ko-config.inc:

$PLUGINS = array(
	array("name" => "leute_crdate", "type" => "leute")
);

„name“ stands for the name of the plugin, which is the same as the name of the folder in the plugins folder and „type“ specifies the type of the plugin. Type can be the name of any module or „global“. This specifies where this plugin should be included.

Plugin configuration in config.php

Some general settings about the plugin itself are stored In config.php.

$PLUGIN_CONF["leute_crdate"] = array(
	'title' => "Creation date for new people",
	'description' => "Adds a new column crdate to ko_leute that holds the creation date",
	'author' => "Renzo Lauper",
	'author_email' => "renzo@churchtool.org",
	'dependencies' => "",
	'conflicts' => "",
	'state' => "stable",
	'version' => "0.1",
	'type' => "leute",
);

If this plugins depends on other plugins, you can add a comma separated list of those in „dependencies“, the same holds for conflicts for plugins that can not coexist with this one.

Add entries in submenus with submenu.php

In order to add new entries in an existing submenu which enables the users to launch the new functionality, you can define new entries in submenu.php. To do this you can add an array $my_submenu:

$my_submenu[MODULE][SUBMENU_ID][output|link|html|show]

Here you see an example for the submenu „kg“ of the module „leute“:

$my_submenu["leute"]["kg"][] = array("output" => getLL(„my_ca_dienstliste_dienstliste“),
	"link" => "index.php?action=my_ca_dienstliste_dienstliste",
	"html" => "",
	"show" => "",
);

In this example a new entry is added to the submenu kg which will be called „Rota list“ and it will call the action „my_ca_dienstliste_dienstliste“. This action is not defined yet, that's why a new function has to be written to take care of this. Read more on how to do this further down in the chapter about hooks.

Localized strings for plugins: locallang.php

Add your localized strings for all languages in this file. You can do so for your own string, that are beeing used in this plugin, but you can also overwrite existing strings with new ones in this file. For the above example you see the contents of the locallang.php file here which defines strings for German and English:

$LL["de"]["my_ca_dienstliste_dienstliste"] = "Dienst-Liste";
$LL["en"]["my_ca_dienstliste_dienstliste"] = "Rota-List";

To prevent other users to use the same keys in this array you should prepend the keys with „my_NAMEOFPLUGIN_“.

Check out the global LL values in kOOL_lib/locallang/locallang.XY.php if you plan to overwrite some of them.

Hooks

Hooks in the code allow you to add or change functionality in specified areas. The following hooks exist in all modules. If you are in need of others, just speak up in the developers mailinglist and present your needs so new hooks can be added where needed.

The following table shows the possible hooks and the names of the functions to be used in your plugins:

my_action_handler_ACTION	Use this to add a new action handler for a new action set by a plugin. This will be called in the main switch($do_action) block if the appropriate action is set.
my_action_handler_add_ACTION	Add code to an existing action. This function will be called after the main switch($do_action) block.
my_show_case_CASE	Define a new show case in the main switch($_SESSION[„show“]) block. This enables you to render new content for a newly created action (see above), where you set the corresponding value in $_SESSION[„show“].
my_show_case_add_CASE	Add code to an existing show case in the main switch($_SESSION[„show“]) block.

Changes in the database: db.sql

If your plugin needs the change fields in the database or add new ones, you can define this in the file db.sql. You must not use ALTER commands but you must place everything in CREATE TABLE requests. Except for INSERT statements to add new content (for new filters) for example. Here you see an example to add a new field „my_res_address_address“ used in the plugin „res_address“.

CREATE TABLE ko_reservation (
 `my_res_address_address` text NOT NULL,
);

These SQL statements will be executed when you install this plugin in the tools module.

Changes to KOTA in kota.inc

After adding new database fields you will most probably include them into the forms in kOOL so the users can add data to these new fields. This is done by extending KOTA in a file kota.inc in your plugin's folder.

The following example adds the necessary entries to KOTA for the above mentioned plugin res_address:

$KOTA["ko_reservation"]["my_res_address_address"] = array(
	"post" => 'format_userinput("@VALUE@", "text")',
	"form" => array("type" => "textarea", "params" => 'cols="40" rows="4"')
	);

The new field in the table ko_reservation is defined to be of the type textarea to let the user enter their full address which will be stored with a reservation. For all the possible settings see the documentation about KOTA.

The localized values to label the new fields are taken from the LL array. So you must add entries in locallang.php file of your plugin following this scheme:

$LL[LANG][kota_TABLE_FIELD] = VALUE;

Where LANG stands for the language this value stands for, TABLE is the table where this field is added. In this example this would be ko_reservation. And finally FIELD stand for the name of the new field:

$LL["en"]["kota_ko_reservation_my_res_address_address"] = "Your postal address";
$LL["de"]["kota_ko_reservation_my_res_address_address"] = "Komplette Postadresse";

Examples

Sometimes it is easiest to learn from examples so get some plugins from www.churchtool.org and check them out.