Créer un module

1. Les bases : structure du module

Dernière mise à jour : 30/06/2024 à 18h18
Table des matières
  1. Création du dossier du module
  2. Mise en place des sous-dossiers
  3. Création du fichier de configuration : config.ini
  4. Copyright
  5. Mise en place des langues du module
    1. Création du fichier de description du module : desc.ini
    2. Création du fichier de langue du module : common.php
  6. Mise en place du Générateur d'urls
  7. Mise en place de la page d'index du module
  8. Les images du module
Nous allons voir les bases de la création d'un module à travers cet article.

Création du dossier du module







Dans un premier temps, il va falloir créer un dossier à la racine de PHPBoost contenant tous les fichiers du module.

Le choix du nom du dossier est important puisqu'il sera l'identifiant du module mais sera également présent dans les différentes urls.

Il est préférable de choisir un nom anglais pour rester cohérent avec le reste de PHPBoost.

Par exemple pour un module dictionnaire, il conviendrait parfaitement de choisir dictionary.

Mise en place des sous-dossiers







Plusieurs dossiers sont à créer dans le dossier de votre module :

  • controllers : contiendra tous les contrôleurs permettant d'afficher vos différentes pages.
  • lang : contiendra les dossiers de langue de votre module.
  • phpboost : contiendra le gestionnaire d'extensions et les différentes extensions qui permettent l'interaction entre modules.
  • services : contiendra les services liés à vos objets, les différentes actions vers la base de données et la définition des autorisations du module.
  • templates : contiendra tous les templates de vos différentes pages.
  • util : contiendra les fonctions utiles du module, comme le générateur d'urls et la définition des liens du menu du module dans l'administration.



Création du fichier de configuration : config.ini







Le fichier config.ini contient toutes les informations relatives au module, à l'exception de son nom et de sa description, qui seront placés dans les dossiers de langue.

Il faut créer ce fichier à la racine du module.

Celui-ci doit contenir au minimum les informations suivantes :
Code EXEMPLE : 
addon_type             = "module"
author                 = "Nickname"
author_mail            = "nickname@email.com"
author_website         = "https://www.phpboost.com"
date                   = "2013/13/07"
version                = "5.2.0"
compatibility          = "5.2"
admin_menu             = "modules"
home_page              = "index.php"
admin_main_page        = "index.php?url=/admin"

Code EXPLICATION : 
addon_type             = "module"
author                 = "Auteur du module"
author_mail            = "Adresse email de l'auteur"
author_website         = "Lien vers la page de l'auteur"
date                   = "Date de création sous forme : AAAA/MM/JJ"
version                = "Version du module"
compatibility          = "Version de PHPBoost compatible avec le module"
admin_menu             = "Choix de l'endroit où le menu doit apparaître dans l'administration. Vous avez le choix entre : administration|tools|members|content|modules"
home_page              = "Chemin vers la page principale du module"
admin_main_page        = "Chemin vers la page de configuration du module"


D'autres choix sont disponibles :
Code EXEMPLE : 
contribution_interface = "index.php?url=/add"
php_version            = "5.6"
enabled_features       = "comments, notation, newcontent"
repository             = "https://dl.phpboost.com/unofficial_modules.xml"
rewrite_rules[]        = "RewriteRule ^...."

Code EXPLICATION : 
contribution_interface = "Chemin vers la page de contribution du module"
php_version            = "Version minimum de PHP nécessaire pour executer le module"
enabled_features       = "Liste des addons disponibles sur le module. Choix multiple : comments, notation, newcontent. "
repository             = "adresse du fichier xml du repository pour les mises à jour"
rewrite_rules[]        = "Règles de réécriture"








