Créer un module PrestaShop

Principes opératoires des modules

Les modules sont la meilleure manière de laisser votre talent de développeur et votre imagine s'exprimer, tant les possibilités créatives sont nombreuses.

Ils peuvent afficher une grande variété de contenus (blocs, texte, etc.), réaliser de nombreuses tâches (mise à jour groupées, import, export, etc.), créer une liaison avec d'autres outils...

Les modules peuvent être aussi configurables que nécessaire ; plus ils le sont, plus ils seront utiles, et donc capables de répondre aux besoins d'un plus grand nombre d'utilisateurs.

L'un des principaux intérêt des modules et d'ajouter des fonctionnalités à PrestaShop sans devoir modifier ses fichiers internes, rendant possible le fait de mettre la solution à jour sans devoir recopier toutes ses modifications.

De fait, vous devriez toujours éviter de toucher au fichier interne de PrestaShop lorsque vous concevez un module, même si cela peut être difficile dans certaines situations...

Arborescence des fichiers du module

Tous les modules PrestaShop sont installés dans le dossier /modules, qui se trouve à la racine du dossier principal de PrestaShop. Cela s'applique autant aux modules par défaut (ceux fournis avec PrestaShop) et les modules tiers que vous pourriez installer par la suite.

Chaque module dispose de son propre sous-dossier dans le dossier /modules : /bankwire, /birthdaypresent, etc.

Structure de base d'un module

Tous les modules utilisent la même structure de base, ce qui facilite l'apprentissage en regardant le code source de chacun.

Créons un premier module très simple ; celui nous permettra de mieux en décrire la structure. Nous le nommerons "My module".

Créons tout d'abord le dossier du module. Il devrait avoir le même nom que le module, avec aucune espace, et uniquement des caractères alphanumériques, le tiret "-" et le caractère souligné "_", le tout en minuscule : /mymodule.

Ce dossier dossier doit contenir un fichier PHP du même nom, qui s'occupera de la plupart des traitements: mymodule.php.

C'est là la base pour un module très simple, mais bien entendu il est possible d'ajouter d'autres fichiers et dossiers.

La partie publique du module doit être définie dans un fichier .tpl placé à la racine du dossier du module. Les fichiers TPL peuvent prendre n'importe quel nom, s'il n'y en a qu'un seul, une bonne pratique consiste à lui donner le même nom que le dossier et le fichier principale : mymodule.tpl.

Ce fichier mymondule.php doit commencer avec le test suivant:

if ( !defined( '_PS_VERSION_' ) )
  exit;

Celui-ci vérifie l'existence d'une constant PHP, et quitte si elle n'existe pas. Le seul but de ce test est d'empêcher les visiteurs d'accéder directement ce fichier.

Ce fichier doit également contenir la classe du module. PrestaShop utilise la programmation orientée Objet, et de fait ses modules également.

Cette classe doit porter le même nom que le module et son dossier, en CamelCase : MyModule.
Qui plus est, cette classe doit étendre la classe Module, et donc hérite de toutes ses méthodes et attributs. Elle peut tout aussi bien étendre n'importe quelle classe dérivée de la classe Module : PaymentModule, ModuleGridEngine, ModuleGraph...

<?php
if ( !defined( '_PS_VERSION_' ) )
  exit;

class MyModule extends Module
  {
  public function __construct()
    {
    $this->name = 'mymodule';
    $this->tab = 'Test';
    $this->version = 1.0;
    $this->author = 'Firstname Lastname';
    $this->need_instance = 0;

    parent::__construct();

    $this->displayName = $this->l( 'My module' );
    $this->description = $this->l( 'Description of my module.' );
    }

  public function install()
    {
    if ( parent::install() == false )
      return false;
    return true;
    }
  }
?>

Examinons chaque ligne de l'objet MyModule...

public function __construct()

Définit la constructeur de la classe.

$this->name = 'mymodule';
$this->tab = 'Test';
$this->version = 1.0;
$this->author = 'PrestaShop';

Cette section assign une poignée d'attributs à l'instance de classe this :

• Un attribut 'nom'. Il s'agit d'un identifiant interne, donc il est préférable de s'assurer qu'il est unique, sans caractères spéciaux ni espaces, et de le garder en minuscule.
• Un attribut 'tab'. C'est le nom du tableau qui contiendra ce module dans la liste des modules du back-office de PrestaShop. Vous pouvez utiliser un nom existant, comme Products, Blocks ou Stats, ou en choisir un personnalisé, comme nous l'avons fait ici. Dans ce dernier cas, un nouveau tableau sera ajouté avec votre titre.
• Un numéro de version pour le module, qui est affiché dans la liste de modules.
• Un attribut 'author'. Le nom de l'auteur est affiché dans la liste de modules de PrestaShop.

