Table of contents

...

Creating a PrestaShop module

Creating a PrestaShop module

What is a PrestaShop module

PrestaShop's extensibility revolves around modules, which are small programs that make use of PrestaShop's functionality and changes them or add to them in order to make PrestaShop easier to use or more customized.

Technical principles behind a module

A PrestaShop module consists of:

• A root folder, named after the module, which will hold all of the module's 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 or its theme have text to display (and therefore, that should be translatable).
• Optional: in a /themes/modules folder, 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:

Image Added

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.

Modules' operating principles

...

The mymodule.php file must start with the following test:

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

This checks for the existence of a PHP constant, and if it doesn't exist, it quits. The sole purpose of this is to prevent visitors to load this file directly.

...

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

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

public function __construct()

Defines the class' constructor.

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

...

• A 'name' attribute. This is an internal identifier, so make it unique, without special characters or spaces, and keep it lower-case.
• A 'tab' attribute. 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.
• Version number for the module, displayed in the modules list.
• An 'author' attribute. This is displayed in the PrestaShop modules list.

$this->need_instance = 0;

NeedThe need_instance flag indicates whether to load the module's class when displaying the "Modules" page in the back-office. If set at 0, the module will not be loaded, and therefore will spend less resources to generate the page module. If your modules needs to display a warning message in the "Modules" page, then you must set this attribute to 1.

parent::__construct();

Calling the parent's constructor. This must be done before any use of the $this->l() method, 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()
  {
  return ( parent::install() );
  }

In this first and extremely simplistic incarnation, 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, the module should contain an uninstall() method, so as to have a custom uninstallation process. This method could look as such:

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

...

PrestaShop automatically creates a small config.xml file in the module's folder, which stores a few configuration information. You should NEVER edit it by hand.

On installation, PrestaShop also adds a line to the ps_module SQL table.

Image Added

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 many PrestaShop hooks, described earlier in this guide.

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' ) )
  return false;
return true;

...

Therefore, this line now 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.

...

So, let's create the mymodule.tpl file, and add some lines of code to it.

<!-- 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 -->

...

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' );
?>

We first load the current Smarty instance. This must be done before any call to the display() method.

...

For instance, in our mymodule_page.php, we can create such a a 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' );
?>

From there on, we can ask Smarty to display the content of this variable in our TPL file.

{$messageSmarty}

PrestaShop includes a number of variables. For instance, {$HOOK_LEFT_COLUMN} will be replaced with the content for the left column, meaning the content from all the modules that have been attached to the left column's hook.

All Smarty variables are global. You should therefore pay attention not to name your own variable with the name of an existing Smarty variable, in order to avoid overwriting it. It is good practice to avoid overly simple names, such as products, and to prefix it with your module's name, or even your own name, such as: {$mark_mymodule_product}.

Here is a list of Smarty variables that are common to all 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!
*}

...

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>

...

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

...becomes:

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

...

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 \!';

...

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!

A list of PrestaShop hooks

Here's a recap of PrestaShop's module architecture:

Image Added

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.

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

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

Troubleshooting

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

...

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 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.

...