PrestaShop Module Development

Chapter 1. Creating a New Module

To learn how to code a PrestaShop module, it is always easier to work on a practical case. So, throughout the next chapters, we will develop a module that will permit customers to grade and comment on products.

In this first chapter, we will see how to:

Create the Bootstrap of an installable module
Add a configuration form to the module using Smarty templates
Register the module configuration in a database

First steps

First of all, we have to choose a public and technical name for the module. The technical name must be in lowercase, contain only letters and numbers, and begin with a letter. Let's call the module publicly My Module of product comments and technically mymodcomments.

You can choose whatever names you want as long as you stick to them for the rest of the book. However, since the technical name will be the directory name of your module, you won't be able to have two modules with the same technical name in a PrestaShop. Moreover, your technical name has to be unique if you want to sell it on marketplaces. One trick is to prefix it with your company name (in my case, my company name is Froggy Commerce, so I prefixed all my modules with froggy).

On the other hand, the public name has no restriction, so you can write whatever you want for the merchant.

Now, we will begin to create our first module.

Open the modules directory in the root of the PrestaShop directory, then create a new directory and name it with the technical name we chose: mymodcomments. Once done, in this new directory, create a new blank PHP file and name it with the technical name as well (in our case, mymodcomments.php). This is the main file of the module. The following screenshot depicts the file and folder structure:

Now open the mymodcomments.php file, and write the class of your module. You must name it with your technical name. To make it easier to read, you can use CamelCase. The class must extend PrestaShop's Module class. This class contains all the needed methods to make a module work; without it, your module won't work. In our case, the class of the module will be:

<?php
class MyModComments extends Module
{
}

Tip

Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.

Additionally, the code for this book is part of a Git repository, which is available on GitHub at https://github.com/FabienSerny/mymodcomments, https://github.com/FabienSerny/mymodcarrier, and https://github.com/FabienSerny/mymodpayment.

In order to have a working module, we just have to add the __construct method. In this method, you must write the following three mandatory lines:

Set the technical name: Without this, the module won't be installable. This variable is used by PrestaShop to build the install, uninstall, and configure links of the module:
```
$this->name = 'mymodcomments';
```
Set the public name: This line is used to display the module name for the merchant in the modules list of the back office:
```
$this->displayName = 'My Module of product comments';
```
Calling the parent __construct method: This line is mandatory since important initializations are made in this function:
```
parent::__construct();
```

You can add some of the following optional lines to give information about the module:

Set the module category: This makes the module search easier. If you don't set it or set a wrong value, then the module will automatically be associated with the Other Modules category. You should set one of the values shown in the following table:

`administration`	`advertising_marketing`	`analytics_stats`	`billing_invoicing`
`Checkout`	`content_management`	`export`	`emailing`
`front_office_features`	`i18n`	`localization`	`merchandizing`
`migration_tools`	`payments_gateways`	`payment_security`	`pricing_promotion`
`quick_bulk_update`	`search_filter`	`seo`	`shipping_logistics`
`slideshows`	`smart_shopping`	`market_place`	`social_networks`
`others`	`mobile`

These possible values are associated with the module's categories search filter in the back office of your PrestaShop:

$this->tab = 'front_office_features';

Set the module version: This variable will not only be used to display the module version in the module's list of the back office but also to check if updates are available (we'll cover this in more detail later):
```
$this->version = '0.1';
```
Set the author name: This line is used to display the author name for the merchant in the module's list of the back office. It can also be used to search for modules:
```
$this->author = 'Fabien Serny';
```

Set the module description: This helps the merchant learn what the module is used for:

$this->description = 'With this module, your customers will be able to grade and comments your products';

Here's what your code should look like now:

<?php
class MyModComments extends Module
{
  public function __construct()
  {
    $this->name = 'mymodcomments';
    $this->tab = 'front_office_features';
    $this->version = '0.1';
    $this->author = 'Fabien Serny';
    $this->displayName = 'My Module of product comments';
    $this->description = 'With this module, your customers will be able to grade and comments your products.';
    parent::__construct();
  }
}

At this point, you should be able to see your module in the back office of the modules section, as shown in the following screenshot:

Note

The question mark icon

This is the default logo for all modules. If you want a custom picture, you just have to add a logo.png picture of 32 x 32 pixels and a logo.gif picture of 16 x 16 pixels (for PrestaShop 1.4 compliancy) at the root of your module directory.

The module is now a working module; you can install it by clicking on the Install button. Here is what you should see:

For the moment, your module does nothing and doesn't have any configuration options. The only actions available are:

Uninstall: This option uninstalls the module and deletes the specific configurations, if there are some.
Disable: This is an alternative to the uninstall action but permits you to keep module configurations. The module is still installed and will simply be ignored by PrestaShop.
Reset: This option uninstalls and reinstalls the module.
Delete: This option will uninstall the module and then delete all the module files.

All these core functions are handled by the Module class and can be overridden by the module (we will see this later).

Adding the module configuration

We will now add configuration options to our module. To do so, we just have to add the getContent function to our module. The return value of this function will be the content displayed on your screen.

