Magento Commerce tutorial: what’s new for frontend developers?

Magento Commerce brings a host of performance and scalability improvements to the ecommerce platform, but there are a significant number of changes for frontend developers that are worth highlighting.

So what’s new in Magento Commerce versus Magento 1?

• HTML5 support
• CSS3
• LESS over Sass

Some of the improvements include the addition of HTML5 tags built into the templates and CSS3 techniques used in style sheets, as well as a built-in LESS preprocessor.

The Magento team has chosen LESS over Sass due to a stable PHP compiler, which Sass did not have at the time, and to remove the need for users to install package managers such as npm.

On the JavaScript side, a welcome change is the switch from Prototype to jQuery as the primary library. If you’ve worked with Prototype before, you’ll probably welcome the change as much as we do.

So let's get stuck in and take a closer look at the changes!

First though, just a quick disclaimer that this guide was first published ahead of Magento Commerce general availability, and so may be subject to amendments.  

1. Default Themes

Below is a screenshot of the default blank theme. It’s fully responsive out of the box, which is great, and is a mark of Magento’s push for all stores to be responsive rather than mobile or desktop versions of the same site. Although it’s not hugely different from the responsive themes available on Magento 1.x, some of the elements have been shrunk.

For example, there aren’t many changes to the header, but there are some small changes on the category page such as putting products two per row. The product filter on the category page on smaller device widths has been included underneath the products, which puts products higher in content priority, but could become annoying for users wishing to filter products if they have to scroll through all the products on the page first.

Themes in more detail

The theme.xml was introduced in Magento 1.9. This is where you can define the theme, but also define a fallback parent theme.

Below is the Magento Blank example. This is the base theme so it doesn’t have a parent theme to fall back to. There’s also a preview image which is optional, but it is displayed in the admin if you need it. Previously, there were three or four levels of inherents that a theme could return to. In Magento Commerce, there are unlimited levels of parent themes you can inherit from, and they will fall back sequentially until there are no more parents defined.

Below I’ve created a quick theme.xml. I used the Magento Blank theme as a parent and have titled it, which is essentially all you need to begin building your own theme.

In the admin panel, you’ll find a new section labelled Themes under Content. You have to visit this page before you can start using your theme and make it available for selection for your store.

Another new feature is the view.xml, which allows you to configure image sizes globally. Image sizes on category, product, and basket pages can all be defined within this xml file by width, height, and the ratio (see a short example below). In terms of responsive design, the feature isn’t amazing, but is a nice touch.

Composer

Another handy new feature is the ability to package multiple themes in Composer. The screenshot below is an example of the blank theme composer.json file where you are able to define all of the theme’s dependencies. From here, it’s easy to create and share a package for other people to easily install your theme.

File structure

Below is the file structure of the Magento Blank theme, which you’ll notice is quite different from Magento 1.x. Each folder with the naming pattern of <Package>_<Moduleis a component of the site. The skin is included within this as well, and can also be found in app/design/frontend so you don’t require a separate skin folder as you did in Magento 1.x. Everything is contained within this theme (or fallback themes), which is handy to keep everything together – and makes it much easier to exploit your theme, should you wish to.

In the etc folder, you’ll find the view.xml, which is where you can control image sizes. There is also an i18n folder, which is the internationalisation folder and includes all of the translations specific for that theme in .csv files.

Below is an example of a module. Your module includes all the layout information, templates and other assets such JS/CSS associated with that module. In practice you will be creating your own Module folders, in your own theme. If you want to override / extend files in a core module (which is the most common use case) you do so by creating and copying the module structure as it is defined in the core code i.e. app/ code/Magento/Catalog/view/frontend translates toMagento_Catalogin your theme directory (shown in the screenshot below).

So for example to override: app/code/Magento/Catalog/view/frontend/templates/ product/gallery.phtml you would make a file in your own theme folder with the following path: app/design/frontend///Magento_Catalog/ templates/product/gallery.phtml

The same mechanism is used for layout and other assets and the same pattern is used throughout the whole of Magento Commerce. The JS / CSS is contained within the web folder. You can also have images here which are specific to the module.

If you want to completely change the layout structure, you can override it with an override folder. That folder would then include all the layout information for that module, which can be modified to override any parent XML information. However, in Magento Commerce this would be rarely used as layouts now inherit each other, unlike in Magento 1.x where they would override the file further down the fallback tree.

2. Layouts

