The "example" plugin is complete illustrating all features : https://forge.indepnet.net/repositories/show/example

The "room" plugin is not complete, but very simple : https://forge.indepnet.net/repositories/show/room

Linux-Mag Publication (in French) : http://www.maje.biz/downloads/glpi-plugin.pdf

How to write a plugin for GLPI ?

The plugin appears as a folder to add in the GLPI directory tree plugins.
This folder will contain all of the php files (and images). In short, everything that relates to the plugin.

This directory name must only contain alphanumeric characters (no - _ . etc)

A plugin will never modify the table structure of GLPI, it merely adds tables to the MySQL database to manage its own data. Existing GLPI tables can be read from and written to via the core GLPI API.

Coding Conventions

1. Table Names

  • Your table names must follow the rule : glpi_plugin_<plugin_name>_XXXX
  • If you are using dropdown tables (list of values) they must follow the rule : glpi_dropdown_plugin_<plugin_name>_XXXX

2. Directory Structure :

  • "locales" : contains dictionaries
  • The dictionaries must be named : fr_FR.php / en_GB.php
  • "docs" : contains documentation
  • Readme.txt, Lisezmoi.txt, Roadmap.txt, Changelog.txt
  • "inc" : contains classes and functions
  • Files containing functions should follow the rule: plugin_<plugin_name>.db.function.php
  • Files containing classes should follow the rule : plugin_<plugin_name>.db.class.php
  • "front" : contains forms
  • Filenames should follow the following rules :
  • for forms that create/edit an object : plugin_<plugin_name>.<object>.form.php
  • for forms that display an object : plugin_<plugin_name>.php
  • "pics" : contains images
  • "ajax" : contains everything necessary for AJAX functionality
  • Files in the GLPI root directory :
  • Required :
  • hook.php
  • setup.php
  • Optional
  • index.php
  • If your plugin needs to create temporary files :
  • They must be created in GLPI_ROOT/files/_plugins/<plugin_name>.
  • The directory GLPI_ROOT/files/_plugins/<plugin_name> must be created when installing the plugin and should be removed when the plugin is removed

3. Class and Function names

  • Classes should follow the CamelCase pattern : class Plugin<Plugin_name>Xxxx (example : PluginExampleDisplay)
  • The functions out of the classes should follow the under_scores pattern: function plugin_<plugin_name>_<function> (example : plugin_example_getType())

4. Look and feel of the plugin :

In order to have a consistent look and feel throughout GLPI, it is best to reuse the classes of formatting already defined and used in GLPI.
You will find all of these definitions in the CSS file of GLPI.

Thank you for following these CSS rules, as it will help integrate the plugins and future developments.

Before you begin

  • Useful tips :
sql-mode        = STRICT_ALL_TABLES

and restart MySQL)

File structure for plugins and GLPI hooks

  • If a plugin is not installed, none of the files are loaded
  • When installing setup.php and hook.php are loaded

The process of instaling and deinstalling a plugin are managed by the GLPI core. It calls functions defined in the file hook.php

See detailed explanation of files :

Localization

All of the plugin data to be displayed in GLPI must be saved in a file. This allows easy translation, but just translating a file.
The language files are located in the "locales" directory
The convention for naming a language file is the same as GLPI and uses standard i18n. For example :
  • fr_FR for French (France),
  • nl_NL pour for Dutch
  • nl_BE pour for Flemish
  • en_GB pour for British (England)

Inside the file, the labels are all stored in a table such as the following :

$LANG['<plugin_name>']['title'][0] = "my title";
$LANG['<plugin_name>']['myplugin'][1] = "text 1";
$LANG['<plugin_name>']['myplugin'][2] = "text 2";

The files must use UTF8 encoding

The language file corresponding to the current language of the user will be dynamically loaded.
If GLPI is unable to load the current language of the user, then it will use the default languages of English or French.

Other Interactions

Adding Javascript and CSS

You can add custom JavaScript and CSS files using the following syntax :

$PLUGIN_HOOKS['add_javascript']['<plugin_name>']="FILENAME.js";
$PLUGIN_HOOKS['add_css']['<plugin_name>']="FILENAME.css";

Using the GLPI API

Skeleton of a page in GLPI

At a minimum, a PHP page included in GLPI, or one of its plugins, must contain :
  • constant GLPI_ROOT containing the path to the root of GLPI
define('GLPI_ROOT', '../..');
  • includes the
include (GLPI_ROOT."/inc/includes.php");

if you want to use the features of objects, GLPI must be defined before the inclusion of /inc/define.php, a $NEEDED_ITEMS table listing the functions of objects GLPI to load (The name is the name of the file in the GLPI "inc" directory without .class.php at the end.)
Example :

$NEEDED_ITEMS=array("search");

It then contains the following call :

The function commonHeader displays the GLPI header page, including menu.

The function commonFooter displays the default footer.

Other displays are the top between the function commonHeader and commonFooter.

For example : https://forge.indepnet.net/repositories/entry/example/trunk/index.php

Special case for posts and forms

  • The function glpi_header redirects to another page. It takes as parameters the URL of the target page.
  • Put all of the includes in the file hook.php, which allows the function usePlugin(<plugin_name>, true) to load all the plugin files. This helps limit excessive includes in the file setup.php.

Using CommonDBTM

If you set a new type, you must also define the class associated with the new type.
It must inherit from the class CommonDBTM which allows direct database abstraction.
The minimum type definition is :

class PluginExample extends CommonDBTM {
    function plugin_example () {
        $this->table="glpi_plugin_example";
        $this->type=PLUGIN_EXAMPLE_TYPE;
    }
};

For more information on the functions you can override, the documentation for the class is here :
https://forge.indepnet.net/embedded/glpi/classCommonDBTM.html