Guide de développement

Créer un module personnalisé pour PrestaShop vous permet d'étendre les fonctionnalités de votre boutique et de l'adapter aux besoins spécifiques de votre entreprise. Les modules personnalisés offrent un moyen d'intégrer de nouvelles fonctionnalités, d'améliorer les fonctionnalités existantes ou d'ajuster le comportement de la boutique pour mieux répondre à vos besoins. Dans cette section, nous vous guiderons à travers le processus de développement d'un module personnalisé basé sur le module Groupes de Champs Personnalisés. Cette approche utilise des groupes de champs prédéfinis pour une configuration sans faille, minimisant ainsi le besoin de développement backend extensif.

Vous apprendrez à configurer votre module, à utiliser les groupes de champs pour la configuration et à l'intégrer dans l'écosystème PrestaShop. Ce guide couvrira les étapes essentielles et les meilleures pratiques pour créer et déployer un module personnalisé, en veillant à ce qu'il s'intègre parfaitement à PrestaShop et réponde à vos besoins spécifiques.

Configuration de votre module

Configurer un module personnalisé dans PrestaShop implique de créer un dossier de module structuré, de définir les propriétés essentielles et d'étendre la classe CustomFieldGroupsModule. Suivez ces étapes pour commencer :

Structure du module et exigences

• Créer le répertoire du module :

Commencez par créer un nouveau dossier pour votre module dans le répertoire /modules/ de votre installation PrestaShop. Nommez ce dossier en fonction du nom de votre module, par exemple, mymodule.

• Fichiers essentiels :

Dans le dossier de votre module, créez les fichiers essentiels suivants :

/modules/mymodule/
├── mymodule.php        // Fichier principal de votre module
└── install/            // Ce dossier est utilisé pour stocker les groupes de champs du module

Définir les propriétés du module

Étendez la classe CustomFieldGroupsModule pour utiliser la fonctionnalité de groupe de champs. Assurez-vous que le module CustomFieldGroups est installé et actif. Si le module n'est pas actif, empêchez l'installation de votre module.

<?php

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

if(!Module::isEnabled('customfieldgroups') || !class_exists('CustomFieldGroups\Model\CustomFieldGroupsModule')) {

    /**
     * WARNING: Do not edit this class.
     * Prevents installation if the CustomFieldGroups module is not active.
     *
     * Edit only the subclass present below in this file.
     */

    class MyModule extends Module
    {
        public function __construct()
        {
            $this->name = 'mymodule';
            $this->tab = 'front_office_features';
            $this->version = '1.0.0';
            $this->author = 'John Doe';
            $this->need_instance = 0;

            parent::__construct();

            $this->displayName = $this->trans('CFG - Module Sample', [], 'Modules.MyModule.Admin');
            $this->description = $this->trans('Module sample for CustomFieldGroups.', [], 'Modules.MyModule.Admin');

            $this->ps_versions_compliancy = [
                'min' => '8.0.0.0',
                'max' => _PS_VERSION_,
            ];
        }

        public function install()
        {
            $this->_errors[] = $this->trans('The "Custom Field Groups" module must be enabled to use this module.', [], 'Modules.MyModule.Admin');
            return false;
        }
    }

} else {

    /**
     * Subclass for extending the functionality.
     * NOTE: Make changes only in this subclass.
     * WARNING: The method getContent() is used by CustomFieldGroupsModule to provide the form, do not use it
     */
    
    class MyModule extends CustomFieldGroups\Model\CustomFieldGroupsModule
    {
        public function __construct()
        {
            $this->name = 'mymodule';
            $this->tab = 'front_office_features';
            $this->version = '1.0.0';
            $this->author = 'John Doe';
            $this->need_instance = 0;
    
            parent::__construct();
    
            $this->displayName = $this->trans('CFG - Module Sample', [], 'Modules.MyModule.Admin');
            $this->description = $this->trans('Module sample for CustomFieldGroups.', [], 'Modules.MyModule.Admin');
    
            $this->ps_versions_compliancy = [
                'min' => '8.0.0.0',
                'max' => _PS_VERSION_,
            ];
        }
    
        public function install()
        {
            return parent::install() && $this->registerHook('displayReassurance');
        }
    
        public function hookDisplayReassurance(array $params)
        {
            return '..';
        }
    }
    
}

Installation et configuration du module

Une fois votre module configuré, vous devez l'installer et créer les groupes de champs nécessaires via l'interface principale du module. Cette section couvre ces étapes :