There is no more local.xmlin Magento Commerce. Magento has instead chosen to have all of the XML within the module. If you want to modify XML for a module, you will have to make a new XML file with the same name in your equivalent theme directory and make the modifications there (remember that all of the attributes and definitions from the original module will be inherited into this file).

Another great feature of the new XML in Magento Commerce is the the move action. Previously if you wanted to move a block somewhere, you had to unset the child and then insert it back in by referencing it further down in the layout XML. In Magento Commerce, you just need one line. To move an element you simply reference it via its name and then enter its destination which can be a container or a block.

Layout handles

Usually, you would have a checkout XML with the different parts of the checkout included with the layout handles. In Magento Commerce, these are separate files. The layout instructions are much more logical now, which I will explain in more detail later in this guide.

Magento currently uses structural and content blocks where the structural blocks act like placeholders. Content blocks then actually contain the content. In Magento Commerce, this has been changed to containers and blocks, which makes a bit more sense.

3. Containers and blocks

A container is a structure without content which holds other blocks and containers. You can specify HTML attributes, HTML tags, if it has an ID, or if it has a class. This means that you can actually create HTML throughout the layout, which isn’t possible with Magento 1.x. By going back to extend and override layouts instead of making changes inlocal.xmlyou create the file in the module for your theme and create the modifications there. When extending a layout, you havereferenceBlockand referenceContainerjust to reference the block or container that you’re modifying.

Below is the layout XML for the basket page, which then generates the most of the HTML for this page. It requires quite a lot of xml, and whether it’s better to follow this process rather than using the template remains to be seen. However, there are numerous advantages of having it in XML vs a template.

4. CSS

In Magento Commerce, adding CSS becomes a lot simpler; it’s just CSS and source. Previously, you would have to add CSS either via XML or by adding the <link> code to the <head> of your document via a template file.

If you are just extending one of the inbuilt themes (such as the blank theme), to customise the CSS you simply override the .LESS file where the original styles you want to change exist, using the equivalent name/path in your own theme. So for example if you wanted to override the checkout CSS, originally defined in the following file: app/design/frontend/Magento/blank/Magento_Checkout/web/css/ source/_module.less

You would copy the contents of this file and create a new file in your own theme with the same path. So, it would look something like this: app/design/frontend///Magento_Checkout/web/css/source/_module.less

Note: If you still want to keep all of these or some of the original files, you need to copy the contents of the original over to your override file. LESS files do not extend from other LESS files further down the fallback tree like layout XML files do.

With regard to workflow for watching changes to your LESS / source files, Magento has a Grunt command in developer mode which compiles after each change and publishes stylesheets to a kind of public folder (and also has live reload). It also has a built-in fallback mechanism so it will search for the LESS files based on the hierarchy you have set up in the theme.

You can also add your own custom CSS files if you wish. This is done in the default_ head_blocks.xmlfile found in theMagento_Themefolder in your theme. 

app/design/frontend///Magento_Theme/layout/ default_head_blocks.xml

However, depending on whether you are using the LESS compiler or not (for example you might be using Sass), you will have to make sure this custom file ends up in the correct place to serve the file in the pub/static folder. However, there are various methods of doing this which will be discussed in later guides.

5. Browser support

Magento Commerce supports IE9 and upwards, which is great. It also supports the latest two versions of Firefox and Chrome as well as Safari 5 and iOS6 Safari.

6. JavaScript

jQuery is now the primary library used for JavaScript in Magento Commerce, tightly coupled with jQuery UI and a whole load of custom jQuery UI widgets you can use throughout your site. All the JavaScript loading is now handled by requireJS, meaning you no longer have to worry about including the script tags yourself, or checking if a file is loaded in the correct order, as RequireJS makes sure all your dependencies are loaded before your code is executed.

7. Documentation

Magento recommends using the base theme as the parent of your custom theme, but from reading feedback from the community so far, it seems a lot of people have preferred to ignore that and just create a whole theme from scratch.

I’d recommend looking at the new documentation and wiki released by Magento and begin to investigate it yourself.

8. Conclusion

Overall, Magento Commerce is definitely a big improvement over the original Magento 1.x.

There are lots of great improvements such as the new modular structure of the code and overriding content / layout XML is now much easier than it was previously.

The improvements in the JavaScript are one of the biggest changes as you can now easily add and extend new and existing JS to meet your needs, without having to worry about loading all the dependencies and files yourself.

The only thing that really still needs a lot of work is the Grunt tasks and LESS compilation of the CSS files (which is not currently very useful). It would also be good to see some themes built in Sass as LESS isn’t to everyone’s taste and isn’t as popular as Sass.