0

Magento 2 dev docs are very clear about best practices for extending module styles by placing a file named _extend.less in the <theme_dir>/<module_name>/web/css/source directory.

This works perfectly for our frontend theme, however this functionality does NOT work for our adminhtml theme.

I know my adminhtml theme is applied because layout updates are being processed and applied accordingly, e.g., changing the logo on the admin login screen via <my_vendor_dir>/<admin_theme_dir>/Magento_Backend/layout/admin_login.xml works perfectly.

I wish to change the background of the login screen according to best practices, so I create the file <my_vendor_dir>/<admin_theme_dir>/Magento_Backend/web/css/source/_extend.less with the appropriate CSS rule:

.page-layout-admin-login {
  background-color: #fff; 
}

This file is not processed by Magento, nor are changes to this file are noticed by Grunt's watcher in dev mode.

Furthermore, I am able to override CSS/LESS files by creating a file with the same name as the "original" file in my adminhtml theme. For example, if I create the file: <my_vendor_dir>/<admin_theme_dir>/Magento_Backend/web/css/source/_module.less its contents are processed. Of course in this case, I have to copy/paste the contents of the original file which is obviously not desirable as this mandates constantly monitoring the original file for changes i.e., the exact reason why _extend.less feature exists.

Am I missing something? Is this functionality just not supported for adminhtml themes?

| improve this question | |
3

Alright, I've figured it out. _extend.less files are not picked up in adminhtml themes. I wish this was made clear in the documentation, but alas.

I've come up with the following workaround which allows for _extend.less files to be used for applying styles to modules in the admin interface without creating any "hidden dependencies" on Magento's adminhtml theme CSS roots (as would be the case with copy/pasting files into your adminhtml theme).

There is a caveat I should mention for the "add another root CSS source file" method that I've described in this answer. Using this approach, redeclaring variables will not have any effect because of the manner in which LESS files are processed i.e., the root file is processed, LESS files are gathered, and CSS is generated. If you wish to be able to redeclare variables (e.g., @primary__color) you must copy/paste styles.less from the Magento adminhtml theme into your own theme, then append the contents of my extends.less file onto the end of the copy/pasted file. This unfortunately creates what I call a "hidden dependency" on the original file (which is subject to changes in future versions of theme-adminhtml-backend) so it will become your responsibility to check for changes to this file whenever theme-adminhtml-backend is updated, and copy those changes to your local copy.

Firstly, we must add another Root CSS Source File. This is described in the Magento 2 documentation as-so:

The .less files from which the .css files included in layout are compiled. For example, in one of the layout files of the Magento Blank theme, the following .css files are included in the head:

<head>
    <css src="css/styles-m.css"/>
    <css src="css/styles-l.css" media="screen and (min-width: 768px)"/>
    <css src="css/print.css" media="print"/>
</head>

For development mode, using Grunt as a LESS processor, add another Source to the theme declaration in themes.js or local-themes.js depending on how you have your environment setup. Your theme declaration should look something like this:

your_adminhtml_theme_name: {
    area: 'adminhtml',
    name: 'VendorName/theme-name',
    locale: 'en_US',
    files: [
        'css/styles-old',
        'css/styles',
        'css/extends' // we've added this file
    ],
    dsl: 'less'
}

This step is not necessary for server-side compilation mode, as Magento simply looks for corresponding LESS files depending on what CSS files are included in the page head.

That said, this new file (extends.css) must be included in the layout in the same fashion as the other CSS source files for the theme. Since the Magento_Backend module is responsible for this, lets add the layout update to that module in our own adminhtml theme.

Create the file: vendor/theme-adminhtml-themename/Magento_Backend/layout/default.xml

With contents:

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <head>
        <css src="css/extends.css"/>
    </head>
</page>

Now we must create this Root CSS Source File.

Create the file: vendor/theme-adminhtml-themename/web/css/extends.less

With the contents:

// import theme-wide extend file (use this for importing other theme-level extension files)
@import 'source/_extend.less';

// import module-specific extension file e.g. <ModuleDir>/web/css/source/_extend.less
//@magento_import 'source/_extend.less';

Now you can apply changes to Magento modules in the admin interface in the same fashion as you can with a frontend theme by adding an _extend.less file to the module's web/css/source directory. You can also use the <theme-root>/web/css/source/_extend.less to import other theme-wide LESS files as is recommended for frontend themes (e.g., _navigation_extend.less)

I hope this helps someone.

| improve this answer | |
  • 1
    +1 for this explanation. – Sumit Sep 9 '19 at 17:11
  • 1
    thank you @Sumit , I hope it is helpful. I added an explanation of a caveat to my solution that I've noticed. I think its a good case for a PR to community edition to include _extend.less functionality in adminhtml styles.less file. – John Hall Sep 9 '19 at 17:32

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.