Creating a child theme

Instead of modifying a PrestaShop v1.7 theme directly, it is better to create a child theme that extends the parent theme. This will make upgrading the parent theme easier in the future, since you can overwrite the theme with the newest version without losing your changes. In this tutorial, we'll create a child theme of the Classic theme, but it also works with other themes.

Copying the config directory and preview image

Create a new directory in the themes directory and give it a name without spaces. For this tutorial, we'll use mychildtheme. Copy the config directory from themes/classic to themes/mychildtheme and themes/classic/preview.png to themes/mychildtheme/preview.png.

Linking the child theme to the parent theme

Edit themes/mychildtheme/config/theme.yml, remove the # from the front of line 32:

# use_parent_assets: true

and add the following to the top of the file:

parent: classic

This tells PrestaShop that your theme is a child of the Classic theme and should use its assets.

Changing the theme name, version and author

In themes/mychildtheme/config/theme.yml, change the value of name to the directory name and the value of display_name to your company name or whatever you want to call the theme. Enter your company name, email and URL in the author fields. Theme developers can use the version field to notify customers when a new version of the theme is available.

name: mychildtheme
display_name: My Child Theme
version: 1.0.0
author:
  name: "Nethercott Constructions"
  email: "info@nethercottconstructions.com"
  url: "http://www.nethercottconstructions.com"

Changing the compatibility of the theme

In the compatibility subsection of the meta section of themes/mychildtheme/config/theme.yml, you can change the from and to fields to prevent the theme being used in versions of PrestaShop where it is not compatible.

Changing the theme layouts

If you've added or removed layouts in the layouts directory of the theme, you can make PrestaShop aware of the layouts and change their names and descriptions in the available_layouts section of themes/mychildtheme/config/theme.yml.

Adding CSS and JavaScript libraries

If you want to add additional CSS and JavaScript libraries to the theme, you can uncomment the css and js sections of themes/mychildtheme/config/theme.yml and specify the paths to the libraries inside the theme. Write an all subsection to add the CSS or JavaScript library to all pages in the theme or write a page name like product or category as the subsection to add the CSS or JavaScript to just that page. It is also possible to specify a priority to change the order that libraries are loaded and set the media for CSS files.

Changing PrestaShop's configuration on theme installation

In the global_settings section of themes/mychildtheme/config/theme.yml, it is possible to change PrestaShop's configuration when the theme is installed. For example, in the configuration subsection, you can change any configuration settings when the theme is installed. For example, you can set the thumbnail image format after PS_IMAGE_QUALITY to jpg to use JPEG, png to use PNG only if the base image is in PNG format, or png_all to use PNG for all images.

In the modules subsection, there are to_enable and to_disable subsections that can be used to list which modules to enable and disable on theme installation. In the hooks subsection, it is possible to set the module positions on theme installation. Each subsection is a hook name following by a list of modules to install in that hook. It's a good idea to update these lists whenever you install or reposition modules, so you can simply reinstall the theme in the future if the module hooks need to be restored.

In the image_types subsection, it is possible to set the thumbnail image sizes to be configured on theme installation. Each subsection is the name of the image type and has the width and height in pixels and a scope that specifies whether the image type applies to categories, products, manufacturers, stores or suppliers. Update this list whenever you modify the widths and heights of image types in the Back Office or add new image types to make future reinstallation easier. Note that the cart_default, small_default, medium_default, home_default, large_default, category_default, and stores_default image types must be included in the file.

Changing the default theme settings

In the theme_settings section of themes/mychildtheme/config/theme.yml, it is possible to set the default theme layout in the default_layout subsection and set which layouts to use on different pages in the layouts subsection. The possible values are layout-full-width to display no left or right columns, layout-left-column to display just the left column, layout-right-column to display just the right column, and layout-both-columns to display both the left and right columns. You can also specify any custom layouts you have added.

Overriding the parent theme templates

Once you've finished configuring the child theme, you can override the parent theme templates by copying them to the child theme in the same directory structure. You can also override just a specific block instead of entire file.

For example, to remove the banner image from category pages and only display the category name, create themes/mychildtheme/templates/catalog/listing/category.tpl with the following:

{extends file='parent:catalog/listing/category.tpl'}

{block name='product_list_header'}
  <h1 class="h1">{$category.name}</h1>
{/block}

This code will override the entire product_list_header block with the specified code.

It is also possible to add code above or below the parent code instead of overriding it completely by using the prepend and append keywords. For example, to add a Google map of where your store is located to the top of the contact form, create themes/mychildtheme/templates/contact.tpl with the following:

{extends file='parent:contact.tpl'}

{block name='page_content' prepend}
  Google map code goes here
{/block}

To add the map to the bottom of the contact form instead, just change prepend to append.

Overriding the parent theme assets

Unfortunately, the parent theme assets including CSS, JavaScript and images cannot simply be overridden like the templates. To override the parent theme assets, you'll need to copy themes/classic/_dev to themes/mychildtheme/_dev and then change the files in the css, js and img directories.

You can change the theme colors by editing themes/mychildtheme/_dev/css/partials/_variables.scss and then changing the primary and secondary brand colors:

$brand-primary: #2fb5d2;
$brand-secondary: #f39d72;

After running npm run build to recompile the child theme assets (see Setting up your local environment to learn how), the colors will update throughout the entire theme.