• Installer le module:
  • Accédez au back-office de PrestaShop.
  • Allez dans Modules > Gestionnaire de modules.
  • Recherchez votre module et installez-le.
• Créer des groupes de champs:
  • Accédez à l'interface des Groupes de Champs :
    • Allez dans l'onglet CFG > Groupes de Champs dans votre back-office.
    • Cliquez sur le bouton "Créer un nouveau groupe de champs".

• Configurez votre nouveau groupe de champs :
  • Remplissez les détails requis (Nom, Slug, etc.) et configurez les paramètres du groupe de champs selon vos besoins.
  • Définissez l'entité du groupe de champs sur "module" et le module sur le vôtre.
  • Ajoutez autant de champs que nécessaire dans votre groupe de champs.
  • Enregistrez la configuration du groupe de champs.

info

Les modifications apportées aux groupes de champs seront automatiquement reflétées dans les formulaires du module. Aucune configuration supplémentaire n'est nécessaire.

Utilisation du formulaire

Une fois le module et les groupes de champs configurés, vous pouvez utiliser les formulaires créés avec ces groupes de champs et récupérer les données selon vos besoins.

• Accédez au formulaire :
  • Allez sur la page de configuration de votre module (comme pour les autres modules Prestashop, allez dans la section Modules > Gestionnaire de modules).
  • La page de configuration est mise à jour avec les données de votre groupe de champs.

info

Si le formulaire n'apparaît pas, vérifiez si votre groupe de champs est activé, associé à votre module, et lié à votre boutique actuelle.

Groupes de champs multiples et menu

Lorsque vous créez un module personnalisé avec le module CustomFieldGroups, vous pouvez souhaiter ajouter un menu à la page de configuration du module. Cela peut être utile si vous avez plusieurs groupes de champs associés à votre module ou si vous souhaitez ajouter des liens externes pour une meilleure navigation.

Pour ajouter un menu à votre module personnalisé, vous devez implémenter la fonction getMenu(): array dans le fichier principal de votre module. Cette fonction retourne un tableau d'éléments de menu qui seront affichés sur la page de configuration.

/**
* Define the menu items for the module configuration page.
*
* @return array
*/
public function getMenu(): array
{
    return [
        [
            'type' => 'field_group',
            'value' => 'my_module_field_group_slug', // Slug du groupe de champs
            'label' => $this->trans('Groupe de champs lié', [], 'Modules.Mymodule.Admin'),
        ],
        [
            'type' => 'field_group',
            'value' => 'my_second_module_field_group_slug',  // Slug du groupe de champs
            'label' => $this->trans('Deuxième groupe de champs lié', [], 'Modules.Mymodule.Admin'),
        ],
        [
            'type' => 'route',
            'value' => 'symfony_route_to_redirect', // Nom de la route Symfony
            'label' => $this->trans('Route Symfony', [], 'Modules.Mymodule.Admin'),
        ],
        [
            'type' => 'link',
            'value' => 'https://google.com', // URL
            'label' => $this->trans('Lien externe', [], 'Modules.Mymodule.Admin'),
            'new_window' => true, // Ouverture de la page dans un nouvel onglet
        ],
    ];    
}

Récupération des données du formulaire

• Dans le fichier principal de votre module avec la méthode getConfiguration().

class MyModule extends CustomFieldGroups\Model\CustomFieldGroupsModule
{

    ...
    
    public function hookDisplayReassurance(array $params)
    {
        $configuration = $this->getConfiguration();
        ...
    }
    
    ...
    
}

• N'importe où dans votre code PHP avec la classe DataRetrieverFacade.

use CustomFieldGroups\Facade\DataRetrieverFacade;

public function someMethod()
{
    $myModule = \Module::getInstanceByName('mymodule');
    $dataRetriever = DataRetrieverFacade::getInstance();
    
    // With object
    $configuration = $dataRetriever->get($myModule);
    
    // With module name
    $configuration = $dataRetriever->get('module', 'mymodule');
    
    // With entity and ID
    $configuration = $dataRetriever->get('module', $myModule->id);
}

Enregistrement des groupes de champs pour le module

Pour garantir que votre module fonctionne correctement dès son installation, exportez les groupes de champs depuis la page "Groupes de Champs" et placez-les dans le répertoire /install/ de votre module. Cette configuration garantit que les groupes de champs sont automatiquement créés lors de l'installation.

De plus, les groupes de champs sont versionnés en tant que fichiers, ce qui permet la synchronisation entre différents environnements. Pour des instructions détaillées sur la gestion des versions et la synchronisation, référez-vous à la section versioning de la documentation.