Insérez un copyright dans toutes les pages php de votre module. Celui-ci doit être de la forme suivante (remplacez les différentes valeurs par ce qui convient dans l'entête) :

Code EXEMPLE : 
/**
 * This the config file of the module
 * @copyright   © 2005-2019 PHPBoost
 * @license     https://www.gnu.org/licenses/gpl-3.0.html GNU/GPL-3.0
 * @author      Firstname LASTNAME <nickname@email.com>
 * @version     PHPBoost 5.2 - last update: 2019 01 01
 * @since       PHPBoost 3.0 - 2012 06 25
 * @contributor Firstname LASTNAME <nickname@email.com>
*/

Code EXPLICATIONS : 
/**
 * Courte description du fichier (optionnelle et SANS le tag @desc qui n'existe plus)
 * @copyright   dates d'existence de PHPBoost et nom des ayants droit
 * @license     adresse et nom de la licence du fichier
 * @author      nom et email de l'auteur du fichier
 * @version     dernière version de PHPBoost compatible avec le fichier - date de dernière mise à jour du fichier (à modifier à chaque modification du fichier)
 * @since       version de PHPBoost lors de la création du fichier et date de création du fichier 
 * @contributor nom et email de tout contributeur sauf s'il en est l'auteur
*/


Vous pouvez aussi utiliser une autre licence de la GPLv3 du moment qu'elle soit compatible GPLv3

Mise en place des langues du module







Dans le dossier lang, créez un premier sous-dossier : french. Nous allons y créer deux fichiers : le fichier contenant la description du module et le fichier de langue utilisé pour le module.

Les étapes suivantes peuvent être reproduites pour ajouter la langue anglaise (avec la création d'un dossier english) ou tout autre langue.

Création du fichier de description du module : desc.ini







Créez le fichier desc.ini dans le dossier french.

Celui-ci doit contenir (dans la langue concernée, français dans cet exemple) :

Code INI : 
name="Le nom de votre module"
desc="La description de votre module"


Création du fichier de langue du module : common.php







Nous allons mettre en place le fichier common.php qui sera utilisé dans les chapitres suivant. Commencez par y indiquer le nom de votre module (en remplaçant ModuleName par le nom de votre module) comme suit :

Code PHP : 
 
<?php
//Insérer le copyright ici
 ####################################################
 #French  #
 ####################################################
$lang['module_title'] = 'ModuleName';
?>
 


Mise en place du Générateur d'urls







Le générateur d'urls est utilisé pour éviter de réécrire à chaque fois chaque url. Il suffira d'appeler une de ses méthodes lorsqu'il est nécessaire de renvoyer vers une url ou d'afficher une url.

Créez le fichier ModuleNameUrlBuilder.class.php dans le dossier util de votre module.

Nous allons y placer deux méthodes pour le moment : configuration() qui permettra de générer le lien vers l'administration du module et home() qui permettra de générer le lien vers la page d'accueil du module :

Code PHP : 
 
<?php
//Insérer le copyright ici
class ModuleNameUrlBuilder
{
private static $dispatcher = '/ModuleName';
/**
 * @return Url
 */
public static function configuration()
{
return DispatchManager::get_url(self::$dispatcher, '/admin/config');
}
/**
 * @return Url
 */
public static function home($param = '')
{
return DispatchManager::get_url(self::$dispatcher, '/' . $param);
}
}
?>
 


Mise en place de la page d'index du module







La page index.php permet de diriger l'affichage vers tel ou tel contrôleur en fonction de l'url appelée. Nous allons ici créer un premier lien vers le contrôleur d'administration du module si l'url de configuration est appelée. Pour mettre en place d'autres liens, il suffit d'ajouter d'autres UrlControllerMapper() dans le tableau. Il est préférable d'avoir des connaissances en regex pour définir au mieux les urls.

Code PHP : 
 
<?php
//Insérer le copyright ici
define('PATH_TO_ROOT', '..');
require_once PATH_TO_ROOT . '/kernel/init.php';
$url_controller_mappers = array(
//Admin
new UrlControllerMapper('AdminCalendarConfigController', '`^/admin(?:/config)?/?$`'),
);
DispatchManager::dispatch($url_controller_mappers);
?>
 


Les images du module







Deux images doivent être placées à la racine de votre module :

[list]

[*] ModuleName_mini.png qui doit être une image de 16 pixels de large et de long.

[*] ModuleName.png qui doit être une image de 32 pixels de large et de long.

ModuleName étant le nom du dossier principal de votre module.

A ce stade là, votre module sera visible sur la page d'ajout d'un module dans l'administration.
Cette page a été vue 9051 fois