ProcessWire 3.0.179 – New Uikit admin theme customization options

ProcessWire 3.0.179 adds great new admin theme customization tools that put you in full control over the admin styles.

This useful addition comes to ProcessWire thanks to a PR (#189) submitted by Bernhard Baumrock. Many of you already know Bernhard from many of his great modules. This core addition is a big one with tons of upsides and opens a lot of new doors that we didn't have before, so this post will attempt to cover many of the details.

This addition means that ProcessWire can now compile Uikit along with your own custom .less files into it at the same time, putting you in control of the admin theme styling. Previously this was something that might only be considered by serious admin theme module developers. But now, anyone can do it just by adding an admin.less file to their /site/templates/ directory. ProcessWire sees the .less file and then recompiles it all automatically!

Not only does this update make it easy to customize the admin theme, but it also opens doors for sharing those customizations and enabling entire new admin theme styles that would have previously required a separate AdminTheme module.

New “rock” style for AdminThemeUikit

Bernhard's PR also adds a new admin style to AdminThemeUikit called the "rock" style. This style is very close to stock Uikit and intended as a starting point to launch your own custom admin styles/themes from. One really useful feature of the Rock style is that [like Uikit] it is based around a primary color, and that primary color is used throughout to style all the different components. This means that you can modify a single LESS variable named @rock-primary with the color you want to use, and it will affect the appearance of the entire admin theme.

Keeping Uikit up-to-date

Beyond what this addition brings to everyone else, it also makes life a lot simpler for me as the maintainer of the core AdminThemeUikit module. Prior to this, I found it difficult to keep the UIkit version up-to-date. I tended to delay anything that might involve having to recompile the LESS files because it usually meant I'd spend a lot of time resolving Node dependencies and related errors. For that reason, rarely did I update the Uikit version or AdminThemeUikit .less files. (Though to Uikit's credit, it has worked quite well even when not up-to-date.)

Bernhard's PR moved all of our .less files around in a manner that completely separates UIkit from AdminThemeUikit's .less files, and replaces all the Node baggage with Wikimedia's PHP .less file parser. Now ProcessWire itself (with the Less module) handles the compilation of Uikit rather than 3rd party dependencies in a different language. Now everything just works, and very smoothly at that.

Because it's now so simple, we're going to be regularly updating the Uikit version in ProcessWire. As of ProcessWire 3.0.179 we are now running the latest version of Uikit, version 3.6.22 from May 18, 2021. Previously we were running Uikit 3.0.0 rc17 from September 2018. That's nearly 3 years worth of versions, so a pretty major upgrade to Uikit. Everything in ProcessWire still seems to work just fine despite the major version change, but please keep an eye out for issues (particularly JS ones) and report them if you come across any.

Now that you understand some of the benefits that this update brings, let's take a closer look at how to use it in practice. You'll need ProcessWire 3.0.179 or newer to proceed.

Three simple steps to customize your admin theme

1. Install the ProcessWire Less module.
2. Specify the “reno” or “rock” base style in /site/config.php.
3. Create and edit /site/templates/admin.less and see your changes in the admin.

June 2022 note: there is now the AdminStyleRock module which can also do this for you.

Either step 2 or 3 can be optional too. Let’s take a closer look at each of these steps below:

1. Install the “Less” module

Download and install the “Less” module from https://processwire.com/modules/less/. This module is required to compile customizations to AdminThemeUikit. If this module is not installed then all of the capabilities described here will not be available.

2. Choose a base style

To proceed, edit the /site/config.php file and specify what base style you want to start from. Currently you can specify either “reno” or “rock”, like in the example below:

$config->AdminThemeUikit('style', 'rock');

Below are descriptions of both base styles:

• Reno: The “reno” base style is the default that you see when using AdminThemeUikit. It is named after Tom Reno (aka Renobird) creator of the AdminThemeReno module. The reno style of AdminThemeUikit attempts to retain much of the color scheme of Tom’s original theme. If you choose to use this style, you can optionally skip step #2 since reno is the default.

• Rock: The “rock” base style is designed to use the default UIkit UI as much as possible and have only one single primary color that can easily be changed without destroying the overall look and feel. This makes it easy to customize for your client’s color scheme. It is named after Bernhard Baumrock who is the creator of this style and the system that enables you to customize AdminThemeUikit in ProcessWire. Because this style is largely stock Uikit, it is intended as a base to build from for your own custom admin style. While it looks quite nice in its stock form, you should also think of it as your blank canvas.

If you selected the “rock” style and want to see what it looks like before moving to the next step, simply reload/refresh the ProcessWire admin in your web browser and it should compile and use it.

3. Create and edit an admin.less file

Create a new LESS file named /site/templates/admin.less for your customizations and add a style or two just to test things out. For example:

div { border: 1px solid red; }

Save the LESS file and the admin theme will automatically recompile and include your change(s). Click reload/refresh in your web browser to start the recompile and see the changes.

• Whether using “reno” or “rock”, you can modify any LESS variable from UIkit or the base style, including all UIkit variables like @global-font-family or @global-margin, and so on… there are hundreds of variables available to you. See the LESS variables reference later in this post.

• If you are using the “rock” base style, you can set the primary color like this: @rock-primary: blue;

• If there is a compile error, you will see it in an admin error notification. In that case, correct the error in your admin.less file, save and refresh again.

