Getting started with theming in Magento 2

Today I wanted to go through a short guide to getting started with theming in Magento 2. After its release a couple of weeks ago (correct as of when I’m writing this), I think it’s been high on everyone’s list within the Magento Community (and outside) to give it a test-drive and really see what it can do!

Now I’ve not been looking at this for too long and have only just scratched the surface of the improvements, features & benefits – but from what I’ve seen so far, I like!

One of the first things I wanted to crack was how to create my own theme and start developing a website! There aren’t too many guides out there – the main resource I’ve used is the Magento 2Â dev.docs which are actually very useful. The docs cover almost everything you need. This guide is going to be in 2 parts, as there’s so much to cover.

The reason I’ve put this guide together is that it’s a simple version of the dev.docs and hopefully really straight forward to follow. It doesn’t cover things in massive amounts of detail (I’ll let you learn that for yourself), it just serves as a starting point to theming. So let’s get started.

Pre requisites

Previous Magento coding experience
Some knowledge of Magento 2
Magento 2 fully installed and running smoothly, access to the frontend &Â admin

Installing Magento 2

The first (and most important) step is to get Magento 2 installed. Now this can be quite tricky if you’ve not done it before, but again, there are some great resources which I’d recommend:

I’m not going to go through how to install Magento 2, just how to create a theme and get started theming!

I’ve used all of the above resources to get Magento 2 installed, but for this demo I cloned the Magento 2 repo & followed the guide in the Magento 2 developer docs. I’m using MAMP Pro & PhpStorm and just working locally on my machine for demo purposes.

Creating a theme

Similar to Magento 1, themes are stored in ~/app/design/frontend.Â Inside of the frontend directory, you need to create a Vendor directory (which is essentially the same as a package in Magento 1). Within your Vendor directory, you have to create your theme folder which can be called anything you like really – make it something relevant and meaningful.

You should now have a directory structure which looks like this:

~/app/design/frontend
- Â /<Vendor_Name>
  - /<Theme>

Now your structure is in place, you need to declare your theme so that Magento knows it exists and you can set it as an active theme in the admin.

Create a theme.xml file within the theme folder, on the root. You can use the code inside of the Blank or Luma theme folders. You can also use the code below. Just insert the name of your theme in the <title> tags. You can also specify a parent theme for fallback purposes.

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>INSERT THEME NAME</title>
    <parent>Magento/blank</parent>
</theme>

This is the minimum code you need, but you can also declare a theme image. This is a thumbnail image which shows in the admin on your theme page so you can see a preview of what your theme looks like. To add one of these, add the code below in-between the <theme> XML nodes, underneath the <parent> theme declaration.

<media>
     <preview_image>media/theme-screenshot.jpg</preview_image>
</media>

Change the name of the thumbnail image to that of your filename. Place the image in the following location:

~/app/design/fronted/<Vendor_Name>/<Theme>
- /media
  - /theme-screenshot.jpg

If you don’t have this file in the correct location when you visit yourÂ theme page in the admin, you’ll get an error – so make sure your image is in the right place and named correctly.

Registration.php

The last part in declaringÂ your theme is to add a registration.php file to your theme’s root.

~/app/design/frontend/<Vendor_Name>/<Theme>
- /registration.php

Paste the below code into the file and edit the Vendor Name & Theme parts to match your theme structure.

<?php
/**
* Copyright Â© 2015 Magento. All rights reserved.
* See COPYING.txt for license details.
*/
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::THEME,
    'frontend/<Vendor_Name>/<Theme>',
    __DIR__
);

Composer

Magento themes are distributed as Composer packages so themes include a composer.json file. Creating one of these composer.json file’s within your theme is optional – I’ve not done it for my demo, but you can. Copy the file from the Magento Blank or Luma theme and edit as necessary.

Directory Structure

By this point all the theme declaration & registering is done, you just want to create the directory structure in preparation for yourÂ layout, styleÂ & template files. Below is how your theme directory should look, all highlighted names you will need to create now.

~/app/design/frontend/<Vendor_Name>/<Theme>
- /theme.xml
- /registration.php
- /composer.json
- /media
  - /theme-screenshot.jpg
- /web
  - /css
    - /source
  - /fonts
  - /images
  - /js
- /etc
  - /view.xml
- /Magento_Theme
  - /layout
    - /default.xml

The web folder you’ve created is where your theme’s css, fonts, js & images will go. Magento 2 doesn’t have a skin folder, so these files go in here.

The etc/view.xml file is where you can configure the Magento Catalog image sizes and other things. Copy the etc/view.xml file from one of the default theme’s and edit as necessary.

The last thing you can do before activating your theme, is to add you logo and declare it. The image file can be added to the web/images folder which you created not long ago. This can be whatever file type you like, in this case I’ve used an svg. So to actually tell the theme to use your logo, you create the Magento_Theme/layout folders and add the following code to a default.xml file. Edit to match your requirements.

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceBlock name="logo">
            <arguments>
                <argument name="logo_file" xsi:type="string">images/logo.svg</argument>
                <argument name="logo_img_width" xsi:type="number">300</argument>
                <argument name="logo_img_height" xsi:type="number">300</argument>
            </arguments>
        </referenceBlock>
    </body>
</page>

Activate your theme

Now everything is in place for you to activate your theme. Browse to the admin of your Magento 2 store, and go to ContentÂ > Design > Themes. Make sure your theme appears in this list – if it doesn’t, it hasn’t been declared correctly.

When you can see your theme in the path above, browse to Stores > Configuration > Design. Select the right store scope and then change the theme to your newly created theme.

End of part 1

So that’s part 1 of the tutorial. HopefullyÂ you’ll now have a working theme which you’ve configured & created yourself. The next part of the tutorial, we’ll be covering:

Styling
Layout changes
Editing & Overriding templates

If you have any comments or questions, please leave them below!

Getting started with theming in Magento 2 – Part 1