Making your module work with Bootstrap
Version 1.6 of PrestaShop brings a whole new design to the default theme and the software itself. These designs are technically based on the Bootstrap 3 CSS framework (http://getbootstrap.com/), which enables designers and developers to rely on its tools and templates in order to create great and responsive designs.
As a module developer, you should strive to update your module to use Bootstrap, so that they integrate will into the new design.
It's all in the helpers
In itself, it is not complicated: most of the work is handled by PrestaShop's Helper methods, which have been upgrade to use Bootstrap the way it should be. Therefore, the hardest part for you is to move your module's interface code from the old way, where you defined your forms directly in HTML, into the new way that was introduced with PrestaShop 1.5, and which makes the Helpers methods do the heavy lifting.
Before / after
Here is an example of how your module can make use of the Bootstrap framework, through PrestaShop's Helper methods. This example is taken from the blockcart module, and concentrates on two methods:
getContent() (which PrestaShop calls in order to display the module's configuration page), and
displayForm() (which is replaced by
You can see the difference right on Github:
- Old blockcart module: https://github.com/PrestaShop/PrestaShop/blob/62ff976d69f4f5efd3413227f20bed429705e7b7/modules/blockcart/blockcart.php
- "Bootstrapped" blockcart module: https://github.com/PrestaShop/PrestaShop/blob/8144935d764d39d9ed809a1d16c8f452dd9f5591/modules/blockcart/blockcart.php
- The commit where all the work happens: https://github.com/PrestaShop/PrestaShop/commit/c7ebf5ba5daaf54e7c1579c39f9d1d929f0259aa#diff-643b105ace43ea459d923f319583a84c
The changes are minimal, the most important one being that we do not use direct HTML code anymore to output content, but rather use PrestaShop's
displayError() for error messages and
displayConfirmation() for success messages. It is no longer necessary to include
displayName() in the output since this it taken into account by PrestaShop methods.
As you can see,
getContent() no longer calls on
displayForm(), but rather
renderForm(). We could simply rewrite
displayForm()'s code to use the HelperForm methods, but changing the name of the method too helps to make the step to the new way of building forms since PrestaShop 1.5.
Let's first get a reminder of what
displayForm() looked like.
Now, here is the
renderForm() method, which makes pretty much the same thing as
displayFrom(), but in a cleaner, more portable and now responsive way. This is how you should build forms from now on.
For a complete presentation of HelperForm, see this documentation page: http://doc.prestashop.com/display/PS15/HelperForm
The 'bootstrap' variable
One last thing to watch out for: if your module uses a bootstrapped controller, you must add the
bootstrap variable to the module's constructor method.
Indeed, helpers do most of the hard work, but as long as you do not indicate that you are using Bootstrap, your controller will be surrounded by "classic" CSS classes, whereas a single line makes PrestaShop use the "bootstrapped" CSS classes:
This MUST be placed in your module's
__construct() method to work – if you use bootstrapped controllers.
If you are not use a bootstrapped controller, then PrestaShop will wrap it with a specific class, which will do its best to handle the controller as effectively as possible, thus ensuring a certain level of retrocompatibility.
Text field width
If you want to choose the width of your text fields, just add a class on the input, directly in the array described in your HelperForm.
In this example, "xs" is used to choose the width of the field.
There are several available sizes you can use:
- xs: extra small.
- sm: small.
- md: medium.
- lg: large.
- xl: extra large.
- xxl: extra extra large.