lechowski / 13.11.2021

PrestaShop File structure for a theme

When creating a theme, you have to think up front of all the various pages and pieces of information that your theme has to handle correctly, in order to offer a complete experience to your customer. Here again, the default theme is a good way to get inspiration, both in the variety of files it features and behaviors it caters for, but also in its code, which you can dive into in order to better understand how a theme works.

First, here is the list of necessary template files (spoiler alert: there are 60 of them. Yes, all are necessary to various PrestaShop features):

File name

Why it is necessary

Other template files used by this template in the default theme
404.tpl Displays when a file cannot be found.  
address.tpl Enables the customer to create a new address.
  • errors.tpl
addresses.tpl Enables the customer to view her current addresses.  
authentication.tpl Enables the customer to log into her account.
  • order-steps.tpl
  • errors.tpl
best-sales.tpl

Displays the best-selling products.
  • product-sort.tpl
  • nbr-product-page.tpl
  • product-compare.tpl
  • pagination.tpl
  • product-list.tpl
breadcrumb.tpl  Displays the category path to the current product/category.
  • breadcrumb.tpl
category-cms-tree-branch.tpl Runs through the CMS categories in order to display them.
  • category-cms-tree-branch.tpl
category-count.tpl Displays the number of products in a category.  
category-tree-branch.tpl Runs through the product categories in order to display them.
  • category-tree-branch.tpl
category.tpl Displays the content of a category: scene, image, text, product comparator, etc.
  • errors.tpl
  • scenes.tpl
  • category-count.tpl
  • product-sort.tpl
  • nbr-product-page.tpl
  • product-compare.tpl
  • pagination.tpl
  • product-list.tpl
  • product-compare.tpl
cms.tpl Displays the content of a CMS page.  
contact-form.tpl Displays the customer contact form.
  • errors.tpl
discount.tpl Displays the list of the customer's vouchers.  
errors.tpl Displays the current error(s).  
footer.tpl Displays the footer.
  • global.tpl
global.tpl Defines several Smarty variables, most notable JavaScript ones.  
guest-tracking.tpl Displays the tracking page for guest customers (visitors with no account).
  • order-detail.tpl
header.tpl Displays the header: HTML doctype, links to CSS files, etc.
  • breadcrumb.tpl
history.tpl Displays all her previous orders to the customer.
  • errors.tpl
identity.tpl Displays and updates the customer's personal information.
  • errors.tpl
layout.tpl Calls upon the main bricks of the theme: header, footer, columns, current template and Live Edit.
  • header.tpl
  • footer.tpl
maintenance.tpl Displays a special page for when the store is in maintenance.  
manufacturer-list.tpl Displays a list of all manufacturers.
  • errors.tpl
  • nbr-product-page.tpl
  • pagination.tpl
manufacturer.tpl Display the products from a single manufacturer.
  • errors.tpl
  • product-sort.tpl
  • nbr-product-page.tpl
  • product-compare.tpl
  • pagination.tpl
  • product-list.tpl
my-account.tpl Displays the customer's account page.  
nbr-product-page.tpl Displays the number of products in the current page.  
new-products.tpl Displays a block with the new products.
  • product-sort.tpl
  • nbr-product-page.tpl
  • product-compare.tpl
  • pagination.tpl
  • product-compare.tpl
  • pagination.tpl
order-address-multishipping-products.tpl Displays the addresses to deliver a product to in a multishipping situation.
  • order-address-product-line.tpl
order-address-multishipping.tpl  
  • order-steps.tpl
  • errors.tpl
  • order-address-multishipping-products.tpl
order-address-product-line.tpl    
order-address.tpl  
  • order-steps.tpl
  • errors.tpl
order-carrier.tpl  
  • order-steps.tpl
  • errors.tpl
order-confirmation.tpl  
  • errors.tpl
  • order-steps.tpl
order-detail.tpl    
order-follow.tpl    
order-opc-new-account.tpl    
order-opc.tpl  
  • shopping-cart.tpl
  • order-address.tpl
  • order-opc-new-account.tpl
  • order-carrier.tpl
  • order-payment.tpl
  • errors.tpl
order-payment.tpl  
  • errors.tpl
  • order-steps.tpl
  • shopping-cart-product-line.tpl
order-return.tpl  
  • errors.tpl
order-slip.tpl    
order-steps.tpl    
pagination.tpl    
password.tpl  
  • errors.tpl
prices-drop.tpl  
  • product-sort.tpl
  • nbr-product-page.tpl
  • product-compare.tpl
  • pagination.tpl
  • product-list.tpl
  • product-compare.tpl
  • pagination.tpl
