How LESS / CSS Generation works in Pearl Theme & Magento [developer corner]

About LESS/CSS generation. Why is it necessary? 

Quick answer: Performance & Best Practice.

As you probably noticed, Pearl Theme for Magento 2 is very flexible in terms of customizations, with a wide range of available admin options that offers control over functionality, layout and design. In order to implement that we had 2 options:

• classical way where the Theme CSS overwrites the Magento CSS.
• a better way, where we re-use existing Magento variables when making admin option changes. We dynamically generate some of the LESS files based on admin options so they can be merged with Magento LESS files before Magento CSS is generated. This way we can re-use already existing Magento variables, and the CSS generated by Magento is not duplicated and overwritten multiple times.

We know developers may be familiarized with the first approach that was used in most Magento 1 themes, but with the new architecture of Magento 2 we saw the opportunity to improve the CSS code performance. We'll detail below this process so you can have a good understanding of how it works, and easily extend the functionality we already provide if necessary.

1. LESS Generation in Pearl Theme.  

Most of the modules provided with Pearl Theme use their own static LESS files, but a few of the extensions re-use existing Magento variables based on admin settings for performance and best practice considerations. For this reason, once settings that re-use magento variables are changed from Theme admin options, the corresponding LESS files need to be re-generated in order for the new settings to reflect in the store front. 

Command used:

weltpixel:less:generate

This command involves below modules that are part of Pearl Theme:

• WeltPixel_FrontendOptions
• WeltPixel_CustomFooter
• WeltPixel_CustomHeader
• WeltPixel_CategoryPage
• WeltPixel_ProductPage
• WeltPixel_DesignElements

LESS generation can be triggered in 3 ways:

a. via SSH

php bin/magento weltpixel:less:generate

b. by saving the module in admin (this will re-generate the LESS for that module only). 

When one of the mentioned modules settings are saved in admin, an observer containing below details generates for that module a LESS file, for each individual store-view. 

admin_system_config_changed_section_weltpixel_custom_footer ,
admin_system_config_changed_section_weltpixel_custom_header,
admin_system_config_changed_section_weltpixel_frontend_options,
admin_system_config_changed_section_weltpixel_category_page,
admin_system_config_changed_section_weltpixel_product_page

c.  by hitting the Re-Generate Pearl Theme Less/Css from Cache Management page.

Advanced details on LESS files generation:

CategoryPage:    view/frontend/web/css/weltpixel_category_store_STORECODE.less

ProductPage:      view/frontend/web/css/weltpixel_product_store_STORECODE.less

                         view/frontend/web/css/source/_module.less

CustomHeader:   view/frontend/web/css/weltpixel_custom_header_STORECODE.less

CustomFooter:    view/frontend/web/css/weltpixel_custom_footer_STORECODE.less

FrontendOption:  view/frontend/web/css/source/module/_store_STORECODE_extend.less

                         view/frontend/web/css/source/_extend.less

- Above LESS files contain the CSS settings from admin, at store-view level, they are read and parsed when the final CSS generation occurs. For each module, we generate specific store-view  LESS/CSS files.

- For Product Page module we have an additional file called '_module.less' that is necessary for admin options that allow changing page layout, like moving Tabs or other elements in the product page. It is also store-view specific, and the less files are pre-fixated with .theme-pearl.store-view-STORECODE in order to apply 100% only on specific store-view. 

- For Frontend Options module we have an additional file called '_extend.less' which includes each individual module /(per) _store_STORECODE_extend.less, one after the other. This means that if we have multiple store-views, the settings from the last store-view will overwrite the settings from all the other store-views. For some time we had a limitation here and the Frontend Options were only available as Global Settings and not available to change at store-view level. However, we extended the way CSS is generated for this module, reading from '_extend.less' and parsing only the CSS specific for each store view.     

- Frontend Options availability on store-view level. When CSS is generated via SSH or from Magento compilation (deploy) it uses the following structure /pub/static/version1547164043/frontend/Pearl/weltpixel_custom/en_US/css/styles-l.css . Only the Theme Name and Locale are used, but not the STORECODE and for this reason when using Pearl Theme on multiple store-views you need to either use a different Child Theme name or a different Locale (language) as described in this article. How to use Pearl Theme on multiple store-views.

- In order to include these LESS files with the corresponding STORECODE, for each of these modules we use a plugin \Magento\Framework\View\Page\Config\Reader\Head and from there the LESS is included in the page. 

- For generating the LESS files from SSH, for each module we include the observer's class that handles LESS generation in admin. In file di.xml we have the variable generationContainer and in module WeltPixel_Command when the LESS files are generated, classes defined are iterated and for each one less files are generated. If this functionality needs to be implemented in a new module, you just need to implement that Observer and inject it in di.xml in class generationContainer, and command weltpixel:generate:less will automatically generate it. 

Example of di.xml

<type name="WeltPixel\Command\Console\Command\GenerateLessCommand">
  <arguments>
   <argument name="generationContainer" xsi:type="array">
    <item name="WeltPixel_CategoryPage" xsi:type="object">WeltPixel\CategoryPage\Observer\CategoryPageEditActionControllerSaveObserver</item>
    </argument>
  </arguments>
</type>

2. CSS Generation in Pearl Theme.   

Command used:

weltpixel:css:generate --store=STORECODE

This command only works for Pearl Theme and Pearl Child Themes. You cannot generate the CSS for other themes with this command.  This command has only one parameter and that is the store code where you need to generate the CSS files. If you try to generate CSS on a store where Pearl Theme is not activated, an error message is displayed. 

Advanced details on CSS files generation:

CSS generation is implemented in WeltPixel/Command/Model/GenerateCss  -> processContent.

Here you can see what happens when when we trigger the CSS generation :

1. From var/view_preprocessed we delete the pre-generated less files corresponding for our modules, as well as the less files generated for Magento CSS. 

2. We re-generate the CSS files specific for each store-view as well as 2 temporary CSS files styles-l-temp.css si styles-m-temp.css. The temp files were introduced in order to avoid down time when when changing or regenerating the new Magento CSS.

     2.1 The temp files only includes the original Magento less files:  @import ‘styles-l.less’, and           @import ‘styles-m.less’

     2.2 Before the new CSS in generated, the old one is removed. The generation of the two CSS       files may take some time, and for this reason the temporary CSS files are overwriting the old         removed one until the new CSS generation is finished. 

3. We make some gzip compression and CSS minification verifications in order to make sure the new generated CSS comply with this configurations. If enabled we apply gzip compression and/or minification. 

Note: After switching Magento to Production Mode, you need to run the CSS generation command for the store-views where Pearl Theme is activated in order to correctly display the theme CSS. You can do this either from Admin Cache Management section or via SSH.

Note: The LESS/CSS regeneration process (either via the Magento Admin or via the Command Line) also needs to be run in developer mode, if Magento Admin option changes are made to any of the modules in the list above for the changes to be reflected on the frontend.