credits: wuestenigel Colorful chalk pastels, close up via photopin (license). posted on October 2nd, 2017.

My Opinion on Magento Theming and Templating

Because Everyones' Opinion matters!

Recently I received an e-mail from a reader of my blog. He had some basic questions about Magento 2 that at some point every Magento developer faces. For example:

  • What's the best way to create a new theme (PSD to phtml)?
  • Why is the Frontend of Magento so complex?
  • Why do you almost need an module for every simple task?

After years of developing with Magento 1 and 2, like any other Magento Developer, I have an opinion about all of the above. And instead of answering this e-mail, I thought it would make more sense to share my opinion with the community. After all, that's what this blog is for. So let's just start with number #1:

What's the best way to create a new theme?

We've all faced this problem at some point. You've been given a nifty PSD or Sketch file and it needs to be transformed to a working shop. Now there are various things you could do here. But in this article I'll share with you with I think what's the right way:

Inherit from a blank theme

First a short history lesson

It's true that for legacy reasons Magento implemented LESS instead of SASS. According to Alan Kent the only reason that LESS was chosen was that at the time LESS was the only CSS pre-compiler that had a working PHP implementation.

"So why did the pre-compiler had to be written in PHP?" you might ask? Even though there were stable/mature SASS pre-compilers written in Node or Ruby at the time, a requirement for Magento was that they needed to be able to inject PHP code into the pre-compilation process. If you look at the documentation, you'll see that there are various Magento-specific Directives. Also, the static asset compilation is done in PHP and the compilation of CSS is one task of that.

Using LESS

If you want to use LESS, inherit the default Magento blank theme. I would not recommend Luma, because that's already a customization on the existing blank theme, and in my opinion Luma is better used as a reference instead of a base.

Using SASS

If you want to use SASS, inherit the Snowdog Blank Theme. I've worked with this theme before and it's very similar to the default Magento blank theme, only it uses SASS. Note that at some point it kind of looks more like a port from LESS to SASS, so even though you might have SASS, it still has a steep learning curve (as with everything in Magento).


In both cases, if you use LESS or SASS, be aware that you first take your time to template using the variables. Both themes have a significant amount of variables that can be set (or overridden) and in my opinion almost 80% of the template work can already be done by tinkering with these variables. Think about:

  • Font family + sizes
  • Typography
  • Colors
  • Breakpoints
  • Column width
  • Form layout + design
  • etc.

If you really want my opinion I think that if you're new to templating in Magento and your up for your first task, just take your time to learn the variables and see what they do. Also, sourcemaps are your best friend.

The Remaining 20%

For the rest of the templating, beware which LESS/SCSS files you copy to your local theme. For example: if you have a original source file of 1000+ lines and you only need to change a few (that cannot be done with variables), or just add a new rule, don't copy the source file to your theme. Instead make use of the extend-possibility (that both Magento and the Snowdog Blank Theme offer) to just add a small file with only your changes.

But whatever you do:

Don't Create a New Theme from Scratch!

Trust me: if there's one big lesson I can teach you it's "Do it The Magento Way™". I've made this mistake too many times that I thought it would be wise to swim upstream. I created a fresh SASS-theme once only to have it backported to LESS a year later due to future incompatibility (Magento 2.0 to 2.1 anyone?).

Also: Magento has some... quirky stuff going on sometimes. For example: did you know that there are places in the code where the presence of a CSS Transition determines JavaScript functionality? It's true: if the CSS doesn't have a transition, the JavaScript doesn't work! Example #1 Example #2

Avoid Buying a Theme!

When it comes to buying a theme you need to be aware of one very important fact: Themes are mostly made from a commercial point of view. This means that they are designed to be as feature-packed as possible. Most of the time the decision on what theme to buy is done by non-developers (like project managers or store owners). The downside from this is that they are a nightmare for developers to maintain. Because they come with all kind of 'cool' features like:

  • Multiple different color- and font-variations to choose from.
  • Added functionality like mega menu's, images sliders and product labels.