product-compare.tpl    
product-list-colors.tpl    
product-list.tpl    
product-sort.tpl    
product.tpl  
  • errors.tpl
  • product-list.tpl
products-comparison.tpl    
restricted-country.tpl    
scenes.tpl    
search.tpl  
  • errors.tpl
  • product-sort.tpl
  • nbr-product-page.tpl
  • product-compare.tpl
  • pagination.tpl
  • product-list.tpl
shopping-cart-product-line.tpl    
shopping-cart.tpl  
  • order-steps.tpl
  • errors.tpl
  • shopping-cart-product-line.tpl
sitemap.tpl  
  • category-tree-branch.tpl
  • category-cms-tree-branch.tpl
stores.tpl    
store_infos.tpl    
supplier-list.tpl    
supplier.tpl Makes it possible to display the list of products per supplier.
  • errors.tpl
  • product-sort.tpl
  • nbr-product-page.tpl
  • product-compare.tpl
  • pagination.tpl
  • product-list.tpl

 

Let's diving into the way a theme is organized: folders, files, where they belong and how to handle them correctly

Organization of a Theme

 

  • Organization of a Theme
    • Folders
      • Thumbnail file
      • CSS and Sass
        • CSS
        • Sass / Compass
      • Font
      • Image
      • JavaScript
      • Language
      • The mobile theme
    • Files
      • Templates files
      • Style sheets
      • Image files
      • Tools

 

Folders

The main folders of any PrestaShop theme are those:

  • The /cache folder contains all the temporary files that are generated and reused in order to lighten the server load. The folder is empty by default.
  • The /css folder contains all CSS files.
    • The /sass folder contains all the Sass .scss source files, before they are compiled into the CSS files.
  • The /font folder contains the needed font files.
  • The /img folder contains all images.
  • The /js folder contains all the JavaScript files.
  • The /lang folder contains the theme's translations. Its access rights should be set at CHMOD 666 (for instance), so that the back office translation tool can read and write into it.

The following folders are not directly theme-related, but help you make sure the whole of PrestaShop's feature have a design that is consistent with your theme:

  • The /mails folder contains the templates for the emails that PrestaShop sends (order confirmation, password request, shipping notifications, etc.).
  • The /mobile folder contains the mobile version of the theme.
  • The /modules folder contains the template files for many modules.
  • The /pdf folder contains the template files for the PDF files that PrestaShop generates (invoices, delivery slip, supply orders, etc.).

The root of the folder contains TPL files only, as well as the preview.jpg thumbnail file.

Thumbnail file

The preview.jpg file at the root of the theme's folder is the thumbnail that is used by PrestaShop in its back office theme selector.

It serves as a visual reminder of what the theme is, and you should therefore make it a screenshot rather than your company's logo.

It can have any size – the default theme's is 180*445 pixels.

It must be a JPEG file.

CSS and Sass

CSS

The theme's CSS files are located in the /css folder.

It is recommended to have a common style sheet for global CSS rules: global.css.
Then, each of the controller should have its own CSS file: for instance, product.css for the Product page.

Sass / Compass

Sass and Compass files are optional: you do not need to use these tools to build the CSS files for your back office theme.

If you do use Sass and Compass, we strongly advise to put the source .scss files in the /sass theme, so that other developers can have access to theme and rework them more easily.

From there, you can generate the CSS files in the /css folders from the Sass files in the /sass folder!

Font

The /font folder is optional: it contains the fonts that you chose to use for your theme.

For instance, the default PrestaShop theme uses the Font Awesome font set (http://fortawesome.github.io/Font-Awesome/) for its responsive icons, and therefore has the following files in its /font folder:

  • fontawesome-webfont.eot
  • fontawesome-webfont.svg
  • fontawesome-webfont.ttf
  • fontawesome-webfont.woff

If you do not build your theme with a specific font or icon set in mind, you can skip this folder.

Image

Theme-related images are to be stored in the /img folder.

You can create sub-folder for a better organization. For instance, the default theme has the following subfolders:

  • /icon for simple icons (for instance, those not available in your chosen font set).
  • /jquery for jQuery-specific images.

You can create more if needed.

JavaScript

JavaScript files are to be stored in the /js folder.

Unlike CSS files, we recommend you NOT to have a common/global JavaScript file, nor should you have a single file per controller.

Language

All the translation files are to be stored in the /lang folder.

Files should be named after their ISO 3166-1 alpha-2 code in lowercase: for instance, fr.php.

These files should be generated by PrestaShop integrated translation tool (located in the Localization / Translations menu).