Writing your own Prestashop Module – Part 2

Creating a basic module

Introduction

In this second part of the series we will look at creating our first basic Prestashop module that can be controlled from the Back Office.

The Module class

Similar to the ObjectModel base class, all Prestashop modules are extended from a common base class used to define their basic functionality. The “Module” class provides the interface between the administration screens and your module as well as providing internationalisation and “hook” management functionality.

Updated for Prestashop version 1.4 onwards.

Coding conventions

Before we can write our first code there is one more element that needs to be considered — that of module class, directory and file naming.

In Prestashop, modules must be located within the /modules directory below your base store installation directory. In addition the module directory and class source file must be named in lower case, with the same name as the module class we choose. Note that the module class name itself does not have to be lowercase (by convention class names use “Camel case”), but it is essential that the folder it resides in and the source file follow this convention.

An “empty” module

In this part of the tutorial we will create a module “TutorialFirst” which demonstrates the mandatory code required to create our very first module. The first step is to create our directory on the server and name it “tutorialfirst”. We then need to create the main module class file within this directory and insert the following code:

class TutorialFirst extends Module
{
  function __construct()
  {
    $version_mask = explode('.', _PS_VERSION_, 3);
    $version_test = $version_mask[0] > 0 && $version_mask[1] > 3;
    $this->name = 'tutorialfirst';
    $this->tab = $version_test ? 'others' : 'eCartService.net Tutorials';
    if ($version_test)
      $this->author = 'eCartService.net';
    $this->version = '0.1.0';
    parent::__construct();
    $this->displayName = $this->l('First Tutorial Module');
    $this->description = $this->l('Our very first module - it does absolutely nothing at all.');
  }
}
// End of: tutorialfirst.php

We save this file as “tutorialfirst.php” in our module directory and upload to our server. Although the above code doesn’t look like very much, it is actually packed with functionality thanks to the base class it extends. Once you’ve uploaded to your development site you will be able the see the module listed under the group heading “eCartService.net Tutorials” in versions prior to Prestashop 1.4 and under the heading “Other Modules” for version 1.4 onwards. You should also now be able to install and uninstall your new module.

Let’s look at what we’re doing in this code, and why.

$version_mask = explode('.', _PS_VERSION_, 2);
$version_test = $version_mask[0] > 0 && $version_mask[1] > 3;

This code retrieves the Prestashop version information into a variable so we can check the major and minor version numbers (array elements 0 and 1 respectively). We use this to cope with changes in the module handling logic between versions. In the above code we are testing that the Prestashop version is later than 1.3.

The remaining lines of code in the constructor are concerned with setting up the basic properties of the module and ensuring that we properly inherit required functionality from the base class. First we need to set up the “internal” name of the module – note that this again follows the naming convention for the module directory and main class definition file, and again is the class name in lower case.

$this->name = 'tutorialfirst';

Next, the $this->tab member variable defines how we wish our module to be classified by the Back Office in the modules list.

$this->tab = $version_test ? 'others' : 'eCartService.net Tutorials';

In general prior to version 1.4 we would choose one the the standard categories (e.g. ‘Advertisement’, ‘Products’, ‘Tools’, ‘Blocks’ etc.) however it was entirely up to you how you wish to use this property, and in the case of these examples I’ve chosen to group them under the heading “eCartservice.net Tutorials”. From version 1.4 there are now standard values for this parameter, selected according to the following table:

We use the $version_test variable defined above to decide which of the naming conventions to use — this maintains compatibility across the Prestashop versions. Also introduced in version 1.4 was an author property for modules, so we again use the $version_test variable to optionally define this, along with the module version number, which is consistent across versions:

if ($version_test)
  $this->author = 'eCartService.net';
$this->version = '0.1.0';

The $this->version member variable allows us to display the current module version in the modules list, which will allow users to identify visually which version of our module they are using. This may also be useful in allowing us to identify old and outdated module versions later, using an external module distribution site.

The final steps in our constructor is to call the parent class to inherit any other required initialisation, and finally set some friendly labels to use for the name and description in the back office module list. Note that these are being set using the $this->l() Module class function however, rather than just being assigned as the static strings directly.

parent::__construct();
$this->displayName = $this->l('First Tutorial Module');
$this->description = $this->l('Our very first module - it does absolutely nothing at all.');

The l() (base class) member function implements language support, and enables the store owner to provide translations. The English language version of the text we wish to display is passed to this function, and when defined in this way the store owner can use the Tools->Translations Back Office screens to translate them into the language of their choice. Wrapping any static text used in our module with this function enables the translation functionality and should be use for all static text within modules which isn’t language dependent.

Summary

Having read this article you should now be able to create a new module which can be listed and controlled from the Prestashop Back Office and optionally displaying this information in the store owner’s own language. In the next part of this tutorial we will look at extending our first module to allow configuration, and based on this configuration display output in a specified area of a page.