gtd-php Documentation | Developers / The gtd-php Programming Interface

Add-ons all reside in the addons directory. The package scans this for sub-directories at the start of each session, and upon entry to the preferences screen. Directories with names starting with a '.' are ignored.

The addon can optionally include a file description which contains a single line of text describing the addon. This text will be shown in the preferences screen, to guide the user as to the purpose of the addon.

Configuration file

The add-on should include a file setup.inc.php which specifies the configuration. This file is processed at the start of each session, and upon submitting the preferences form.

There are two categories of add-on: those that add new menu items, and those that change the behaviour of core pages. These two categories are explained below, and in each case, the explanation starts with an example configuration file.

New menu items

file: setup.inc.php:

<?php
$events[_GTD_ON_MENU]['*']=array(
    'link'   => "achievements.inc.php",
    'title'  => 'Notable Achievements',
    'label'  => 'Achievements',
    'where'  => 'listItems.php?type=*&amp;tickler=true&amp;liveparents=*',
    'when'   => 'after',
    'options'=> array('jpgraphdir'=>'../jpgraph/')
);

The file should be of this format:

<?php
$events[_GTD_ON_MENU]['*']=array(

link is the add-on file to be called, which should be in the relevant addons sub-directory. NB the entry in setup.inc.php should not include the path.
title is the text that will appear in the tooltip if the user hovers the mouse over the menu item, and should be a fuller explanation of the menu item's purpose
label is the text that will appear in the menu
where is the full link text of the existing item next to which the new item should appear
when can be either 'before', 'replace' or 'after' to indicate whether the new item should appear before the item indicated by where, instead of it, or after it, respectively.
options are passed on directly into the addon when it is executed.

The file should end by closing the array:

);

Within the scope of the included file, the $addon array stores information on the addon. It has the following key/value pairs:

id is the registered identity of the addon
dir is the directory containing the addon files, and is of the form: ./addons/{id}/
_GTD_ON_MENU.'-*' contains the options element from the $events array specified in setup.inc.php. So, for example, if in that file you have:
```
$events[_GTD_ON_MENU]['*']['options']=array('jpgraphdir'=>'../jpgraph/');
```
then within the scope of the execution of the addon,
```
$addon[_GTD_ON_MENU.'-*']
```
will contain
```
array('jpgraphdir'=>'../jpgraph/')
```
urlprefix is the path to use if you need to link to other files within your addon. For example, in the achievements plugin, the file graph.php is used to generate an image: this is linked using:
```
<img src="{$addon['urlprefix']}graph.php" />
```

Changing the behaviour of core pages

file: setup.inc.php:

<?php
$events[_GTD_ON_HEADER]['*']         ="insertjs.inc.php";
$events[_GTD_ON_DATA]  ['itemReport']="modifydata.inc.php";

The structure of each line is:

$events[{trigger}][{existing page}]={add-on file};

trigger can be _GTD_ON_HEADER, _GTD_ON_DATA or_GTD_ON_FOOTER, and indicates the point during page generation at which the add-on code should be injected
existing page indicates which page should be modified, and should exclude the '.php' suffix. Use the asterisk, '*', to indicate that the code should be injected into all pages
add-on file is the full name of the file to be injected, from the relevant addons sub-directory. Note that the filename here should not include the path.

The code to manage these injections is in the gtd_handleEvent function, in gtdfuncs.inc.php

Within the scope of the included file, the $addon array stores information on the addon. It has the following key/value pairs:

id is the registered identity of the addon
dir is the directory containing the addon files, and is of the form: ./addons/{id}/