Fundamentals

Concepts

PrestaShop was conceived so that third-party modules could easily upon its foundations, making it an extremely customizable e-commerce software.

A module is an addition to PrestaShop that enables any developer to add the following:

• Provide additional functionality to PrestaShop.
• View additional items on the site (product selection, etc..).
• Communicate with other e-commerce players (buying guides, payment platforms, logistics...)
• etc...

The company behind PrestaShop provides more than 100 modules for free with the tool itself, enabling you to launch your business quickly and for free.

More than 750 add-ons are also available at the official add-ons site.
These additional modules were build ??by the company PrestaShop or members of the PrestaShop community, and are sold at affordable prices.
As a developer, you can also share your modules on this site, and receive 70% of the amounts associated with the sale of your creations. Sign up now!

Technical principles behind a module

A PrestaShop module consists of:

• A root folder, named after the module, which will hold all of the modules files, and will reside in PrestaShop's /modules folder.
• A main PHP file, named after the module, located in that root folder. This PHP file should have the same name as its root folder.
• An icon file, named logo.gif, representing this module.
• Optional: some .tpl files, containing the module's theme.
• Optional: language files, if the module of its theme have text to display (and therefore, that should be translatable).
• Optional: in a /themes/modules, a folder with the same name as the module, containing .tpl and language files if necessary. This last folder is essential during modifications of existing module, so that you can adapt it without having to touch its original files. Notably, it enables you to handle the module's display in various ways, according to the current theme.

Let's see an example with PrestaShop's blockuserinfo module:

Any PrestaShop module, once installed on an online shop, can interact with one or more "hooks". Hooks enable you to "hook" your code to the current View at the time of the code parsing (i.e., when displaying the cart or the product sheet, when displaying the current stock...). Specifically, a hook is a shortcut to the various methods available from the Module object, as assigned to that hook.

A list of PrestaShop hooks

Here is a list of 53 hooks, available in PrestaShop.

When one of the site's page is loaded, the PrestaShop engine check which are the modules to call for each of the hooks that make up the page.

Front-office

Homepage and general website items

Product sheet

Cart

Search

Carrier choice

Payment

Merchandise Returns

Back-office

General

Orders and order details

Products

Statistics

Clients

Carriers

Creating a PrestaShop module

Modules' operating principles

Modules are the ideal way to let your talent and imagination as a developer express themselves, as the creative possibilities are many.

They can display a variety of content (blocks, text, etc.), perform many tasks (batch update, import, export, etc.), interface with other tools...

Modules can be made as configurable as necessary; the more configurable it is, the easier it will be to use, and thus will be able to address the need of a wider range of users.

One of the main interest of a module is to add functionalities to PrestaShop without having to edit its core files, this making it easier to perform an update without having the transpose all core changes.

That is way you should always strive to stay away from core files when building a module, even though this can prove hard to do in some situations...

Module file tree

All PrestaShop modules are found in the /modules folder, which is at the root of the PrestaShop main folder. This is true for both default modules (provided with PrestaShop) and 3rd-party modules that are subsequently installed.

Each modules has its own sub-folder inside the /modules folder: /bankwire, /birthdaypresent, etc.

Basic structure of a module

All modules use the same basic structure, which makes it easier to learn by observing existing modules' source code.

Let's create a simple first module; this will enable us to better describe its structure. We'll call it "My module".

Let's first create the module folder. It should have the same name as the module, with no space, only alphanumerical characters, the hyphen and the underscore, all in lowercase: /mymodule.

This folder must contain a PHP file of the same name, which will handle most of the processing: mymodule.php.

That is enough for a very basic module, but obviously more files and folders can complement it.

The front-office part of the module is defined in a .tpl file placed at the root of the module's folder. TPL files can have just about any name. It there's only one such file, it is good practice to give it the same name as the folder and main file: mymodule.tpl.

The mymodule.php must contain the module's class. PrestaShop is Object-Oriented Programming, and so does its modules.
That class must bear the same name as the module and its folder, in CamelCase: MyModule.
Furthermore, that class must extend the Module class, and thus inherits all methods and attributes. It can just as well extend any class derived from Module: PaymentModule, ModuleGridEngine, ModuleGraph...

<?php
class MyModule extends Module
  {
  public function __construct()
    {
    $this->name = 'mymodule';
    $this->tab = 'Test';
    $this->version = 1.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;
    }
  }
?>

Let's examine each line from our MyModule object...

public function __construct()

Defines the class' constructor.

$this->name = 'mymodule';

Assigns a 'name' attribute to our class' instance.

$this->tab = 'Test';

Assigns a 'tab' attribute to our class' instance. This is the title for the table that shall contain this module in PrestaShop's back-office modules list. You may use an existing name, such as Products, Blocks or Stats, or a custom, as we did here. In this last case, a new table will be created with your title.

$this->version = 1.0;

Version number for the module, displayed in the modules list.

parent::__construct();

Calling the parent's constructor. This must be done before any use of the $this->l(), and after the creation of $this->name.

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

Assigning a public name for the module, which will be displayed in the back-office's modules list.
The l() method is part of PrestaShop translation's tools, and is explained further below.

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

Assigning a public description for the module, which will be displayed in the back-office's modules list.

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

As it is, this method is useless, since all it does is check the value returned by the Module class' install() method. Moreover, if we hadn't created that method, the superclass' method would have been called instead anyway, making the end result identical.
Nevertheless, we must mention this method, because it will be very useful once we have to perform checks and actions during the module's installation process: creating SQL tables, copying files, creation configuration variables, etc.

Likewise, should contain an uninstall() method, so as to have a custom uninstallation process. This method could look as such:

public function uninstall()
  {
  Db::getInstance()->Execute( 'DELETE FROM `' . _DB_PREFIX_ . 'block_cms` WHERE `id_block` = ' . intval($this->id) );
  parent::uninstall();
  }

To put the finishing touch to this basic module, we can add an icon, which will be displayed next to the module's name in the back-office modules list.
The icon file must respect these requirements:

• 16*16 image.
• named logo.gif.
• place on the module's main folder.

You can find an excellent free set of icons to pick from on the FamFamFam website.

Now that all basics are in place, put the module's folder in the /modules folder of your PrestaShop test install, open PrestaShop, and in the "Modules" tab, under "Other Modules", you should find your module. Install it in order to be able to manager it for the rest of this guide.

Hooking a module

Displaying data, starting a process at a specific time: in order for a module to be "attached" to a location on the front-office or the back-office, you need to give it access to one of the above cited hooks.

To that effect, we are going to change your module's code, and add these lines:

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);
  }

Let's explore these new or changed lines.

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

We changed the original line to add a second test. Now this line reads this way: if installation or hooking fail, we inform PrestaShop.

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

The hookLeftColumn() method makes it possible for the module to hook into the theme's left column.
$smarty is the global variable for the Smarty template system, which PrestaShop uses, and which we need to access.
The display() method returns the content of the mymodule.tpl template file, if it exists.

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

Likewise, hookRightColumn() gives access to the theme's right column. In this example, we simply call the hookLeftColumn() method, in order to have the very same display, whatever the column.

Save your file, and already you can hook it into the theme, move it around and transplant it: go to the "Positions" sub-tab for the "Modules" tab in the back-office, then click on the "Transplant a module" link.

In the transplantation form, find "My module" in the modules drop-down menu, then choose "Left column blocks" in the "Hook into" drop-down menu. Save.

The "Positions" page should reload, with the following message: "Module transplanted successfully to hook". Congratulations! Scroll down, and you should indeed see your module among the other modules from the "Left column blocks" list.

Displaying content