Understand the theme structure

Before we go any further, it’s probably a good idea to understand the structure of themes. A custom Magento 2 theme is made up of several different files and directories, which are organized into a specific structure.

Let’s open up Blank theme and check that out. It is located at vendor/magento/theme-frontend-blank

We can also look at the Luma theme below it. Even though Luma is a fairly basic theme, it’s still a fully customized theme with some great examples of how to override & extend the blank theme.

Let’s walk through it to find out exactly how a theme is structured.

root

There are also 3 other files in the root of this directory:

1. theme.xml: This file defines basic information about your theme, such as its name, parent theme, and the locations of the other files that make up the theme.
2. registration.php: This file registers your theme with Magento, so that it can be used by the system.
3. composer.json: This file is optional, but recommend as it can be used to define dependencies for your theme, such as third-party libraries or other themes.

Some third-party themes will also have CHANGELOG or LICENSE readme files, that explain changes to the theme and copyright info, respectively. If you are distributing a theme, you may want to include these files with your theme to let users know about changes & updates, or licensing info, respectively.

etc

The etc directory contains a single view.xml file. This file sets widths & heights of product images, relating to where the images are used. For example, when customizing a bundled product, the values for the bundled_product_customization_page page will be used, which means the images will be 140x140. But when images are pulled for the crosssells block, the values defined for cart_cross_sell_products will be used instead, making the images 240x300. These are defined for just about all of the catalog images used throughout a theme, so if you wish to change these image sizes, this is the place to look.

The view.xml file can also set & override variables set in other modules. By setting a value under vars, we can easily override a value set in a template. We’ll cover this in a bit more detail later.

And finally, the exclude node in this file allows us to exclude a file or directory in this theme. This basically allows you to “reset” a theme, and remove any files or directories that you don’t want to load which are set in a parent theme.

i18n

The i18n directory contains translation files. You’re probably already familiar with this concept, but every string in Magento is passed through a translation function. You’ll see this as a __ within a template, a $t variable in templates, and so on. If you define different locales visitors can switch to or use in the frontend, Magento will look up the related translation file from this i18n directory for the related locale. This allows you to easily change a string of text in a simple CSV file, rather than needing to completely override a theme file for a simple text edit. This feature also allows you to translate your store into multiple languages, and we’ll definitely cover this in more detail later on in this course.

Module directories

We’re going to skip all of these module directories for the time being. I’ll come back to them later when we talk about theme fallbacks.

media

The media directory contains files to reference our theme, most notably the image that allows us to see what a theme looks like from the admin. There’s not much else in this directory.

web

The web directory is a main directory that you’ll be using & referencing a lot. This is the directory that references static assets that our theme will be using, such as css, fonts, images & js.

Even though it’s called css, this directory actually contains Less files that will compile down to CSS. We’ll learn more about Less later, but you can think of it as a more powerful version of CSS with some extra superpowers.

The blank theme doesn’t have a fonts directory, but if we check out the Luma theme, we’ll see that this fonts directory contains files related to the custom webfont your theme could be using.

The images directory contains any images relating to your theme on a global level. You’ll notice that the logo.svg file is here, which is the main logo displayed within the frontend of our theme header.

The js directory isn’t often used, as there are usually better places to place your JavaScript. But can contain global JavaScript related to your template that may not really fit in another place. In blank’s example, it contains JavaScript related to the main header nav in Magento.

Now that we understand the files & folders that make up a theme, let’s start setting one up!