Notice: You are browsing the documentation for PrestaShop 9, which is currently in development.
You might want to read the documentation for the current version, PrestaShop 8. Read the current version of this page
The way 1.7 themes are created is significantly different from the way they were with PrestaShop 1.6. By taking the freedom to rewrite the way themes work according to the latest best-practices, we chose to also work with modern tools. These tools are widely accepted as best-of-breed in the current web development; hence, learning to use them will not only make you more productive in PrestaShop development, but more importantly in web development in general.
While those tools will help all designers and developers in the long run, there is a first step of knowing how to use them, particularly if you have never used such a chain of tools through the command line.
This page is here to help! It will browse through the toolset, so that you know what the rest of the documentation is talking about :)
The PrestaShop developers chose to rely on these tools for the development of the Classic theme:
Along with these tools, PrestaShop 1.7 introduced frameworks and design tools that are must-know:
This document presents each tool, and how they can get you to become a more productive web developer – not just a more productive PrestaShop theme developer!
Many of the tools cited above are to be used through the command line – launching commands in a text-based environment, line after line. While it has the advantage of being very powerful and easy to automate, it is also not intuitive and can be hard to grasp. Luckily, it only takes a handful of commands to understand the power of the command line, and to adopt it for your everyday processes.
Now, as a web-designer, you might be more used to work with graphical interfaces, such as Dreamweaver (for the more WYSIWYG-inclined), or a full-featured text editor, such as Sublime Text, Atom or Brackets (among many other possibilities). Using the command line can supplement this.
All operating systems give you access to a command line interface (CLI).
Windows: It is called the “command prompt”.
You can open it this way:
cmd and press Enter. This will start the cmd.exe program.Try out a few basic commands:
cd .. to go to the parent folder.ping google.com.Note: Windows 10 also includes the Linux-
OS X: It is called the “terminal”.
You can open it this way:
Try out a few basic commands:
cd Downloads to enter a Downloads directory in the current folder; or cd .. to go to the parent folder.ping google.com.Unix/Linux: Oh come on, don’t tell me you don’t already use bash, tcsh, zsh or any other POSIX variation of the concept! :)
There are many default tools and commands which you can use and even combine, but we’re going to use some non-standards tools: npm, Git, Composer and Webpack. Because they are non-standards, you will have to install and configure them first.
Note that you do not HAVE TO use these exactly: you can choose alternatives such as Gulp or Grunt if you’re more familiar with them. We simply use Webpack :)
Git is a version control system, designed to manage decentralized projects with speed and efficiency. In plain English: you can use Git to save the current state of your files (through individual snapshot), in order to return to a previous state should the need arise, among other things.
As a theme designer, tracking all your CSS and JavaScript changes can help you return to a previous snapshot of a file or of the whole project, add new code without breaking the code that’s already working, collaborate with others, and in general keep you from losing your project because of a bad Ctrl-S.
If you have already used the Subversion system, think of Git as a decentralized Subversion (to keep it simple): any machine hosts all versions of all the files, and therefore there is no centralized repository. In effect, the PrestaShop project is mainly hosted on GitHub – but developers also work on it on their own machine.
The PrestaShop Open Source project makes heavy use of Git in order to keep versions of its files. The community can access the official public repository on GitHub: https://github.com/PrestaShop/PrestaShop
As a theme designer, you will need Git in order to retrieve the latest version of PrestaShop 1.7 and its default theme, “Classic”.
Note: You do not need to install or use Git if you are not interested in the latest development of PrestaShop.
Simply download the archive for the latest version of Git (2.23 as of this writing) and install it just like you would do for any other software:
Windows: https://git-for-windows.github.io/
OS X: https://git-scm.com/download/mac
Linux: type apt-get install git (or your distribution’s equivalent).
You can then open your command line and type git --version to check that Git is indeed installed. It should display the version number. You’re good to go!
The PHP ecosystem is made of code packages which can be embedded into bigger projects, or even into other code packages which, in turn, can be embedded, etc. These packages are called dependencies.
Being able to rely on such code packages is great, because it prevents from having to reinvent the wheel every time a well-known feature is needed. On the other hand, dependencies can get problematic: the more a project depends on third-party package, the more it must manage dependency resolution (determining which package to use), autoloading solution (finding the right package and making it available automatically), and keeping all packages up to date (or not, if backward compatibility is an issue).
In short, the modern PHP ecosystem can get complex quite quickly, and Composer is the main way PHP developers manage their dependencies.
Now, why should you care about PHP files when working on a PrestaShop theme? Since you mostly work with theme files (.tpl, .css and .js), .php files are few in your editor, and “PHP dependencies” is something out there, and it seems you’d be better off avoiding them, right?
Thing is, PrestaShop uses Composer to build its own package dependencies. While the Zip archive available for public download is packed with all the required dependencies, the Git-hosted files do not automatically download and install all those dependencies: PrestaShop developers rely on Composer for that, through a composer.json file located at the root of the official Git folder.
In short, you need to use Composer when working with the latest development version from Github, in order to have a complete set of packages.
Yes, that means that if you choose not to retrieve the latest PrestaShop files using Git, but to simply install the latest public archive, then you do not need to worry about Composer. But not using the latest Git version also means that you cannot work with the development version of PrestaShop, and that you rely on the Core developers to release upgraded packages, thus giving you no head start in developing with new features. Your call!
Download the archive for the latest version of Composer (1.9 as of this writing) and install it just like you would do for any other software:
Note: you need to already have the PHP tool installed on your machine. You probably already have it if you’re building websites locally. If not, install WampServer, EasyPHP, XAMPP or any other Windows Apache+PHP+MySQL package there is.
OS X and Linux: in your command line, type these commands:
curl -s https://getcomposer.org/installer | phpsudo mv composer.phar /usr/local/bin/composerTesting it requires using the command line; there is no graphical interface for this tool.
Simply type composer --version to check that it is indeed installed.
npm is a popular package manager, which originates from the JavaScript ecosystem – most precisely, from the Node.js JS runtime environment.
npm is both a command line tool and an online registry (located at https://www.npmjs.com/): you can use it to manage the dependencies (yes, just like Composer), or simply to work with useful packages. It is an extremely useful command to have when building websites, even if you do not use JavaScript or Node.js.
In the context of building PrestaShop themes, npm is mostly used in order to automate tasks – namely, building assets automatically so that you don’t have to.
PrestaShop 1.7 themes are built around “assets”: CSS, JavaScript and image files, which are (or can be) generated from easier-to-manager formats:
All the source files are located in the theme’s _dev folder. The generated files are built using Webpack, a JavaScript module bundler. See below for more information about Webpack.
npm cannot be directly downloaded and installed. It is an integral part of the Node.js tool, therefore you need to download and install Node.js, which in turn will install npm for you.
To download Node.js, please refer to the NodeJS versions table
So, install Node.js on your machine, then test that npm is available:
node -v to check that Node.js is installed.npm -v to check that npm is indeed available.npm is updated much more frequently that Node.js, so chances are that there’s a more recent version available than the one from the Node.js package.
To update your npm:
npm install npm -g: this tells npm to install npm as global package.npm -v to check if the version has indeed changed.Modern website are getting more and more complex, and JavaScript becomes more prominent than ever in the web-development world. As a result there is a lot of code on the client side!
Webpack was built in order to make your life easier, most notably by organizing your code into JavaScript modules. It takes a whole lot of work off your shoulders: you have better things to do than to edit configuration files in order to adjust media files, fonts or URLs.
Before Webpack, many were using task-runners such as Grunt or Gulp in order to organize their code. That lead to a patchwork of configuration, and you had to pay a lot of attention to any change in order to not break everything. Webpack fixes this in an elegant way.
Let’s see where we’re at. So far was have installed:
It’s all fine and dandy, but all of this remains very developer-centric, and there comes a time when you have to think about the user, and optimize for the browser. Fear not, for Webpack is here to save the day! Webpack is a “module bundler”, meaning that it turns your assets into JavaScript modules, and packs them into static assets.
So, the main interest of using Webpack is that it will compile all your styles into a single CSS file. This way, your theme will make only one HTTP request for this single file, and since your browser will cache it for later re-use, it will even download this file only once.
The same goes for your JavaScript code. Instead of loading jQuery along with its community plugins, your own custom plugins and any extra code you might need, Webpack compiles and minifies all this JavaScript code into a single file, which will be loaded once - and cached.
From the moment you have npm installed (see above), Webpack can be installed in a few seconds:
npm install webpack -g