• Note that the default compiled CSS file is: /site/assets/admin.css. Do not make changes to this css file directly as ProcessWire may periodically recompile it during version upgrades and such.

Additional notes

• ProcessWire monitors the timestamps of your custom .less file and the resulting .css file. If your .less file is newer than the .css file, it will automatically recompile.

• ProcessWire also monitors for changes to your $config->AdminThemeUikit settings. If any of those settings change, it will automatically recompile.

• If you are using @import statements in your .less file, ProcessWire does not monitor the timestamps of files that are imported. In this case, to trigger a recompile, you should either make some minor change to your admin.less file so the timestamp is updated, or you should use the recompile config setting described in the next section.

• Following a ProcessWire core upgrade, if you are using customizations as described in this post, ProcessWire may automatically recompile the /site/assets/admin.css file in order to bring it up-to-date with the Uikit version or other core AdminThemeUikit changes. As a result, don't make changes directly to that css file, as ProcessWire will sometimes recompile and overwrite it. Instead, always keep any of your own changes in your /site/templates/admin.less file (or other files you @import from it).

LESS variables reference

• Rock style
• Reno style
• Uikit base
• Uikit components

AdminThemeUikit $config settings

The $config->AdminThemeUikit array has various settings you can customize in your /site/config.php file. Below is an example of all settings with their default values:

$config->AdminThemeUikit = [
  'style' => '',
  'recompile' => false,
  'compress' => true,
  'customCssFile' => '/site/assets/admin.css',
  'customLessFiles' => [ '/site/templates/admin.less' ],
];

When modifying a setting from your /site/config.php file, you can specify one or more of them in a PHP array like above, or you can specify any individually using a method call like in the example below. Use whatever definition style you prefer.

$config->AdminThemeUikit('style', 'rock');
$config->AdminThemeUikit('compress', false);

Description of all settings

• style (string)
  Admin theme base style: "reno", "rock", or blank for system default. The default value is blank. When blank, ProcessWire uses the current system default, which is presently “reno”. Advanced option: you may also specify a .less filename relative to the ProcessWire installation root. However, if you are looking to start a theme from scratch, the “rock” style combined with your own /site/templates/admin.less may be what you really want.

• recompile (boolean)
  This is a runtime-only setting that when set to true forces the recompile of the admin theme. When necessary, set this to true for one request, then set it back to false, otherwise it will recompile the admin theme on every admin page load (maybe that’s what you want in some cases too). But in most cases you should not need this setting as ProcessWire already monitors your admin.less file for changes.

• compress (boolean)
  When true, compiled CSS will be compressed or minified so that it consumes less bandwidth. The default value is true. You might choose to set this to false when doing custom admin style development and debugging. Otherwise you should leave this at the default value, which is true.

• customCssFile (string)
  The target custom .css file to compile custom .less file(s) into. The default value is /site/assets/admin.css. If you modify this value, it must be in a location that ProcessWire can write to. Within /site/assets/ is the only directory that is known writable to all ProcessWire installations, though individual installations may vary.

• customLessFiles (array)
  These are the custom .less files that you want to be compiled. The default value is one file: /site/templates/admin.less. The given file(s) must be relative to the ProcessWire installation root directory.

Note for customCssFile and customLessFiles

Chances are you won’t ever need to change these settings, but just in case you do, please make note of the following. Your values for these settings should literally begin with one of the following paths below. Meaning, the literal words, regardless of your actual /site/ directory name (if you happen to be using something different).

• /site/assets/
• /site/templates/
• /site/modules/

This is because the paths above are automatically converted to their actual values at runtime. This ensures the same value works everywhere (development, production, staging, etc.) and regardless of whether the site is running from a subdirectory or not.

Should you choose to use a different location, that’s also okay, but just note that ProcessWire will not perform any runtime conversion on it.

Wrapping up

Big thanks again to Bernhard for his work on this PR which puts AdminThemeUikit on track with its original mission of being an admin theme that one can easily customize and build from. Now it's finally there. We can't wait to see what you all come up with. Thanks for reading! As always, you can read more ProcessWire news and updates at ProcessWire Weekly.

Comments

• 

  cb2004

  • 4 years ago
  • 103

  ★★★★★

  Wow. So good to see PW turning into a community portent and rightly so. We are gifted with some serious forum contributors and now the core is benefiting from them all in the right way. 2021 is looking very exciting

  Reply

• 

  Glenn

  • 4 years ago
  • 53

  Great job Bernard and Ryan! I look forward to trying this out.

  It would also be cool if you could make multiple admin theme variations like:
  - light-mode-blue,
  - dark-mode-blue,
  - light mode-green,
  - dark-mode-green.

  Then the user can select his/her default preference in their user profile settings based on their preference.

  Might even be cool to have a light/dark mode toggle switch displayed somewhere in the in the admin?

  Just some thoughts for down the road... Have a great weekend everyone!

  Reply

  • 

    Jacob

    • 4 years ago
    • 42

    I do something similar to this using settings factory where I let folks select the fonts and colors they want to use on the front end. This could point to a different .less file that is predefined on the backend. Don't see why your couldn't also set a cookie for light and dark and read it on either the front or back. I realize it is a bit of a stopgap to use another settings module to do this, but it is a workaround that may provide you with more flexibility. You can even set it up so that when a client picks a setting for the front end, it automatically does a contrasting theme on the backend.

    Reply