Best way to build Bootstrap Themes

Topics: Customizing Orchard, Writing themes
Sep 28, 2015 at 4:01 AM
Edited Sep 28, 2015 at 4:03 AM
I am looking to establish some standard workflow for developing Orchard Themes based on Bootstrap and Orchard Layouts. Eventually I'll turn this into a blog post, but I'd really like some discussion about what I'm currently doing. At the moment it's quite a bit of mucking about and requires some careful thought about where I place things into LESS files. Here is how I currently go about it:

Install Cascade.Bootstrap. I wrote this theme to extend PJS.Bootstrap with two essential things:
  1. Bootstrap support for Orchard.Layouts
  2. Makes it easy to add new 'Bootswatches'
If you want to use standard PJS.Bootstrap then you need to modify it to support Bootstrap for Layouts, and you need to modify the settings template editor to show any newly developed swatches.

A Bootswatch is a Bootstrap customization. You'll find a folder of Bootswatches (in Cascade.Bootstrap/Styles/bootswatch-3.3.5) containing pairs of LESS files called xxx-variables.less and xxx-bootswatch.less. There is also an image folder (Cascade.Bootstrap/Content/swatches) containing a sample image for each swatch. Add a new Bootswatch by cloning an existing one, not forgetting to create a new image as well. It's the image that makes the swatch selectable in the Orchard Admin, so don't forget it. You also need to create a new site-xxx.less file.

You need to pick a starting swatch carefully. It can significantly reduce the amount of work you need to do if you can find an existing swatch that's close to what you want. Then, after you've cloned and renamed it, you'll want to get into the xxx-variables.less file and muck with things like colors, spacing and fonts. I find that I rarely need to change the xxx-bootswatch.less file.

Now you need to go thru your newly created site-xxx.less and change the import statements so that they refer to your new swatches.

I use site_xxx.less for all custom css. Custom css consists of classes that apply to html that's beyond what orchard and bootstrap provide. So if I create a special template to display a Projection, for example, then classes for that would go here.

Nearly every site I do needs a custom Branding.cshtml template to display the company logo just as I want. To avoid modifying the base template I now need to create an Orchard Theme, based on the Cascade.Bootstrap. As far as I know that's the only way I can override the standard Branding.cshtml without modifying the Cascade.Bootstrap theme itself. I also use the derived theme to hold any other custom templates specific to this site (eg for a gallery). But I never use this theme for css -- that goes into the Bootswatch

So now when I configure the site I have to set two things:
  1. In Theme I need to select my custom XXX theme.
  2. In Theme-Bootstrap I need to select the corresponding XXX Bootswatch
I am fairly happy with the results, but I am sure things could be improved and am looking for ways to do so.

Advantages and Disadvantages

The advantages of my way of working are:
  1. No modification of the base theme itself, other then extending it with a new swatch.
  2. Works great with multi tenant sites.
  3. The LESS compiler produces a single css file.
  4. Each site has its own theme, so I can override layouts AND css as needed.
Disadvantages are:
  1. There are quite a few steps involved in creating a new swatch and so it's a bit error-prone, especially when I'm in a hurry.
  2. It can be hard to know where to place a css override. Do I place it in the swatch or do I put it in the site_xxx.less file?
Sep 28, 2015 at 11:07 AM

Using the base theme

In theory you shouldn't need to alter anything in your base theme.

Whenever you come across something you want to change you can just copy that file over to the derived theme and Orchard will use that file instead of the one in the base.

You might feel like you're copying too much if, for example, you just want to tweak a single line and need to copy the whole file, but for me, the point of using the "basedon" themes is to make the upgrade process really simple. When a new version is released you should be able to just drop it in. For best results you might want to use a diff programing (I use KDiff3) to compare the directories of the two themes.

With KDiff3 the 3 means that it can do a 3 way diff. This means you can compare a copy of the new base theme folder, the old base theme folder and your modifications theme so that you can quickly see if the new base theme uses any different techniques that will need to be updated for the modified derived theme to carry on working.

Error-prone steps

Generally I like to write checklists for any kind of complex process. This means that it's repeatable. It also means that anyone else that's on your team can complete a process in your absence. I use Asana for all my task management needs.

Where to override

Again, you shouldn't really alter anything in the base themes swatch files. You are using a less pre-processor so it doesn't matter if there are duplicate rules in the swatch which you then override in your base theme - the less pre-processor will do the heavy lifting and you will get a clean css file outputted at compile time so it won't slow the site or bloat your css file.
Sep 28, 2015 at 11:49 AM
@rtpHarry How do you go about changing a font, a color scheme or some other global theme change? Anyway, I don't actually CHANGE anything in the base theme, I ADD to it, in the form of a new swatch.

Good point about checklists.

I understand the theory, and in fact what you describe is what I used to do until I got tired of spending days sorting all the edge cases after making a basic change to a bootstrap theme.

You can't use Orchard's basedon to override a less file.
Sep 30, 2015 at 12:41 AM
Check out what we've done with PGBBT:
Sep 30, 2015 at 9:59 PM
@Piedone Nice! I have not yet downloaded it but the philosophy is straight 'Orchard' and thus less rough edges than my approach. You do, however, lose the flexibility of the Theme Settings. Also, the explicit LESS imports from the base theme are ugly. I will install it and have a closer look when I have time.
Oct 1, 2015 at 9:38 AM
@bsdr When I have used the PJS.Bootstrap as a base theme I have ignored all the extra "features" like bootswatch.

I prefer to base the site off plain bootstrap and to be honest would prefer if all that clutter wasn't even included.

I basically followed these steps:
  1. Install PJS.Bootstrap
  2. Create a new theme /BasedOn with orchard.exe scaffold
  3. Make my own less structure
  4. When I need to modify anything in the base theme I copy the file over eg .\View\Resources.cshtml to add in some extras
  5. The only time I've had to modify the base theme was for example when I copied over the menu class. I excluded it from the solution in the base theme and then copied over the class to my theme and modified it.
Oct 4, 2015 at 4:24 AM
@piedone I have had a closer look at PGBBT. As I said above PGBBT is pure Orchard in that it uses Bootstrap mixins to build the native Orchard structure classes, and doesn't even expose the standard Bootstrap grid. That has some problems for me:
  1. How do you recommend using it with Orchard.Layouts? You can't use the techniques that apply to standard Bootstrap themes (eg as described here And if you rely on default-grid.css (from Orchard.Layouts), you get a parallel grid implementation with it's own set of media breakpoints etc). I tried importing Bootstrap grid.less, but that mucks up the container nesting.
  2. I frequently use .container .row .col and .offset classes in html to get the layout I want. The need for doing this is reduced now that Orchard.Layouts exists, but I still could not live without access to the native Bootstrap grid.
Oct 17, 2015 at 8:50 PM
Edited Oct 17, 2015 at 8:52 PM
I have overcome one of the major disadvantages of Cascade.Bootstrap by implementing a 'Duplicate' button. This allows the admin/theme developer to quickly and reliably duplicate a chosen swatch and, optionally, create a theme for it. I will also write some docs to make it obvious how to go about modifying the newly created theme. You can download Cascade.Bootstrap (or later) from the Orchard Gallery.