Module development changes in PrestaShop 1.7.0.0

Existing modules should mostly work as-is with version 1.7. In this article, we dive into that “mostly”!

As you certainly know, all well-written 1.6 modules should work with little to no changes in version 1.7, except:

• Those which target the theme/front office – because we rewrote the way themes are written.
• Those which target the Product page – because the DOM of this page has changed.
• Those which target the Modules page – again, because the DOM of this page has changed.

What this means for any upgrade is that in order for a PS 1.6 to migrate to PS 1.7, you (or your agency) will have to:

• Rewrite the theme, ideally using the Starter Theme or the default theme.
• Adapt the Product page modules (CSS and JavaScript).
• Adapt the Modules page modules (CSS and JavaScript).
• Test all the other modules – as you would for any new release.

In any case, we advise you to make sure that your module does work in PrestaShop 1.7.

(the information above comes straight from the PrestaShop 1.7 Project FAQ. Read it if you haven’t yet!)

Now, let’s dive into the details.

General information

• We changed all variables passed to Smarty: make sure what you use is still assigned!
• Objects are no longer passed to Smarty. We only use arrays now.
• Smarty’s strings are now automatically escaped:
• You should remove all your |escape:'html':'UTF-8' (FOR FRONT OFFICE TEMPLATES ONLY).
• You should add the nofilter tag if you print HTML.
• $link is deprecated. Use the {url} helper instead.
  • Even if $link is still passed to Smarty, it will be removed at some point in a future version.
• Make sure you use the new way of calling templates: fetch(module:modulename/views/template.tpl).
• Make sure you do not add your assets with a hardcoded path in the displayHeader hook.
  • Nothing new from v1.6 here, but it’s a bad practice.
• Only rely on documented variables!

Overrides and namespaces

PrestaShop 1.7 introduces the use of namespaces with its new architecture, and in short, anything that has namespaces cannot be overridden.
The legacy architecture can still be overridden, though. But in general, we advise against overriding code. It is better to extend it.
Also, overrides are currently forbidden in the Symfony-based pages (namely, the Product page and the Modules page).

Overrides are a nice system to have, but the issue with it is that it is an uncontrolled extension system. We are working on a carefully planned process that will allow developers to extend the PrestaShop code in a much cleaner way. The gist of it would be that the developer team would integrate your needs for overrides in the next version of PrestaShop – kind of what polyfills do for HTML5 features :) In short, you tell us what you need, and while we include it in the next version, you can use an override.

Again: the override system is not going away, you will still be able to easily extend PrestaShop. We’re just changing the way we want this to happen: instead of each developer having a separate set of overrides, we want developers who need an override to let us know about it, so that the next version of PrestaShop includes it directly.

Introducing the PrestaShop UI Kit

The Product page and the Modules page are the only two pages that have been rewritten using Symfony, and they still work fine with pre-1.7 modules – albeit with a necessary design adaptation, as happened in all major version of PrestaShop before, only this time we provide a UI Kit to help developers easily have a consistent style for their module screens.

The whole PrestaShop 1.7 back office has its design based on the UI Kit. This UI Kit was built so that designers and developers can create interfaces which are consistent in style with the administration interface.

Check its reference documentation here: http://build.prestashop.com/prestashop-ui-kit/
Check its code here: https://github.com/PrestaShop/prestashop-ui-kit

Note that it is still a work in progress, and should not be considered stable until 1.7 is released.

Payment API change

Payment modules should be particularly looked after, as we wrote in the third article about the Starter Theme.

To provide the best user experience possible for customers, and to guarantee that PrestaShop orders respect the law in all countries, we slightly changed the payment API.
For example, the Terms & Conditions checkbox is now displayed with the payment options, and there is only one button to click in order to pay.
That way, theme designers have more control of the layout of payment options.

Hook changes

The updated payment API changes the parameters passed to these two hooks:

• hookPaymentReturn
• hookDisplayOrderConfirmation

Before

After

Sample code

Everything can be retrieved from order. For instance.

$currency = new Currency($params['order']->id_currency);
$total_to_pay = $params['order']->getOrdersTotalPaid();

We advise you to dive into the Payment Example sample module, or to explore the native Bankwire module – most notably the commit that updated this module for 1.7.

Changes for modules targeting the Product page

The Product page has been entirely rewritten for PrestaShop 1.7 in order to make the product creation easier, faster, and more logical. 6 default tabs instead of the previous 12, with the main tab containing much more information; a greatly improved Combination generator/manager; new shortcuts; an in-page catalog browser; and other niceties…

If you created modules which target the Product Page, you may be impacted by these changes. To make them work as expected in the new Product page, you will need to adapt your code.

Here are the main information that you will need to update your modules.

Handling tabs

In PrestaShop 1.6, it is allowed to have a dedicated tab per module on the Product page. In version 1.7, we changed this and added a dedicated tab for all the Product page’s modules, via a new hook called hookDisplayAdminProductsExtra.

If you coded your modules by following the best practices of both PHP and PrestaShop 1.5-1.6, it should not take you too much time to update your code.

Back office hook Parameters

Parameters cannot be obtained from a query string anymore. From now on, an array of parameters is directly passed onto the hookDisplayAdminProductsExtra method.

See this sample hook:

public function hookDisplayAdminProductsExtra($params)

With $params taking these values:

$params [
  "_ps_version",
  "id_product",
  "cookie",
  "cart",
  "altern"
]

Assets

The URLs of back office assets (CSS, JavaScript, images, etc.) must be absolute, meaning that they must start with http:// or https://.

You can use the Tools::getCurrentUrlProtocolPrefix() method to make sure you always use the correct protocol.

Form fields

The form field names must be created in an array hook of this format: [MODULE_NAME][INPUT_NAME].

DOM

The format of the ID for the module’s container has been modified. Here is its new format: module_MODULE_NAME.

Changes for modules targeting the default theme.

All the 1.6 modules targeting the theme will likely be impacted (to various degrees) by the changes and need to be adapted for 1.7. From the moment your module targets the theme, it will have to be updated.

The Theme documentation

The Designer Guide is currently being entirely rewritten to focus on the 1.7 Theme system. We expect it to be available online in the coming weeks.

In the meantime, we invite you to dive into the source code:

• The Starter Theme, which you can use as a skeleton template for your 1.7 theme:
  https://github.com/PrestaShop/StarterTheme/tree/master
• The 1.7 default theme, called “Classic”, which can you can learn from:
  https://github.com/PrestaShop/PrestaShop/tree/develop/themes/classic

Widgets

PrestaShop 1.7 introduces widgets, which you can use to place your module’s content directly in your theme.

Widgets introduce 2 major features for theme developer:

• You can use a module directly within a theme.
• Widgets can be hooked to any display hook.

More information about this will be available in the soon-to-be-available PrestaShop 1.7 Designer Guide.

Hook changes

The front office hooks have seen a bit of evolution. Some have been moved, some have been removed, and some have been created. Here are the lists!

1.6 hooks that are not available in 1.7

These hooks were only available in 1.6. They are removed from 1.7.

Hooks that were added in 1.7.0.x

These hooks are only available in the 1.7.0.x branch

Common hooks

These hooks are common to PrestaShop 1.6 and 1.7. Some have seen their location change in 1.7.

That’s it for now!

More information is coming soon!

If you have specific questions about module development that are not answered in this article, let us know in the comments: it will help us build a better Developer Guide!