$this->need_instance = 0;

Le drapeau need_instance indique s'il faut oui ou non charger la classe du module lors du chargement de la page "Modules" dans le back-office. S'il est à 0, le module n'est pas chargé, et donc la page des modules utilisera moins de ressources. Si vos modules ont besoin d'afficher un avertissement dans la page des modules, alors vous devez mettre cet attribut à 1.

parent::__construct();

Appelle le constructeur du parent. Cela doit être fait avant tout appel à la méthode $this->l(), et après avoir créé $this->name.

$this->displayName = $this->l( 'My module' );

Assigne un nom public au module, nom qui sera affiché dans la liste des modules, dans le back-office.
La méthode l() fait partie des outils de traduction de PrestaShop, et est expliquée plus bas.

$this->description = $this->l( 'Description of my module.' );

Assigne une description publique pour le module, qui sera affichée dans la liste des modules.

public function install()
  {
  return ( parent::install() );
  }

Sous cette première incarnation extrêmement simple, cette méthode est inutile, étant donné que tout ce qu'elle fait est vérifier la valeur renvoyer la méthode {{install}] de la classe Module. Par ailleurs, si nous n'avions pas créé cette méthode, la méthode de la superclasse aurait été appelée de toute façon, amenant au même résultat.
Cependant, nous devons mentionner cette méthode, car elle nous sera très utile une que nous aurons à réaliser des tests et des actions lors du processus d'installation du module : créer des tables SQL, copier des fichiers, créer des variables de configuration, etc.

De la même manière, le module devrait contenir une méthode uninstall(), afin de disposer d'un processus de désinstallation personnalisé. Cette méthode pourrait être comme suit :

public function uninstall()
  {
  if ( !parent::uninstall() )
    Db::getInstance()->Execute( 'DELETE FROM `' . _DB_PREFIX_ . 'mymodule`' );
  parent::uninstall();
  }

Pour parfaire ce premier module, nous pouvons ajouter une icône, qui sera affiché à côté du nom du module dans la liste des modules.
Le fichier d'icône doit respecter le format suivant :

• image en 16*16 pixels ;
• nommée logo.gif ;
• placée dans le dossier principal du module.

Vous trouverez un excellent jeu gratuit d'icônes sur le site FamFamFam.

Maintenant que toutes les bases sont en place, mettez le dossier du modules dans le dossier /modules de votre installation test de PrestaShop, ouvrez PrestaShop, et dans l'onglet "Modules", sous "Autres Modules", vous devriez trouver votre module. Installez-le afin de pouvoir le gérer pour la suite de ce guide.

PrestaShop crée automatiquement un petit fichier config.xml dans le dossier du module, fichier qui stocke certaines informations de configuration. Vous ne devriez JAMAIS le modifier manuellement.

Lors de l'installation, PrestaShop également ajoute une ligne à la table SQL ps_module.

Accrocher un module

Afficher des données, lancer un processus à une heure donnée : afin "d'attacher" un module à un emplacement du front-office ou du back-office, vous devez lui donner accès à l'un des nombreux points d'accroche de PrestaShop, décrits plus avant dans ce guide.

Pour ce faire, nous allons changer le code de notre module, et ajouter ces lignes :

public function install()
  {
  if ( parent::install() == false OR !$this->registerHook( 'leftColumn' ) )
    return false;
  return true;
  }

...

public function hookLeftColumn( $params )
  {
  global $smarty;
  return $this->display( __FILE__, 'mymodule.tpl' );
  }

public function hookRightColumn( $params )
  {
  return $this->hookLeftColumn( $params );
  }

Explorons lignes ajoutées/modifiées :

if ( parent::install() == false OR !$this->registerHook( 'leftColumn' ) )
  return false;
return true;

Nous avons modifié la ligne originale pour faire un second test.

Ce code vérifie :

• la valeur booléenne renvoyée par la méthode install() de la classe Module : si elle est true, alors le module est installé et peut être utilisé.
• la valeur booléenne renvoyée par la méthode registerHook() pour le point d'accroche leftColumn : si elle est true, alors le module est en enregistré pour le point d'accroche dont il a besoin, et peut être utilisé.

Il suffit que l'une de ces deux valeurs soit false pour que install() renvoie false également, et que le module ne puisse être installé. Les deux valeurs doivent être true pour que le module soit installé.

De fait, cette ligne peut se lire comme suit : si l'installation ou l'accrochage échouent, nous en informons PrestaShop.

