CONTRIBUTOR GUIDE - Technical validation

1 - 3 tools to help you get off to a good start

1.1/ the Validator

The Validator (http://validator.prestashop.com) is a tool created to check your module is technically compatible with the PrestaShop requirements. You can:

• upload a zip

• or specify the URL of your Github submission.

The Validator then automatically creates a detailed report explaining what needs to be improved in your module. By following this report, you can submit your module error-free!

!! Important!!
Since the 1.6.1.0 version, PrestaShop uses the PSR-2 norma. Even if we recommend you to use this norma, it's not mandatory and it won’t be a reason to decline your module. Here are more details in this blog article.

1.2/ search engine methods

A search engine is available within the Validator to help you work out which methods are available for the various versions of PrestaShop. Make the most of this and use it to save time!

1.3/ the Module Generator

Have you thought about saving time with our Module Generator yet? All you have to do is choose your module type and follow the instructions. A skeleton module is then automatically generated to facilitate the creation of your module.
For quicker technical validation!

To finish the technical validation process, manual verification of the module is carried out by our team of developers. They upload, install, configure and verify your module's code.

2 - 3 steps to passing the technical validation

2.1/ A development environment

Create and test your module in a local development environment, with the help of WampServer (Windows) for example. This will allow you to display errors, warnings and other PHP alerts without having to depend on your online server.
To make this easier, PrestaShop features a Dev Mode, which allows you to configure your use of PHP to display error messages. To activate Dev Mode: in the directory/config of your PrestaShop installation, open the file defines.inc.php. The Dev Mode is activated at the very start of the file: you must modify the following line to change the defined value to true (it's set to false by default):
define('_PS_MODE_DEV_', true);

Important: stores which are up and running must not be used in Dev Mode!

2.2/ Good practice

A few recommendations for your modules:

• Prefix what belongs to you:

  • modules

  • configuration parameters (ps_configuration)

  • tables

  • CSS classes

• Consider deleting your configurations, tables, and other entities unique to your product during the de-installation of your modules.

• You shouldn't use HTML code in your PHP code. Here are alternatives to separate the view into your code:

  • display content with Smarty

  • use helpers for your configuration pages

  • include PrestUI, a graphic library created by the community for your configuration pages.

• Your module interface has to match the back office interface. Customized interfaces aren’t validated/accepted. Please use the alternatives explained before to help you create an interface that matches merchants' BO.

• For modules compatible before the 1.7 PrestaShop version, the minimal compatibility has to be PHP 5.3. You will be then able to use, for example, namespaces.

• If you add function to add a file, check the type of the file to make sure you avoid security issues. Here are more information for the function mime_content_type().

• When uninstalling the module, delete all tabs you might have added during the installation.

• When your module has forms, you should:

  • show a confirmation message if everything is fine or an error message if not.

  • make sure information entered by customers are correct. If you ask a sum, it has to be only numbers. More information about the Validate class of PrestaShop here.

• Consider carefully casting your variables and use pSQL/bqSQL in the SQL requests to avoid any injections(read http://doc.prestashop.com/display/PS16/Best+Practices+of+the+Db+Class). Make sure your files are properly protected (especially if your module uses a cron for example) to avoid anyone being able to execute them. As a result,you are required to use a token!

• The use of overrides is permitted, however if we decide that too many (2/3 max) have been used and/or the modifications are too dangerous, we will refuse your module. If you're unsure, don't hesitate to get in touch.

• If you need to upload a .js or .tpl (containing JavaScript) to the back-office, put restrictions in place on your back-office hooks (hookbackofficeheader/top/footer)! Specific examples: If your JS only applies to your module's configuration page, use:
  if (Tools::getValue('configure') == $this->name { // code }

A few recommendations for your themes:

• PrestaShop does not yet feature a "theme validator". However, each of the modules present in your theme must be tested via our Validator: http://validator.prestashop.com

• Don't remove the default hooks in PrestaShop, whether via PHP or in the theme! You will risk preventing a third party module from working properly.

• Prefix what belongs to you:

  • modules

  • image standards

• You should not have HTML in your PHP code; use Smarty or helper classes for views.

• We do not accept themes using the PrestaShop base them to which only color, font and image changes etc. have been made. You should create a unique theme!  :-)

• You should keep the store logo by default in your theme's zip, in the header and footer of your theme.

A few recommendations for your email templates:

• Use our official SDK to develop your emails: https://github.com/PrestaShop/email-templates-sdk

• Make sure to submit on Addons a valid zip, built with the SDK.

• Test your emails with the official module: https://github.com/PrestaShop/email-templates-sdk

2.3/ Using the Validator to optimize your module

The Validator explains exactly what you need to modify for your module to be compliant with our technical requirements (technical errors, forbidden features or structural problems, etc.).
By following the Validator's recommendations, your module will be on sale sooner!

Are the recommendations provided preventing your module from working properly?
Contact us, we will be happy to help you develop your module!

If you encounter any problems, you can contact the technical team when submitting your module. Take advantage of their experience to perfect your module!

3 - Update your modules and create themes for PrestaShop 1.7

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.

  • Payment modules – should be especially taken care of, since the payment API has seen a slight update.

• The BO Product page – because the DOM of this page has changed.

• The BO Modules page – again, because the DOM of this page has changed.
  
  

What this means for any shop upgrade is that in order for a PS 1.6 to migrate to PS 1.7, you will have to:

• Rewrite the theme. You can use the Starter Theme or the default theme as a foundation.

• Adapt the Product page modules (CSS and JavaScript).

• Adapt the Modules page modules (CSS and JavaScript).
  
  

Everything you should know is gathered in the following pages:

• Details on every changes concerning modules on this article of the Build devblog;

• The Theme Developer documentation is being written in the open. Don't hesitate to contribute or ask questions!

• Payment modules:

  • Get inspired by our payment module demo to develop yours and use our dedicated documentation!
    
    

And of course our 1.7 Project FAQ that should already be your bedtime reading!

4 - How to submit a product to the Addons marketplace

After creating the perfect product page using the Seller Kit- Marketing Section submit your module for technical validation.

4.1/ Information

At this stage, you can find the module_key for your module. This is to be entered into the constructor in this format:

public function __construct() { etc. $this->module_key = 'c1614c239af92968e5fae97f366e9961'; }

This will signal to the seller when an update of your module is available in the back-office.
You should describe the modifications made one by one when an update is made.
Don't forget to indicate which versions of PrestaShop your module is compatible with!

4.2/ Your file and the permanent name of your module

The zip archive submitted to our team must contain all the necessary files for your module, and have the same name as your module: if the main file of your module is called "module_name.php", then it should be in the folder "module_name", and the zip file must have the same name - without a version number.

Make sure that the name used for your file and zip is the same that you have given to your product page (so that the online seller can quickly identify your module in the back office of their store). So think carefully about the name you choose for your product (without using either "PrestaShop" or "module"). Feel free to personalize the name, for example with the name of your company or your initials

5 - What happens next?

Once your module has been verified by the technical team, you will receive an email from us informing you of its status (validated or refused).

If refused, you will be told the points to improve. You can respond directly to the team via a link in the email informing you of the refusal in order to receive further information.
Then it's up to you to follow these recommendations and resubmit your module to us!

Would you like to find out more about PrestaShop's standards?
Head over to the Developer Guide!

Happy selling on PrestaShop Addons!