Module of the Month: Colouring outside the lines

Out of the box, SilverStripe, comes with it’s own CMS theme pre applied, in most cases this is more than enough for marketing and content teams to get started.

The UX team at SilverStripe does a great job at ensuring the default CMS theme is both accessible and user friendly to its users. But when it comes to the look and feel of the CMS from a branding and marketing perspective, some organisations and agencies might have a different opinion on the CMS theme. A custom branded CMS is a nice touch to a company’s image.

Whether it is to facilitate the clients wishes to have the CMS styled to match their brand, or as an independent agency, who brands the CMS to reflect their own brand and get a little more feeling of “we made this”.

Wait, hold on, is this really Simon talking? Talking about branding, company image and marketing? I was here for a module!

Hold your horses, yes, it’s really me, and we’ll get to the module below!

In my experience working with different CMS systems, rebranding and styling the CMS was usually quite a frustrating experience. Rebranding the SilverStripe CMS however, is pretty straight forward.

But no matter how straight forward something is, it is still nice if it could be made even easier. Ryan Potter, a well known community member, did just that: the SilverStripe CMS Theme module.

Run the following command:

composer require ryanpotter/silverstripe-cms-theme

and it will make your CMS just that little bit easier to style and theme.

Getting started

The installation is the same as always with composer. And configuring your theme is now a breeze. A YML file will take care of all your settings.

After installation, the demo colours are applied to the CMS

First off is the CMS logo. This can be done through the SiteConfig, or you can set one in the YML file if you don’t want editors to be able to change it.

SilverStripe\SiteConfig\SiteConfig:
  cms_logo: 'mysite/images/cms_logo.png'

Where cms_logo of course is your own filename.

Update from Ryan:
As of May 10th, it's possible to set the width of the logo, so it won't be as massive as the example below by adding cms_logo_width to the yml

I had to manually copy the logo location (mysite/images) to the SilverStripe 4.1 “public” folder, so that’s something to keep in mind. In SilverStripe 4.0 it works right out of the box, same for 4.1 without public folder. 

That was inevitable, either my cow or Rainbow Dash CMS logo for me!

Or a different menu background colour? No problem!

SilverStripe\Admin\LeftAndMain:
  cms_background: '#000000'

A bit dark and gloomy, but this is what a black background looks like

And more settings, as per the documentation. If you know a little bit about CSS and the layout of the SilverStripe CMS, the following should have you nod with an understanding smile:

SilverStripe\Admin\LeftAndMain:
  cms_background: '#0747A6'
  cms_border_color: '#173778'
  cms_color: '#fff'
  cms_hover_background: '#093684'
  cms_active_background: '#173778'
  cms_active_color: '#fff'
  cms_drawer_background: '#0e418e'

Grouping the menu

Sometimes however, your Left menu gets a bit long and it’s becoming a bit unclear how to navigate. Fear not, because the SilverStripe CMS Theme comes with Grouped CMS Menu integration.

If you have a ModelAdmin for multiple separate DataObjects, for example “Categories”, “Tags” and “Topics”, it’s nice to group those under a combined menu item in Left.

SilverStripe\Admin\LeftAndMain:
  menu_groups:
    Categorisation:
      - Vendor-Project-Categories
      - Vendor-Project-Tags
      - Vendor-Project-Topics

This is SilverStripe 4 syntax for namespaced ModelAdmins, e.g.

MyCompany\MyProject\Categories

I don’t have a project I can use to show the grouping, but you’ll have to trust me on my blue eyes that it works :)

Icons

The CMS Theme module also overrides SilverStripe’s default CMS icons with Font Awesome so to give you a bit more flexibility in what icons you want to use. Same as per the standard icon set, you can set it on your ModelAdmin like so:

private static $menu_icon_class = 'fas fa-pencil-alt';

Compatibility

For SilverStripe 4, there’s the 2.x versions that are ready to theme your CMS, whereas the 1.x versions are for SilverStripe 3.

Improvements

As always, any module can be improved. In this particular case, I think it would be nice to be able to set the size of the logo. But there are probably a lot more things you would like to see. So don’t hesitate to create an issue or (especially appreciated) a pull request.

Closing Thoughts

Whether it is your own brand, or your clients brand, it’s now a lot easier to style the CMS to your desire.

So, as per usual, give it a go, enjoy and don’t forget to contribute back!