public function hookLeftColumn( $params )
  {
  global $smarty;
  return $this->display(__FILE__, 'mymodule.tpl');
  }

Ma méthode hookLeftColumn() fait en sorte que le module puisse s'accrocher au point d'accroche de la colonne de gauche du thème.
$smarty est la variable globale du système de modèle Smarty, utilisé par PrestaShop, et à laquelle nous devons accéder.
La méthode display() renvoie le contenu du fichier de template mymodule.tpl, s'il existe.

public function hookRightColumn( $params )
  {
  return $this->hookLeftColumn( $params );
  }

De la même manière, hookRightColumn() donne accès au thème de la colonne de droite. Dans cet exemple, nous appelons simplement la méthode hookLeftColumn() afin d'obtenir le même affichage, quelle que soit la colonne.

Enregistrez le fichier, et vous pouvez d'ors et déjà l'accroche au thème, le déplacer et le greffer : aller au sous-onglet "Positions" de l'onglet "Module" du back-office, puis cliquer sur le lien "Greffer un module".

Dans le formulaire de greffe, trouvez "My module" dans le menu déroulant de modules, puis choisissez "Left menu blocks" dans le menu déroulant "Greffer le module sur".

Enregistrez. La page "Positions" devrait se recharger, avec le message suivant : "Le module a bien été greffer au hook". Félicitations ! Descendez dans la page, et vous devriez effectivement voir votre module parmi les autres modules dans la liste "Left column blocks". Déplacez-le en faut de la liste.

Affiche du contenu

Maintenant que nous avons accès à la colonne de gauche, nous pouvons y afficher quelque chose.

Comme indiqué plus tôt, le contenu à afficher dans le thème doit être stocké dans des fichiers .tpl. Nous allons créer le fichier mymodule.tpl, qui a été passé comme paramètre à la méthode display() du code de notre module.

Créons donc le fichier mymodule.tpl, et ajoutons-lui quelques lignes de code.

<!-- Block mymodule -->
<div id="mymodule_block_left" class="block">
  <h4>Welcome!</h4>
  <div class="block_content">
    <ul>
      <li><a href="{$base_dir}modules/mymodule/mymodule_page.php" title="Click this link">Click me!</a></li>
    </ul>
  </div>
</div>
<!-- /Block mymodule -->

Enregistrez le fichier dans le dossier racine du module, et rechargez la page d'accueil de la boutique : il devrait apparaître au haut de la colonne de gauche, juste à côté du logo de la boutique.

Le lien affiché ne mène à rien pour le moment. Si vous avez besoin de le tester, ajoutez le fichier mymodule_page.php dans le dossier du module, avec un contenu minimal, tel qu'un simple "Bienvenu dans ma boutique !" La page résultante sera brute d'aspect, donc nous allons voir comment lui appliquer le style du thème.

Comme vous pouvez vous attendre, nous devons créer un fichier TPL pour pouvoir exploiter le style du thème. Créons donc le fichier mymodule_page.tpl, qui contiendra notre message basique, et appelons ce fichier depuis mymodule_page.php, qui ajoutera le thème (en-tête, pied de page, etc.).

Welcome to my shop!

<?php
global $smarty;
include( '../../config/config.inc.php' );
include( '../../header.php' );

$smarty->display( dirname(__FILE__) . '/mymodule_page.tpl' );

include( '../../footer.php' );
?>

Nous chargeons en premier l'instance actuelle de Smarty. Cela doit impérativement être fait avant l'appel à la méthode display().

Les divers appels includes() du fichier nous permettent de charger :

• La configuration actuelle de PrestaShop ;
• le fichier de l'en-tête du thème (via header.php, qui agit comme fichier de chargement).
• le fichier de pied de page du thème (via footer.php, qui agit comme fichier de chargement).

Au milieu de tout cela, nous place notre fichier TPL personnalisé, dont la seule action sera d'afficher la ligne "Bienvenu dans ma boutique !"

Enregistrez tous les fichiers et rechargez la page d'accueil de votre boutique : en quelques lignes, le résultat final a été nettement amélioré, avec notre message maintenant correctement placé entre en-tête, pied de page et colonnes !

Utiliser Smarty

Smarty est un moteur de modèle/template en PHP, et est utilisé par PrestaShop pour son système de thème.

Il parcours les fichiers TPL, à la recherche d'éléments dynamiques à remplacer par les données équivalentes, puis affiché le résultat ainsi produit. Ces éléments dynamiques sont indiqués avec des accolades : { ... }. Le programmeur peut créer de nouvelles variables et les utiliser dans ses fichiers TPL.