In our case, we will write the following code:

public function getContent()
{
  return 'My name is Raphael, I am a tourist';
}

Note

The sentence returned is only an example (and a private joke from one of the PrestaShop core developers).

When the getContent function is placed in a module's class, PrestaShop automatically displays a Configure link in the back office. When the Configure link is clicked, this function is called and the return value is displayed.

So, if you refresh the modules list in the back office and your module is installed, you should now see a Configure button:

If you click on the configuration link, you will see the translations block (automatically generated by PrestaShop software), and the sentence that we wrote in the function:

You must avoid writing HTML in PHP code (very bad practice). That's why we will use the Smarty template (the template engine used in PrestaShop). If you are not familiar with this library, or with template engines in general, I invite you to read the official documentation (the link is in the introduction of this book). However, do not panic; using Smarty templates is quite easy!

We will start by creating the templates directory in the root of the module's directory: /views/templates/hook/. All of the templates used in the module's class must be placed in this directory.

One of the best practices is to name the templates with the name of the method in which they are used. So, we will create a template named getContent.tpl. Let's write our previous text in this template:

My name is Raphael, I am still a tourist

Then, in the getContent method, we just have to change the return line to the following:

return $this->display(__FILE__, 'getContent.tpl');

In this case, the display method will automatically use the getContent.tpl template in the /views/templates/hook/ directory. If you refresh the page, you'll see that your display has changed (we added one word). Now, your view is separated from your code. The following screenshot displays the file architecture you should have now:

Making a simple configuration form

We will now make a small configuration form with two options: one to enable grades and the other one to enable comments on a product.

Let's fill in the getContent.tpl file we created previously with a small form.

Since PrestaShop 1.6, the back office now uses the CSS Framework Bootstrap. You can either write basic HTML (and make the display compliant with an older version of PrestaShop), or write Bootstrap templates.

