Page History

...

<?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()
  {
    ifreturn (parent::install() == false)
      return false;
    return true;
  }
}
?>

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

...

This section assign a handful of attributes to the class instance (this):

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

...

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

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

Assigning This assigns 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 further explained below.

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

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

public function install()
{
  return (parent::install());
}

// this also works, and is more future-proof
public function install()
  {
    if (parent::install() == false)
      return false;
    return true;
  }

In this first and extremely simplistic incarnation, this method is uselessdoes the minimum, since all it does is check return the value returned by the Module class' install() method, which returns either true if the module is install, or false otherwise. 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

...

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

To put the finishing touch to this basic module, we can you should add an icon, which will be displayed next to the module's name in the back-office modules list. In case your module is made for a prominent service, having that service's logo visible brings trust.
The icon file must respect these requirements:

• placed on the module's main folder.
• In order to work with PrestaShop 1.4:
  • 16*16 image.
  named
  • GIF format.
  • Named logo.gif.
• placed on the module's main folder.

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

• • Tips:
    • FamFamFam's free Silk icon set is probably the best there is http://www.famfamfam.com/lab/icons/silk/.
    • If the logo is written for a particular online service, you could use that site's favicon file (if they agree).
• In order to work with PrestaShop 1.5:
  • 32*32 image.
  • PNG format.
  • Named logo.png.
  • Tips:
    • There are many free 32*32 icon libraries available. Here are a few: http://www.fatcow.com/free-icons (very close to the FamFamFam one) or http://www.jonasraskdesign.com/downloads/downloads.html (Danish Royalty Free),
    • Make sure you do not use a logo already used by one of the native modules.

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 manage it for the rest of this guide.

...

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 linesLet's hook your module to the leftColumn hook:

public function install()
{
  if (parent::install() == false OR !$this->registerHook('leftColumn'))
    return false;
  return true;
}

// then...

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

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

...

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 you need to access.
The display() method returns the content of the mymodule.tpl template file, if it exists.

...

Save your file, and already you can hook it your module's template into the theme, move it around and transplant it: go to the "Positions" sub-tab for page under the "Modules" tab in the back-office, then click on the "Transplant a module" linkbutton (top right of the page).

In the transplantation form, :

1. find "My module" in the

...

1. "Module" drop-down

...

1. list
2. choose "Left column blocks" in the "Hook into" drop-down

...

1. list.

Click the "Save" button. 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 in the "Left column blocks" list. Move it to the top of the list by drag'n'dropping the module's row.

Displaying content

Now that we have access to the left column, we should display something there.

As said earlier, the content to be displayed in the theme should be stored in template files .tpl files. We will create the mymodule.tpl file, which was passed as a parameter of the display() method in our module's code.

...

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

This is just regular HTML code... except for the {$base_dir} variable in the link's href attribute: this is a Smarty variable created by PrestaShop, which provides developer with PrestaShop's root directory.

Save the file in the module's root folder, reload your shop's homepage: it should appear on top of the left column, right below the shop's logo (if you have indeed moved it at the top of the "Left Column" during the transplanting part).

The displayed link that the module displays doesn't lead anywhere for now. If you need to test it, add the needed mymodule_page.php file in the module's folder, with a minimal content, such as "Welcome to my shop!". The resulting page will be very raw, so let's see if we can use the theme's style instead.

As you would expect, we have to create a TPL file in order to use the theme's style. Let's create the mymodule_page.tpl file, which will contain the basic "Welcome to my shop!" line, and call that file from mymodule_page.php, which will add we will rewrite in order to put that basic line within the theme's header, footer, etc.

...

<?php
global $smarty;
include('../../config/config.inc.php');
include('../../header.php');

$smarty->display(dirname(__FILE__).'/mymodule_page.tpl');

include('../../footer.php');
?>

Let's explore this new PHP file:

• We first load the current Smarty instance. This must be done before any call to the display() method.
• The various include() calls in the file enable us to load:
  • The current PrestaShop configuration.
  • The theme's header file (through header.php, which acts as a load file).
  • the theme's footer file (through footer.php, which acts as a load file).
• In the middle of

...

• the include() calls, we place your custom template file, whose single action will be to display the "Welcome to my shop!" line.

Save all both files and reload your shop's homepage: with just a few lines, the end result is so already much better, with our the "Welcome" line neatly placed between header, footer and columns!

...

...

