1. Les bases : structure 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 INI :
author="Auteur du module"
author_mail="Adresse email de l'auteur"
author_website="Lien vers la page de l'auteur"
version="Version du module"
date="Date de création sous forme : JJ/MM/AA"
compatibility="Version minimum de PHPBoost compatible avec le module. Exemple : 4.1"
admin_main_page="Chemin vers la page d'administration principale du module"
admin_menu="Choix de l'endroit où le menu doit apparaître dans l'administration. Vous avez le choix entre : index|administration|tools|members|content|modules"
home_page="Chemin vers la page principale du module"

D'autres choix sont disponibles :
Code INI :
php_version="Version de PHP minimum pour exécuter le module. Exemple : 5.5"
repository="Lien vers le fichier XML de mise à jour s'il y en a un"
contribution_interface="Chemin vers la page de contribution du module"



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 PHP :
 
/*##################################################
 *                           PageName.class.php
 *                            -------------------
 *   begin                : [Date]
 *   copyright            : (C) [Year] [Author]
 *   email                : [author mail]
 *
 *
 ###################################################
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 ###################################################*/
 

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 2766 fois