If you choose to use Bootstrap (as I'll do later), you have to set the Bootstrap flag in your module constructor first.

In the __construct method of your module's mymodcomments.php main class, add the following line before parent::__construct:

$this->bootstrap = true;

If you do not set this flag to true (and if you are using PrestaShop 1.6), PrestaShop will include a retrocompatibility CSS file to make the template that you used in PrestaShop 1.5 compliant with the PrestaShop 1.6 display. Here is the Bootstrap HTML code that we will use to display the configuration:

<fieldset>
  <h2>My Module configuration</h2>
  <div class="panel">
    <div class="panel-heading">
      <legend><img src="../img/admin/cog.gif" alt="" width="16" />Configuration</legend>
    </div>
    <form action="" method="post">
      <div class="form-group clearfix">
        <label class="col-lg-3">Enable grades:</label>
        <div class="col-lg-9">
          <img src="../img/admin/enabled.gif" alt="" />
          <input type="radio" id="enable_grades_1" name="enable_grades" value="1" />
          <label class="t" for="enable_grades_1">Yes</label>
          <img src="../img/admin/disabled.gif" alt="" />
          <input type="radio" id="enable_grades_0" name="enable_grades" value="0" />
          <label class="t" for="enable_grades_0">No</label>
        </div>
      </div>

      <div class="form-group clearfix">
        <label class="col-lg-3">Enable comments:</label>
        <div class="col-lg-9">
          <img src="../img/admin/enabled.gif" alt="" />
          <input type="radio" id="enable_comments_1" name="enable_comments" value="1" />
          <label class="t" for="enable_comments_1">Yes</label>
          <img src="../img/admin/disabled.gif" alt="" />
          <input type="radio" id="enable_comments_0" name="enable_comments" value="0" />
          <label class="t" for="enable_comments_0">No</label>
        </div>
      </div>
      <div class="panel-footer">
        <input class="btn btn-default pull-right" type="submit" name="mymod_pc_form" value="Save" />
      </div>
    </form>
  </div>
</fieldset>

The HTML tags used here are the tags generally used in the native module, but you have no real limitations except your imagination.

Note

I will not go further in my explanation of this code since HTML basics are beyond the scope of this book.

If you refresh your browser, you will see the form appear, but for the moment, submitting the form will do nothing. So, we need to take care of saving the configuration options chosen by the merchant when he submits the form.

In order to not overload the getContent method, let's create a new method dedicated to handling the submission of the module configuration form. The name processConfiguration seems a good name to me for such a function. Since getContent is the only method called by PrestaShop when we enter in a module's configuration, we still have to call the newly created processConfiguration method in the getContent method:

public function processConfiguration()
{
}
public function getContent()
{
  $this->processConfiguration();
  return $this->display(__FILE__, 'getContent.tpl');
}

In the processConfiguration method, we will check whether the form has been sent with the Tools::isSubmit method:

if (Tools::isSubmit('mymod_pc_form'))
{
}

As you might have noticed, we set the mymod_pc_form name attribute on the Submit button. PrestaShop's Tools::isSubmit method checks whether a key matches the attribute name in the POST and GET values. If it exists, we will know that the form has been sent for sure.

We will now save the data of the form sent. We will use the following two methods for this action:

Tools::getValue: This function will retrieve the POST value of the key passed in the parameter. If the POST value does not exist, it will automatically check for the GET value. We can set a second parameter (optional), which will correspond to the default value if neither POST nor GET value is found.
Configuration::updateValue: This function is used to save simple value in the configuration table of PrestaShop. You just have to set the key as the first parameter and the value as the second. The updateValue function makes a new entry in the configuration table if the provided configuration is not found, and will update the configuration value if it is already in the configuration table. This method can have other parameters, but we will cover them later since we do not need them for the moment.

So in practice, we will have this:

if (Tools::isSubmit('mymod_pc_form'))
{
$enable_grades = Tools::getValue('enable_grades');
$enable_comments = Tools::getValue('enable_comments');
Configuration::updateValue('MYMOD_GRADES', $enable_grades);
Configuration::updateValue('MYMOD_COMMENTS', $enable_comments);
}

Note

It is a PrestaShop best practice to set the key in uppercase. Since any module can add configuration value, it's also a best practice to add a prefix to avoid conflict between modules. That's why I added MYMOD_.

Now, I invite you to refresh the configuration page in your browser, change the value of one or both options, and then submit the form.

Apparently, nothing has changed. However, if you go into your phpMyAdmin (or any administration tool), and see the content of PrestaShop's configuration table (if you kept the default database prefix, its name should be ps_configuration), you will see that the last two entries of the table are your values. You can play with the form and submit it again; the value will be updated.

We still have to display a confirmation message to let the merchant know that their configuration has been saved. For this, we just have to assign a confirmation variable to Smarty in the isSubmit condition just after the Configuration::updateValue calls.

The Smarty object is available in the $this->context->smarty variable in your module class. We will use the assign method of Smarty:

$this->context->smarty->assign('confirmation', 'ok');

This function takes two parameters: the name of the variable in which the value will be stored, and the value.

Note

If you want more information about this, you can check the official Smarty documentation at http://www.smarty.net/docsv2/en/api.assign.tpl.

In the Smarty template, you will now have a variable named $confirmation, which contains the value ok.

Note

We will see later exactly what the Context object contains. It is not important at this point.

If the $confirmation variable has been assigned to Smarty, then we display a confirmation message in getContent.tpl:

{if isset($confirmation)}
  <div class="alert alert-success">Settings updated</div>
{/if}

You can add these lines wherever you want in the template. However, you should add it just before the fieldset since this is a PrestaShop standard.

Now, you can submit the form again. If you did it right, the confirmation message should appear, as shown in the following screenshot:

We've almost finished the first version of the configuration form. However, you might have noticed that if you close the configuration form and reopen it, the options you set to Yes won't be preselected correctly. This will give the impression to the merchant that their configuration has not been saved properly.

To fix this problem, we just have to retrieve the configuration values and assign them to Smarty. We will use another function from the Configuration class: Configuration::get.

This function takes the key of the configuration wanted as a parameter, and returns the associated value:

$enable_grades = Configuration::get('MYMOD_GRADES');
$enable_comments = Configuration::get('MYMOD_COMMENTS');

Then, to assign these variables to Smarty, we will use the same method we saw previously to set the confirmation message flag:

$this->context->smarty->assign('enable_grades', $enable_grades);
$this->context->smarty->assign('enable_comments', $enable_comments);

To keep a short getContent method, my advice is to create a new method that we will call assignConfiguration, and write the code in it. So, at the end, we will have something like this:

public function assignConfiguration()
{
  $enable_grades = Configuration::get('MYMOD_GRADES');
  $enable_comments = Configuration::get('MYMOD_COMMENTS');
  $this->context->smarty->assign('enable_grades', $enable_grades);
  $this->context->smarty->assign('enable_comments', $enable_comments);
}

public function getContent()
{
  $this->processConfiguration();
  $this->assignConfiguration();
  return $this->display(__FILE__, 'getContent.tpl');
}

We just have to add some Smarty code in getContent.tpl to make it work. I will take the Enable grades option as an example, but it will be the same for Enable comments. If the Yes option is enabled, we will precheck the radio button whose value is 1. If the option value is not set or is set to 0, we will precheck the other radio button. The following is the Smarty code:

<img src="../img/admin/enabled.gif" alt="" />
<input type="radio" id="enable_grades_1" name="enable_grades" value="1" {if $enable_grades eq '1'}checked{/if} />
<label class="t" for="enable_grades_1">Yes</label>
<img src="../img/admin/disabled.gif" alt="" />
<input type="radio" id="enable_grades_0" name="enable_grades" value="0" {if empty($enable_grades) || $enable_grades eq '0'}checked{/if} />
<label class="t" for="enable_grades_0">No</label>

If we close the configuration form and reopen it, you will now see that the configuration values are prechecked correctly.

Congratulations, you finished the first step of your module!

If you don't know Smarty well yet, take time to read the official documentation to learn about functions of the Smarty object and template syntax. This will save you time for future developments.