Smarty is a PHP template engine, and is used by PrestaShop's theming system. It is a free and open-source projet, hosted at http://www.smarty.net/.

It parses TPL template files .tpl, looking for dynamic elements to replace by with their data contextual equivalents, then displays send the generated result to the browser. Those dynamic elements are indicated with curly brackets : { ... }. The programmer may Programmers can create new variables and use them in TPL files; PrestaShop adds its own set of variables.

For instance, in our mymodule_page.php, we can create such a variable in PHP, and have it displayed by our template file:

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

...

PrestaShop includes a number of Smarty variables. For instance, {$HOOK$hook_LEFTleft_COLUMNcolumn} 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 or initials, such as: {$mark$henryb_mymodule_productproducts}.

Here is a list of Smarty variables that are common to all pages:

There are many other contextual hooks. If you need to have display all of the current page's Smarty variables displayed, add the following functioncall:

{debug}

Comments are based on asterisk:

...

Our module's text strings are written in English, but we you might want French shop owners to use our your module too. We You therefore have to translate those strings into French, both front-office and back-offices ones. This could be a tedious task, but Smarty and PrestaShop's own translation make it far easier, as they provide with already-translated strings; thus provided you use the exact same text, your translation needs should be lessened.

Strings in PHP files will need to be displayed through the l() method, from the Module.php abstract class.

...

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 the file mymodule.tpl:

<li>
  <a href="{$base_dir}modules/mymodule/mymodule_page.php" title="Click this link">Click me!</a>
</li>

...

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

...and this onethe file mymodule_page.tpl:

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

...

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

Notice that we use the mod parameter. The translation tool needs the mod parameter it in order to match the string to translate with its translation. This parameter is mandatory for module translation.

Strings are delimited with single quotes. If a string contains single quotes, they should be escaped using a backslash (
).

This way, strings can be directly translated inside PrestaShop:

• go to the "

...

• Translations" page under the "Localization" tab,
• in the "Modify translations" drop-down menu, choose "Module translations",

...

• click the

...

• flag of the country of which language you want to translate the module into.

The next page that loads displays all the strings for all the currently-installed modules. Modules that have all their strings already translated have their fieldset closed, whereas if at least one string is missing in a module's translation, its fieldset is expanded.
In order to translate your module's strings (the ones that were "marked" using the l() method), simply find your module in the list (use the browser's in-page search), and fill the empty fields.
The destination language must already be installed to enable translation in it.

Once all strings for your module are correctly translated, click on the "Update translation" button , either at the top or the bottom of the page.

The translations are saved .

PrestaShop then saves the translations in a new file, frnamed using the languageCode.php (or languageCode.php, which is generated by PrestaShop and looks like this format (for instance, /mymodule/translations/fr.php). If it does not exist yet, PrestaShop takes care of creating the /mymodule/translations folder. The translation file looks like so:

<?php

global $_MODULE;
$_MODULE = array();
$_MODULE['<{mymodule}prestashop>mymodule_2ddddc2a736e4128ce1cdfd22b041e7fb268021027834ab9a4fe675f0c0a93ef'] = 'Mon module';
$_MODULE['<{mymodule}prestashop>mymodule_d6968577f69f08c93c209bd8b6b3d4d58dc6964360034754105d1328b04d7727'] = 'Description de mon module';
$_MODULE['<{mymodule}prestashop>mymodule_c66b10fbf9cb6526d0f7d7a602a09b7519d8055bcd0e60a5f99c807e50094c4e'] = 'Cliquez sur ce lien';
$_MODULE['<{mymodule}prestashop>mymodule_f42c5e677c97b2167e7e6b1e0028ec6d526fdd5deb77218de6497b4f3f5b5c65'] = 'Cliquez-moi \!';
$_MODULE['<{mymodule}prestashop>mymodule_page_c0d7cffa0105851272f83d5c1fe63a1c9cfb297375a799e0f130804c089bd034'] = 'Bienvenue dans ma boutique \!';

Now that we have a French translation, we can click on the French flag in the front-office (provided the language has indeed been installed), and get the expected result: the module's strings are now in French.

...

In this section you will learn how to give your module its own tab or subtab-tabpage, in a matter of minutes.

...

1. Add a new table to your PrestaShop database, named ps_test. Give it two three fields:
   • id_shop (INT 11)
   • 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:

...

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

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

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

Front-office

Homepage and general website items

...