Par exemple, dans notre mymodule_page.php, nous pouvez créer une telle variable :

<?php
global $smarty;

include( '../../config/config.inc.php' );
include( '../../header.php' );

$mymodule = new MyModule();
$message = $mymodule->l( 'Welcome to my shop!' );
$smarty->assign( 'messageSmarty', $message ); // creation of our variable
$smarty->display( dirname(__FILE__) . '/mymodule_page.tpl' );

include( '../../footer.php' );
?>

De là, nous pouvons demander à Smarty d'afficher le contenu de cette variable dans notre fichier TPL.

{$messageSmarty}

PrestaShop comprend un certain nombre de variables. Par exemple {$HOOK_LEFT_COLUMN} sera remplacé par le contenu de la colonne de de gauche, et donc le contenu de tous les modules qui ont été attachés au point d'accroche de la colonne de gauche.

Toutes les variables Smarty sont globales. Vous devriez donc faire attention à ne pas donner à vos variables un nom déjà utilisé par une autre variable Smarty, afin d'éviter les conflit et les réécritures. Une bonne pratique consiste à éviter les nom trop simples, comme products, mais à préfixer du nom de votre module, voire de votre nom. Donc : {$mark_mymodule_product}

Voici une liste de variables Smarty qui sont accessibles depuis toutes les pages :

If you need to have all of the current page's Smarty variables displayed, add the following function:

{debug}

Comments are based on asterisk:

{* This string is commented out *}

{*
This string is too!
*}

Unlike with HTML comments, commented-out Smarty code is not present in the final output file.

Module translation

Our module's text strings are written in English, but we might want French shop owners to use our module too. We therefore have to translate those strings into French, both front-office and back-offices ones. This could be a tedious task, but Smarty and PrestaShop's own translation make it far easier.

Strings in PHP files will need to be displayed through the l() method, from the Module.php abstract class.

...
$this->displayName = $this->l( 'My module' );
$this->description = $this->l( 'Description of my module.' );
...

Strings in TPL files will need to be turned into dynamic content, which Smarty will replace by the translation for the chosen language. In our sample module, this file:

<li>
  <a href="{$base_dir}modules/mymodule/mymodule_page.php" title="Click this link">Click me!</a>
</li>

...becomes:

<li>
  <a href="{$base_dir}modules/mymodule/mymodule_page.php" title="{l s='Click this link' mod='mymodule'}">{l s='Click me!' mod='mymodule'}</a>
</li>

...and this one:

<h4>Welcome!</h4>
...
Click me!

...becomes:

<h4>{l s='Welcome!' mod='mymodule'}</h4>
...
{l s='Click me!' mod='mymodule'}

The translation tool needs the mod parameter in order to match the string to translate with its translation.
Strings are delimited with single quotes. If a string contains single quotes, they should be escaped using a backslash ().

This way, strings can be directly translated inside PrestaShop: go to the "Tools" tab, its "Translations" sub-tab, and in the "Modify translations" drop-down menu, choose "Module translations", then click the French flag in order to translate modules into French.

The next page displays all the strings for all the currently-installed modules. Modules that have all their strings already translated have their fieldset closed, whereas if at least one string is missing in a module's translation, its fieldset is expanded.
In order to translate your module's strings (the ones that were "marked" using the l() method), simply find your module in the list (use the browser's in-page search), and fill the empty fields.

Once all strings for your module are correctly translated, click on the "Update translation" button, either at the top or the bottom of the page.

