An Introduction to MODX Manager Themes

With MODX Revolution 2.3, site builders will gain the ability to quickly change the way the back end Manager looks. Here's an overview of how Manager themes are constructed, and what it takes to start tweaking them.

By Ryan Thrash  |  July 11, 2014  |  5 min read
An Introduction to MODX Manager Themes

It’s no secret that before now, changing the Manager theme in MODX took a lot of effort. With MODX 2.3, you’ll finally be able to quickly change the way the Manager looks. Because, Sass.

Manager Themes in MODX

A considerable effort went—and continues as of writing this—into the way the Manager works with MODX Revolution 2.3. It is infinitely more customizable than its predecessors. This article covers the basics of what you’ll need to know to start exploring creating a Manager Theme today.

Manager Theme Sass Files

To work on a Manager theme, you need to be familiar with Sass. Fear not—this is a very good thing. Using Sass is a excellent way to build and maintain CSS for websites. It's also been adopted by major front end frameworks including Zurb Foundation and Twitter Bootstrap, so chances are you'll run into it sooner than later. In short, Sass makes writing CSS right a lot more straightforward.

However, there are additional dependencies you need to use Sass. The key part of Sass workflows is compiling the Sass you create into proper CSS files for web browsers. The MODX Manager theme itself uses grunt.js and build tasks, but there are many other ways to go about compiling Sass into CSS, including Compass, native applications and more. (see below)

What Goes in a Manager Theme

Manager Themes can be highly customized, replacing every file in the Default theme, or you can just alter a few styles and make selective overrides. You can even change the way the Manager works by including custome ExtJS files, but that is beyond the scope of this introductory overview.

Manager themes are located in the manager/templates/ directory. The MODX Manager automatically scans there, building a select list from the name of any directories it finds in the Back-end Manager > manager_theme system setting. To change your theme, navigate to that system setting, double-click the name, and choose your new theme from those listed.

A custom Manager theme will usually contain the following directories:

  • sass/ – the baseline Sass files used to build the custom styling
  • css/ – where index.css and login.css stylesheets are generated
  • images/ – a copy of all images needed for the theme
  • js/ (optional) – overrides for the overall layout of the MODX Manager, for instance to use a full-height tree menu, instead of it being nested underneath the top navigation, or to change the way the überbar works. note: this is advanced stuff for seasoned ExtJS developers

There are many other directories located in the default Manager theme, most of them being the layout templates, ending in .tpl. You can create custom *.tpl files should you wish, but it's not needed most of the time, and this is probably an advanced area that would be left to experienced back end developers. The exception to this rule might be the security/login.tpl file and the help.tpl files, which affect the login page and the Help page.

The sass/ Directory

The Sass files are probably the most imortant files when it comes to creating a custom theme. For example, a clients might want branded colors and their logo in their Manager. This is where those changes would get made. The main Sass files you'll modify are as follows:

  • _colors-and-vars.scss – probably the first starting point for your MODX Manager theming work. This is where all your baseline colors, font sets and other baseline styles are set that are used throughout the other Sass files. A few changes to the variables here can make a radical difference in the look and feel of the MODX Manager.
  • index.scss – the styles for the MODX Manager after logging in. This includes the majority of the _xxx.scss files inside.
  • login.scss – the styles for the MODX Manager login

The additional Sass files that you may also wish to work with include:

  • _buttons.scss – the button styles used throughout the Manager
  • _forms.scss – the styles that control how forms appear
  • _help.scss – the styles for the MODX help page inside the Manager
  • _navbar.scss – the styles for the top navigation
  • _tabs.scss – the styles for tabs, both horizontal and vertical
  • _tree.scss – the styles for the trees
  • _uberbar.scss – the styling for the überbar search and keyboard navigation tool
  • _xtheme-modx.scss – a custom version of the default ExtJS 3.x styles (in which we'd love your assistance in purging unused styles)

In addition, there are a few mixin and helper/utility Sass files:

  • _box-sizing.scss – a simple box sizing mixin helper file
  • _image-set.scss – a mixin used to create multiple background images
  • _utility.scss – mixins that don't output directly, but that can be used as helpers for things like image replacement, Font Awesome calls, hiding things visually, etc., via Sass extends functions.

Exploring Sass for Beginners

If you're new to working with Sass, you might find the Webdesigntuts+ article, SASS and Compass for Web Designers: Introduction, a great way to get your feet wet. I did. In about half an hour I got comfortable with the concepts for working locally using Live Reload, which makes my Sass explorations almost automagical.

If you really want to get started exploring today:

  1. Grab a copy of the development branch from Github.
  2. In a sandbox on your local development machine, duplicate the manager/templates/default/ directory to a new name like custom.
  3. Copy the _build/templates/default/sass/ directory from step 1 into your new custom theme directory from step 2.
  4. Pick your favorite tool from the tutorial above to compile your Sass files and have fun changing things up.

The Next Steps

I hope you have a better grasp of what goes into a Manager theme and understand why we chose Sass. In a future article, I will show you how you can create a custom theme, without having to use anything other than your web browser, and a couple of quick trips to a command line. Trust me, if I can do it, it's easy! Stay tuned for more … and happy Sassing.