Theme.yml File: The Heart of Prestashop 1.7

January 24, 2017 / Posted in Prestashop, Prestashop 1.7 by David Nyarbutovik
Theme.yml file: The heart of Prestashop 1.7
Download PDF

In this article we are going to explain why the theme.yml file is so important.

But first, please, check out some basic info about .yml. Newbies will find this config validation service quite useful as well: http://www.yamllint.com/.

And here is the table of all PrestaShop pages for your reference, because it is really important to know which page a Page_Identifier corresponds to. You will understand it better while reading further.

Page_identifier url page description page
address /address
addresses /addresses
authentication /login Authorization page
cart /cart
category /index.php?controller=category any category page
cms /index.php?controller=cms
contact /contact-us contact page
discount /discount
guest_tracking /guest-tracking
history /order-history
identity /identity
index / homepage
my_account  /my-account
order /order
order_confirmation /order-confirmation
order_detail /index.php?controller=order-detail
order_follow /order-follow
order_login /order?login=1
order_return /index.php?controller=order-return
order_slip /credit-slip
pagenotfound /page-not-found
password /password-recovery
pdf_invoice /index.php?controller=pdf-invoice
pdf_order_return /index.php?controller=pdf-order-return
pdf_order_slip /index.php?controller=pdf-order-slip
prices_drop /prices-drop
product /index.php?controller=product
register /login?create_account=1
search /search
sitemap /sitemap
stores /stores
supplier /supplier

The file theme.yml is located under the following directory:

/themes/<theme_folder>/config/theme.yml

This file is obligatory for any theme.

Here is also the list of options that must be present in this file.

  • name;
  • display_name;
  • version;
  • name;
  • compatibility.from;
  • available_layouts;
  • image_types.cart_default;
  • image_types.small_default;
  • image_types.medium_default;
  • image_types.large_default;
  • image_types.home_default;
  • image_types.category_default;
  • default_layout.

So, let’s start from the beginning:

1. Theme info

name – a theme directory name  (an obligatory property).

The directory name should match the theme name. Some examples:

display_name – a theme name (an obligatory property).

version: current theme version, use Semantic Versioning (an obligatory property).

2. Theme settings

All the settings below can be changed through an interface in the theme’s back office interface, and only depend on the theme/shop combination.

When the theme.yml file is parsed by PrestaShop, the ‘theme_settings’ configuration key is copied to a file named settings_n.yml, where ‘n’ is the id of the shop where the theme is installed (settings_123456.yml, for instance).

When the configuration is changed through the back office interface, only the settings_n.yml file is updated – the theme.yml file remains unchanged.

Note: what is a PrestaShop layout:

  • all layout files are located under /<theme_folder>/layouts/<layout>.tpl
  • By default any layout is defined by the property default_layout
  • A description for every <layout>can be added to the property available_layouts (example below)

3. Meta info

4. Asset Management

PrestaShop 1.7 has quite an advanced system of Asset Management. Here is an example of connecting css/js files with the help of theme.yml:

In the table below you get the list of files that can are connected to PrestaShop automatically:

Filename ID Priority Comment
theme.css theme-main 0 Most (all?) of your theme’s styles. Should be minified.
rtl.css theme-rtl 900 Loaded only for Right-To-Left language
custom.css theme-custom 1000 Empty file loaded at the very end to allow user to override some simple style.
core.js corejs 0 Provided by PrestaShop. Contains Jquery2, dispatches PrestaShop events and holds PrestaShop logic.
theme.js theme-main 50 Most of your theme’s JavaScript. Should embed libraries required on all pages, and be minified.
custom.js theme-custom 1000 Empty file loaded at the very end, to allow user to override behavior or add simple script.

аssets.css – the property includes the list of pages and the list of connected .css files

conditional syntax:

# – comments
| – or
[] – an optional parameter
<name variables> – a variable value
0..9 – enumeration of available values from 0 to 9

 

аssets.js – the property includes the list of pages and the list of connected .js files

The syntax is quite similar, you just have a few new parameters added there:

 

5. Global Settings

5.1 Configuration of PrestaShop

The property global_settings.configuration is responsible for PrestaShop settings, therefore, when installing a new theme the settings will be changed.

Example:

5.2 Modules

modules.to_enable – All modules below are enabled when the theme is enabled (and installed if needed). They are disabled when the theme is disabled.

modules.to_disable – All modules below are disabled when the theme is enabled. They are re-enabled when the theme is disabled.

Example:

Using hooks you can control the place and output of any specific module on a page and also exclude the pages where that module is not needed. Most significantly, you can also create custom hooks and define the modules that they will connect.

Example:

5.3 Image settings

Enabling the theme will remove all the existing image types.

Therefore, themes MUST declare their image types, and what they apply to.

Example:

5.4 Dependencies

To create a theme we may use various modules, but if you are using some third-party module it should be declared in the list of dependencies which Prestashop will download and install.

Example:



Post a new comment