Most of the time the code for these themes are also very poorly written. So you think you have less work by buying an existing template, but you end up having to do more' work to maintain and improve on a badly written template. Some themes even have certain functionality designed like a blog or easy customizable CMS pages, but they don't provide the modules or functionality. So they set expectations in the design, but you as a developer still have to write your own code or search, buy and support another module that does it for you.

Why are templates so complex?

You see this question a lot when people are just starting with Magento. And it's a valid one. Magento has a very complex templating mechanism. It's also a very flexible templating mechanism. But in the end it all comes down to a very basic fact:

Magento has an incredibly steep learning curve

This is just a fact you need to embrace. Know that the first shop you make will be crap. The second one will be a bit better, and so on... In the last couple of years I build a number of Magento shops (in Magento 1 and 2), and I still learn new stuff about Magento every time I create a new project.

And once you master all those tiny tips and tricks about the layout XML, the phtml templates and their correlation to the block classes and all other aspects involved in theming and templating, you'll find that your themes get smaller and more logical every time. For example:

  • Using interceptors to manipulate a block classes' output instead of having to override the template.
  • Creating new containers in your layout and moving stuff smart around instead of having to 'pollute' your templates with layout logic.
  • Use actions or dependency injection in your layout to inject domain logic into templates without having to rewrite them.

And one piece of advice: don't try to implement a different template engine into Magento. I know phtml is ugly and that there are tons of better alternatives out there. But once again: Do it The Magento Way™; it will save you a lot of headaches.

Why do I need an module for almost everything?

It's true that out-of-the-box Magento doesn't provide certain functionality that one might expect from an e-commerce solution. Especially not one so big as Magento. Think about how limited the CMS module is, or how the main navigation on the frontend only includes categories, or things like category tiles.

Although I don't have an exact answer for this as to why Magento doesn't do all this out of the box, I'll try to do my best to tell you what I think the reason is. Because I think it all comes down to separation of domains. Magento tries it's best to take care of the whole e-commerce domain logic, but certain items, like how a navigation should be built and how a category tile should like like are most likely to be the domain logic of your client.

And because this can differ from client to client there are 2 possible paths for Magento to take:

  1. Improve the modules to provide as much customization as possible. But in my opinion this will introduce very bloated modules from which in most cases most store owners will not utilize them to their fullest. But as a developer you do have to support all those features.
  2. Leave the domain specific customizations to the developers. I think that this is what Magento does now: they provide a very basic functionality, but they do provide hooks for developers, like adding attributes to categories and customers or hook into every class and event possible to manipulate.

And this brings us to a very interesting point (that correlates with theming):

Beware of 3rd party modules (as a developer)

Like with themes, modules are even more built from a commercial point of view. This means that 3rd party modules tend to be as feature-packed as possible. I've once searched for a product label module, and I came across a module that even had a built-in label editor that would allow for font customization, animation and even SVG generation. Commercially this is very interesting; you have module for 50 bucks that does everything.

For developers such a module is a nightmare to work with. Those feature-bloated modules are most of the time very poorly written, and some times even obfuscated or even require 3rd party software like IonCube to run, rendering it almost impossible to hook into with interceptors or dependency injection.

Whilst when you want to have a product label, you could also write your own custom module that adds one or two attributes and adds a little template that renders the label for you. Such a module might be a couple of lines to write and is limited to only the functionality the store owner needs. And the less functionality you give a store owner, the less likely they are going to break the site. (Think about pink Comic Sans Hello Kitty animated GIF product labels).

What modules should you install?

There are however some modules that you should never write yourself (for logical reasons):

  • Payment Service Providers: all PSP's come with their own Magento 2 module. Let them build (and support) it.
  • Shipping Providers: same as PSP's: it's their domain, so they're the best capable of writing a module for it.

In Conclusion

This is my opinion on how I think about theming/templating and external themes and modules. I hope that this article gave you some ideas on what to consider when you're going to write your own themes. If you have any ideas or suggestions, please be sure to let me know! I also wrote an article recently about responsible templating: this is the templating technique I use when writing my themes/templates.

Magento 1 Magento 2