The translations are saved in a new file, fr.php (or languageCode.php, which is generated by PrestaShop and looks like this:

<?php

global $_MODULE;
$_MODULE = array();
$_MODULE['<{mymodule}prestashop>mymodule_2ddddc2a736e4128ce1cdfd22b041e7f'] = 'Mon module';
$_MODULE['<{mymodule}prestashop>mymodule_d6968577f69f08c93c209bd8b6b3d4d5'] = 'Description de mon module';
$_MODULE['<{mymodule}prestashop>mymodule_c66b10fbf9cb6526d0f7d7a602a09b75'] = 'Cliquez sur ce lien';
$_MODULE['<{mymodule}prestashop>mymodule_f42c5e677c97b2167e7e6b1e0028ec6d'] = 'Cliquez-moi \!';
$_MODULE['<{mymodule}prestashop>mymodule_page_c0d7cffa0105851272f83d5c1fe63a1c'] = 'Bienvenue dans ma boutique \!';

Now that we have a translation, we can click on the French flag in the front-office (provided the language has indeed been installed), and get the expected result: the module's strings are now in French.

They are also translated in French when the back-office is in French.

Creating the module's back-office tab, and its class

In this section you will learn how to give your module its own tab or sub-tab, in a matter of minutes.

Follow these steps:

1. Add a new table to your PrestaShop database, named ps_test. Give it two fields:
   • id_test (INT 11)
   • test (VARCHAR 32)
2. Create a blank file named Test.php in PrestaShop's /classes folder.
3. Add the following lines to that file:

<?php
class Test extends ObjectModel 
  {
  /** @var string Name */
  public $test;

  protected $fieldsRequired = array( 'test' );
  protected $fieldsSize = array( 'test' => 64 );
  protected $fieldsValidate = array( 'test' => 'isGenericName' );
  protected $table = 'test';
  protected $identifier = 'id_test';

  public function getFields() 
    {
    parent::validateFields();
    $fields[ 'test' ] = pSQL( $this->test );
    return $fields;
    }
  }
?>

1. Create a blank file named AdminTest.php in PrestaShop's /admin/tabs.
2. Add the following lines to that file:

<?php
include_once( PS_ADMIN_DIR . '/../classes/AdminTab.php' );

class AdminTest extends AdminTab
  {
  public function __construct()
    {
    $this->table = 'test';
    $this->className = 'Test';
    $this->lang = false;
    $this->edit = true;
    $this->delete = true;
    $this->fieldsDisplay = array(
      'id_test' => array(
        'title' => $this->l( 'ID' ),
        'align' => 'center',
        'width' => 25 ),
      'test' => array(
        'title' => $this->l( 'Name' ),
        'width' => 200 )
    );

    $this->identifier = 'id_test';

    parent::__construct();
    }

  public function displayForm()
    {
    global $currentIndex;

    $defaultLanguage = intval( Configuration::get( 'PS_LANG_DEFAULT' ) );
    $languages = Language::getLanguages();
    $obj = $this->loadObject( true );

    echo '
      <script type="text/javascript">
        id_language = Number('.$defaultLanguage.');
      </script>';

    echo '
      <form action="' . $currentIndex . '&submitAdd' .  $this->table . '=1&token=' . $this->token . '" method="post" class="width3">
        ' . ($obj->id ? '<input type="hidden" name="id_' . $this->table . '" value="' . $obj->id . '" />' : '').'
        <fieldset><legend><img src="../img/admin/profiles.png" />' . $this->l( 'Profiles' ) . '</legend>
          <label>'.$this->l( 'Name:' ).' </label>
          <div class="margin-form">';
    foreach ( $languages as $language )
      echo '
          <div id="name_' . $language['id_lang'|'id_lang'] . '" style="display: ' . ($language['id_lang'|'id_lang'] == $defaultLanguage ? 'block' : 'none') . '; float: left;">
            <input size="33" type="text" name="name_' . $language['id_lang'|'id_lang'] . '" value="' . htmlentities( $this->getFieldValue( $obj, 'name', intval( $language['id_lang'|'id_lang'] ) ), ENT_COMPAT, 'UTF-8' ) . '" /><sup>*</sup>
          </div>';
    $this->displayFlags( $languages, $defaultLanguage, 'name', 'name' );
    echo '
          <div class="clear"></div>
        </div>
        <div class="margin-form">
          <input type="submit" value="' . $this->l( ' Save ' ) . '" name="submitAdd' . $this->table . '" class="button" />
        </div>
        <div class="small"><sup>*</sup> ' . $this->l( 'Required field' ) . '</div>
      </fieldset>
    </form> ';
    }
  }
?>

Put the files online, then create the tab by going to the "Employee" tab, then its "Tabs" sub-tab. Click the "Add new" button, and fill-in the fields with the class' name, "AdminTest". Do not confuse "class" with "modules"! Choose an icon (like one from the FamFamFam pack), choose where the tab should go, and save. You're set! Now start customizing it to your needs!

Troubleshooting

If your module does not work as expected, here are a few ways to find help.

PrestaShop official forum

Join our forum at http://www.prestashop.com/forums/, and search for an answer using the relevant keywords. If your search needs refining, use the advanced search form. And if your search doesn't yield anything useful, create a new thread, where you can be as wordy as necessary when writing your question; you will need to registered first.

Some forums keep certain threads pinned on top of all threads; they contain some useful information, so be sure to read them through.

Our bug-tracker

if it turns out your issue stems from a PrestaShop bug rather than your code, please do submit the issue in the PrestaShop bug-tracker: http://forge.prestashop.com/ (you will need to register). This enables you to discuss the issue directly with the PrestaShop developers.

Official PrestaShop websites